hSUM / docs 0.1.0-alpha.4 / mcp reference

MCP reference

hsum mcp is workspace-dynamic for the managed Codex integration; hsum mcp --binding <UUID> is the binding-pinned manual form. Both speak MCP over stdio and expose exactly four read-only evidence tools.

Tools

Tool	Purpose
`evidence_search`	Search ranked immutable passages with stable citations and live-source state.
`evidence_get`	Resolve a citation to exact indexed bytes and optionally compare the live source hash.
`evidence_project`	Describe the bound filesystem root, indexed extensions, sources, and generation.
`evidence_status`	Report corpus counts, source health, and actionable index or storage problems.

evidence_search

Returns ranked passages, each with a citation. Bounded by a deadline; the response always reports why it stopped.

Representative response shape. IDs, hashes, timestamps, content, and byte counts depend on the indexed project:

{
  "schema_version": "hsum.api.v1",
  "request_id": "dd2ce7eb-0210-4558-ac59-1b8f6d77f0bd",
  "project_id": "bed633a6-3104-4010-8f1d-1742eed33e37",
  "scope_revision": 0,
  "generation": 1,
  "index_epoch": 1,
  "requested_mode": "auto",
  "effective_mode": "lexical",
  "retrievers": ["exact", "lexical"],
  "results": [
    {
      "citation_uri": "hsum://v1/72d90a91-8ae9-4086-b6d1-fc5d57ec99d6/8f6e262c-8776-51f1-a6f6-1f00f59eb5ac/920f61f9-8e4b-4b9d-b956-74be23e208ab?rev=3df02786a19348563b8df57f99c27835d2ea7f6fd963e5d340314993dcf78780#bytes=0-152",
      "index_id": "72d90a91-8ae9-4086-b6d1-fc5d57ec99d6",
      "source_id": "8f6e262c-8776-51f1-a6f6-1f00f59eb5ac",
      "document_id": "920f61f9-8e4b-4b9d-b956-74be23e208ab",
      "revision_sha256": "3df02786a19348563b8df57f99c27835d2ea7f6fd963e5d340314993dcf78780",
      "source_uri": "repo://src/auth.rs",
      "title": "auth.rs",
      "byte_span": { "start": 0, "end": 152 },
      "line_span": { "start": 1, "end": 4 },
      "content": "/// Validate a bearer token against the session store.",
      "content_sha256": "13773ba003aeaba93cd8ac3e70c57a3dce7f77019f3b6a9251ad94bcb227576e",
      "source_updated_at": "2026-07-26T03:07:09.089070016Z",
      "indexed_at": "2026-07-26T03:39:06.0135Z",
      "head_generation": 1,
      "source_state": "metadata_unchanged",
      "untrusted_content": true,
      "score": null,
      "duplicate_citations": []
    }
  ],
  "next_cursor": null,
  "stop_reason": "unique_exhausted",
  "truncated": false,
  "body_bytes": 54
}

Fields worth reading

Field	Why it matters
`stop_reason`	Why candidate collection stopped: `limit_reached`, `unique_exhausted`, `work_budget_exhausted`, or `deadline`. Pagination completeness is reported separately.
`next_cursor`	Non-null when another page exists. Pass it back unchanged to continue the same query and snapshot.
`truncated`	`true` when this page omits fetched results because of the requested page size or response-size ceiling.
`body_bytes`	Total raw content bytes returned in this page.
`effective_mode`	What actually ran. In alpha.4 `auto` resolves to `lexical`.
`score`	`null` unless the request sets `explain: true`; then it contains fused and per-retriever rank details.
`source_state`	Whether the file changed since indexing.
`untrusted_content`	Always `true`. Passages are data, never instructions.

evidence_get

Resolves a citation to exact bytes.

{
  "schema_version": "hsum.api.v1",
  "request_id": "1babdb7a-ec57-4644-9715-e4c5228257ba",
  "requested_citation_uri": "hsum://v1/72d90a91-8ae9-4086-b6d1-fc5d57ec99d6/8f6e262c-8776-51f1-a6f6-1f00f59eb5ac/920f61f9-8e4b-4b9d-b956-74be23e208ab?rev=3df02786a19348563b8df57f99c27835d2ea7f6fd963e5d340314993dcf78780#bytes=0-152",
  "returned_citation_uri": "hsum://v1/72d90a91-8ae9-4086-b6d1-fc5d57ec99d6/8f6e262c-8776-51f1-a6f6-1f00f59eb5ac/920f61f9-8e4b-4b9d-b956-74be23e208ab?rev=3df02786a19348563b8df57f99c27835d2ea7f6fd963e5d340314993dcf78780#bytes=0-152",
  "requested_line_span": { "start": 1, "end": 4 },
  "returned_line_span": { "start": 1, "end": 4 },
  "source_uri": "repo://src/auth.rs",
  "title": "auth.rs",
  "metadata": {},
  "source_updated_at": "2026-07-26T03:07:09.089070016Z",
  "indexed_at": "2026-07-26T03:39:06.0135Z",
  "content": "/// Validate a bearer token against the session store.",
  "body_sha256": "13773ba003aeaba93cd8ac3e70c57a3dce7f77019f3b6a9251ad94bcb227576e",
  "source_state": "content_unchanged",
  "source_hash_verification": "unchanged",
  "untrusted_content": true
}

Compare requested_ against returned_ citations and line spans. get may widen the requested passage to whole stored chunks while staying within max_bytes. Set verify_source_hash: true to report whether the current file still has the indexed content hash.

evidence_project

Call this before interpreting a search miss. It states the filesystem coverage of the project selected when the MCP server started.

{
  "schema_version": "hsum.api.v1",
  "request_id": "aaf27f18-48ad-4572-993e-b21cb8540962",
  "project_id": "bed633a6-3104-4010-8f1d-1742eed33e37",
  "name": "default",
  "scope_revision": 0,
  "root": "/workspace/example",
  "indexed_extensions": [
    ".md", ".markdown", ".txt", ".rs", ".py", ".ts", ".tsx",
    ".js", ".jsx", ".go", ".java", ".kt", ".kts", ".c", ".h",
    ".cpp", ".hpp", ".cc", ".hh", ".cxx", ".rb", ".cs", ".swift",
    ".php", ".scala", ".sh", ".bash", ".sql"
  ],
  "sources": [
    {
      "source_id": "8f6e262c-8776-51f1-a6f6-1f00f59eb5ac",
      "name": "workspace",
      "adapter_kind": "filesystem",
      "logical_uri": "/workspace/example",
      "last_success_at": "2026-07-26T03:39:06.0135Z"
    }
  ],
  "last_successful_generation": 1
}

evidence_status

Use this when a search returns nothing unexpected. It separates an empty or unhealthy corpus from a genuine absence.

{
  "schema_version": "hsum.api.v1",
  "request_id": "45d17701-0abe-4d7b-b060-df52191889c7",
  "index_id": "72d90a91-8ae9-4086-b6d1-fc5d57ec99d6",
  "project_id": "bed633a6-3104-4010-8f1d-1742eed33e37",
  "active_generation": 1,
  "index_epoch": 1,
  "source_count": 1,
  "document_count": 42,
  "passage_count": 318,
  "model_fingerprint": null,
  "degraded_modes": [],
  "health_issues": [],
  "index_problems": [],
  "read_only": true,
  "query_only": true
}

health_issues reports per-source ingest failures. index_problems reports actionable index or storage problems and includes a repair command when one exists. Alpha.2 has no model path, so model_fingerprint is null.

Errors

Failures return a stable machine-readable envelope, not prose:

{
  "code": "NOT_FOUND",
  "subcode": "INDEX_NOT_FOUND",
  "message": "the selected hSUM index is unavailable",
  "retryable": false,
  "next_action": "run hsum context, then initialize or select the intended index",
  "request_id": "e4a44cac-9c23-4f29-a618-cb5895346113"
}

Branch on subcode, not message. Use retryable to decide whether a retry can help. Every subcode is documented under error codes, and offline via hsum help error <SUBCODE>.