MCP server

The Model Context Protocol (MCP) server resolves one Catalog at startup. Every tool uses that catalog for the server lifetime.

Install and start

uv tool install "chartcoach[mcp]"

chartcoach mcp

The default standard-input and standard-output (stdio) transport is launched by the MCP client and has no URL.

Discovery workflow

Start with describe, then choose candidates through SQL or configured search:

1. describe reports catalog identity, table schemas, vocabulary, and profile names.
2. sql selects compact guideline entry candidate IDs.
3. search, when configured, finds candidates through the startup index profile.
4. read returns complete selected entry records and source fields.
5. cite returns the public guideline and source citations.

One schema-first SQL query is:

select id, title
from guidelines
order by id
limit 5

Every tool advertises a concrete success schema plus this error branch:

{
  "error": {
    "code": "lookup",
    "message": "Unknown guideline entry ID: missing",
    "details": {},
    "hints": ["Copy an exact guideline entry ID from a discovery result."]
  }
}

Catalog failures return structured code, message, details, and hints, with the same recovery guidance in text content and MCP isError: true. Invalid tool argument types and limits use the MCP SDK's text error response. Stable catalog codes distinguish lookup, invalid_input, integrity, unavailable_capability, incompatible_profile, embedding_failure, operation_failed, and response_too_large. operation_failed identifies a resource or native operation failure whose cause could not be attributed to invalid input or embedding initialization.

Tools

describe

describe(profile=null) reports the bound catalog. Passing a profile reads its small verified profile.json. The index stays unopened and the embedding function stays unconstructed.

sql

sql(statement, limit=100) accepts one read-only SELECT. limit is from 1 through 100. The result contains typed columns, bounded rows, truncation state, and catalog identity. DuckDB external access is disabled.

read

read(ids, roles=null, source_detail="minimal") accepts 1 through 100 guideline entry IDs and up to 100 section roles. Source detail is none, minimal, or full. The result contains records, entries_digest, manifest_digest, and release_digest.

cite

cite(ids, url_template=...) accepts 1 through 100 guideline entry IDs. The result contains guideline links, formatted source citations, and catalog identity.

search

Set CATALOG_SOURCE to an indexed release and PROFILE to one of its profile names, then start the server:

uv tool install "chartcoach[mcp,index]"

chartcoach mcp \
  --source "$CATALOG_SOURCE" \
  --profile "$PROFILE"

search(text, limit=10, where=null, mode="fts") binds the startup index profile. limit is from 1 through 100 and counts search document hits before guideline deduplication. The result contains matches and match_count. FTS and hybrid scores are relevance. Vector scores are distances. Match excerpts are bounded to 360 characters.

where accepts a LanceDB SQL expression over indexed document columns. A filter-validation error lists those columns. Filters are planned before semantic embedding. For example, role = 'overview' searches entry overviews.

Vector and hybrid search use the persisted LanceDB embedding function. Pass a caller-owned variable file when its embedding model contains $var:name values:

chartcoach mcp \
  --source "$CATALOG_SOURCE" \
  --profile "$PROFILE" \
  --embedding-vars ./embedding-vars.json

chartcoach excludes registry-variable values from its result data, errors, and release artifacts. LanceDB and embedding providers control their own diagnostic logs. Missing-variable errors list the required names. The server reads its variable file once, so restart it after updating that file.

Response budget

Structured tool data is capped at 64 KiB. A complete result that exceeds the budget returns response_too_large with instructions to narrow guideline entry IDs, source detail, SQL columns, or result limits. Selected evidence and SQL scalar values are never silently clipped.

Transports

chartcoach mcp --transport streamable-http

The HTTP transports have no built-in authentication. Keep the default loopback host for local use. Put any wider listener behind an authenticated gateway or private network.

Configuration

Command options override matching environment variables: