# HLA-Compass MCP Module — Reference

> This document is the canonical in-module reference for MCP-capable HLA-Compass
> modules. It is written for both humans and AI assistants working inside a
> scaffolded module repository.

## Quick Start

```bash
# Authenticate for platform-backed commands
hla-compass auth login --env dev

# Validate and smoke test the scaffold
hla-compass validate
hla-compass test --input examples/sample_input.json
pytest

# Inspect or run the local MCP surface
hla-compass mcp schema
hla-compass mcp serve
```

## What Makes This Template Different

- It is still a normal HLA-Compass module and publishes through the standard image-first flow.
- It also exposes a local MCP workflow through `hla-compass mcp schema` and `hla-compass mcp serve`.
- The generated manifest remains `type: "no-ui"` because the platform execution contract is backend-only.

## Runtime Contract

Every MCP module still extends `hla_compass.Module` and implements `execute()`:

```python
from typing import Any, Dict

from pydantic import BaseModel, Field

from hla_compass import Module


class Input(BaseModel):
    query: str = Field(description="The analysis query to execute")
    limit: int = Field(100, ge=1, le=10000, description="Maximum number of results")


class MCPModule(Module):
    Input = Input

    def execute(self, input_data: Input, context: Dict[str, Any]) -> Dict[str, Any]:
        return self.success(
            results={"query": input_data.query, "matches": [], "total": 0},
            summary={"query": input_data.query, "total_results": 0},
        )
```

## Local Commands

```bash
# Validate manifest and entrypoint wiring
hla-compass validate

# Run a containerized smoke execution
hla-compass test --input examples/sample_input.json

# Unit tests
pytest

# Print the derived MCP tool definition
hla-compass mcp schema

# Start the local MCP server (requires hla-compass[mcp])
hla-compass mcp serve
```

## MCP Notes

- `hla-compass mcp schema` reads `manifest.json` and prints the tool definition derived from the current module.
- `hla-compass mcp serve` imports the module entrypoint from `manifest.json` and serves it locally over stdio transport.
- Install the extra dependencies with `pip install "hla-compass[mcp]>=2.0.2"` if the MCP package is not already available.

## Publish Workflow

The platform builds the container from your module source. No Docker, GHCR, or signing keys required.

```bash
hla-compass validate
hla-compass publish --env dev --scope org --wait
hla-compass publish-status --env dev <publish-job-id>
```

If you do not use `auth use-org`, add `--org-id <org-id>` to `publish`.

## AI Assistant Rules

- Read `manifest.json` and `backend/main.py` together before changing runtime behavior.
- Do not invent manifest fields outside the published schema.
- Treat `hla-compass test` as a container smoke test and `pytest` as the unit-test runner.
- Use the source-upload publish workflow: `hla-compass publish --env dev --scope org --wait`.
