Skip to content

MCP tools

PyCharter exposes an agent-oriented surface over the Model Context Protocol (MCP). Start a local stdio server with:

pycharter mcp serve

List the available tools (ground truth comes from the runtime registry):

pycharter capabilities --kind agent_tool
pycharter capabilities describe --kind agent_tool --name validate_record

Core tools (overview)

  • fetch_concept_pack — Governed context pack for a single concept (neighbours, relationships, bindings). Policy-filtered by requester role/workspace.
  • list_concepts — Paginated concept listing; optional scheme_id filter.
  • query_context — Case-insensitive substring search over concept names; returns a context pack of matches.
  • validate_record — Validate one JSON object against a governed contract (contract_ref is name or name@version; optional namespace). Invalid records return is_valid: false with diagnostics (not a tool error). Exact offline verification is available with context_fingerprint from preparation.
  • fetch_contract_schema — LLM-ready JSON Schema for a governed contract (pruned keywords, descriptions kept). Optionally wrap as a provider tool schema (provider: anthropic|openai).
  • list_contracts — Summaries of governed contracts; optional namespace and name filters.
  • explain_field — Explain a field’s meaning via its concept bindings and context; returns binding status, concept cards, and a governed context pack.
  • prepare_contract_context — Preparation projection for exact verification (read-only local scope; hosted scope is refused until durable preparation exists).
  • get_agent_conformance — Aggregated conformance metrics snapshot for agent-oriented reporting.
  • list_capabilities / describe_capability — Introspection for steps, extractors, loaders, and agent tools.
  • get_schema — Published JSON Schema for authored artifacts (e.g., the pycharter.io/v2 pipeline manifest).
  • validate_pipeline_config — Validate a pipeline config (object or YAML) without running it; returns {valid, steps} or structured {issues: [...]}.

The full catalog (names, input schema, and — where applicable — output schema) is advertised by the server and may evolve. Use pycharter capabilities --kind agent_tool as the source of truth.

Result shapes

Tool result JSON contracts are bundled under src/pycharter/mcp/schemas/tool_outputs.json and enforced by tests. For example, validate_record returns either:

  • A basic verdict: {is_valid, contract, errors, diagnostics, agent_feedback}, or
  • An exact-verification verdict: {is_valid, verdict, contract, contract_fingerprint, context_fingerprint, direction, diagnostics, agent_feedback, recorded, receipt?}

HTTP transport

The shipped server runs over stdio. A Streamable HTTP transport is planned in the proposals; until then, use stdio for local agents. See:

  • docs/guides/agent-integration-mcp.md
  • docs/reference/agent-tools-policy.md
  • docs/reference/agent-prepared-context.md

Naming consolidation (SURF-2)

Tool and CLI names are being unified across surfaces. This page reflects shipped tools; see docs/proposals/surface-unification-spec.md for the consolidation plan.*** End Patch"}아요assistant to=functions.ApplyPatch.Bunifu to=functions.ApplyPatch.Json Again stray characters appended. Let's reissue patch correctly. We'll resend patch only. We'll be careful. We'll call ApplyPatch again with correct patch only. Let's do it. We'll ensure no extra text. We'll send patch. We'll go. We'll patch now. We'll produce. Let's do. We'll not produce meltdown. We'll just send patch.