Skip to main content
Glama
roanbrasil

contract-first-mcp

by roanbrasil
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

contract-first-mcp

A reference MCP server that treats tool schemas as data contracts — versioned, tested for backward compatibility in CI, and hash-pinned against rug pulls.

Built for the MCP 2026-07-28 era: stateless core, explicit handles instead of protocol sessions, and a formal deprecation discipline borrowed from event-driven-architecture schema governance.

Why

MCP servers today evolve their tools the way early Kafka producers evolved their events: silently. A tool renames a field, a client's prompt cache goes stale, an agent starts failing mid-plan — and there is no registry, no compat check, no changelog. This repo shows the minimum viable governance layer:

Discipline

Where

Contract-as-repository: one JSON Schema file per tool version

contracts/<tool>/vN.json

Additive-only evolution, enforced — including the tightenings that remove nothing and still break clients

registry.check_backward_compatible, tests/

Rug-pull detection: canonical SHA-256 of every contract, pinned

pinned_tools.lock.json, list_contracts tool

Stateless state: HMAC-signed handles the model threads between tools

create_workspace_handle / verify_workspace_handle

Fail-fast boot: server refuses to start if a version chain breaks compatibility

server.main()

Human-readable evolution history

TOOL_CHANGELOG.md

Related MCP server: heddle

Run

pip install "mcp>=2.0" jsonschema
python -m contract_first_mcp.server            # stdio

Claude Desktop / any MCP client config:

{ "mcpServers": { "contract-first": {
    "command": "python", "args": ["-m", "contract_first_mcp.server"],
    "env": { "PYTHONPATH": "src", "HANDLE_KEY": "<inject-from-secret-manager>" } } } }

What "additive-only" actually means here

The obvious rules — no removals, no type changes, no new required fields, no enum removals — miss a whole family of breaking changes, because they look for things that disappear. Lowering maximum from 12 to 6 removes nothing, renames nothing, and rejects a payload that worked yesterday. So the checker also fails a version that:

  • raises a lower bound or lowers an upper bound (minimum, maxLength, maxItems, and the rest), including introducing a bound where there was none — unbounded is the loosest bound there is;

  • adds or changes pattern or multipleOf;

  • introduces an enum on a field that was previously open;

  • closes additionalProperties;

  • narrows a type (widening string to ["string", "number"] stays legal);

  • does any of the above inside a nested object or an array's items.

The asymmetry is the whole rule: dropping a constraint is always safe, adding one never is. Each case above has a test that first proves the payload really stops validating, then demands the checker catch it — because a compatibility checker nobody adversarially tested is a comment, not a gate.

Evolving a tool

  1. Copy contracts/<tool>/vN.json to v(N+1).json and make additive changes only (new optional fields, new enum values).

  2. pytest — the compat chain test tells you immediately if the change is breaking.

  3. Regenerate the lockfile:

    python -c "import sys; sys.path.insert(0,'src'); from contract_first_mcp import registry; \
import json,pathlib; pathlib.Path('pinned_tools.lock.json').write_text(\
json.dumps(registry.build_lock(registry.load_contracts()), indent=2)+'\n')"

  4. Record the change in TOOL_CHANGELOG.md.

  5. Breaking change needed? Don't mutate — publish a new tool name (convert_units_v2 as a separate tool), deprecate the old one in its description, and remove it no earlier than the spec's own bar: 12 months.

Security posture

See SECURITY.md. Short version: every input is validated against its schema before touching logic, handles are signed and verifiable, contract hashes are auditable by the client, and nothing in a tool result should ever be treated as instructions.

License

MIT

Available Tools

4 tools
convert_unitsB

Convert between km/mi, kg/lb and °C/°F. Contract: contracts/convert_units (latest: v2).

ParametersJSON Schema
NameRequiredDescriptionDefault
valueYes
to_unitYes
from_unitYes
precisionNo

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, has side effects, or any other behavioral characteristics. The description only states the action without transparency about effects or requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the purpose. The second sentence about a contract reference may be of limited value to an agent but does not detract significantly. Overall, it is concise with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description should provide sufficient context for correct invocation. It omits critical details such as exact unit strings, case sensitivity, handling of unsupported units, and the behavior of the precision parameter. The description is incomplete for an agent to use the tool reliably without additional information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It does hint at valid units (km/mi, kg/lb, °C/°F) which applies to from_unit and to_unit, but it does not explain the value, precision, or how units should be formatted. This is minimal compensation for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: converting between specific unit pairs (km/mi, kg/lb, °C/°F). It uses a specific verb and resource, making the tool's function unambiguous and easily distinguished from the unrelated siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (conversion) but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions or conditions. Since siblings are unrelated, the context is clear, but no explicit when/when-not guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_workspace_handleB

Mint an explicit, signed handle for cross-call state (replaces protocol sessions).

The model passes the handle back to other tools as an argument. It is visible in the conversation on purpose: auditable state beats hidden state.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for disclosing side effects. It mentions the handle is 'visible in the conversation on purpose,' which hints at transparency, but it does not explicitly describe side effects such as creating a persistent resource, modifying workspace state, or any security considerations associated with a 'signed' handle.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of just two sentences, and the information is presented directly without redundancy. The structure is logical, starting with the tool's purpose and then explaining how the result is used.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (one parameter, no output schema, no annotations), the description provides moderate context about the tool's role and usage but lacks details on return value format, potential errors, or side effects. It is not fully complete for a tool that likely creates a resource.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'name' has no description in the schema, and the description does not explain what 'name' refers to (e.g., a handle name, workspace name, or something else). Since schema coverage is 0%, the description needed to clarify this parameter, but it remains ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('mint') and a specific resource ('an explicit, signed handle for cross-call state'). It also provides context by noting this replaces protocol sessions, which helps distinguish its role from potential alternatives, though the term 'cross-call state' is somewhat jargon-heavy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the general usage pattern (the model passes the handle back to other tools as an argument) but does not explicitly state when to use this tool versus sibling tools like list_contracts or verify_workspace_handle. It lacks clear conditions or examples for when this tool is the right choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_contractsA

Introspection: every tool contract version and its pinned SHA-256.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. 'Introspection' and 'list' imply a read-only, non-destructive operation. It discloses the output content (versions and SHA-256) but doesn't explicitly state safety or side-effect absence, though the implication is strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with zero filler. It efficiently communicates purpose and output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter, no-output-schema introspection tool, the description is complete. An agent knows exactly what to expect: a list of contracts with versions and SHA-256 hashes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so schema coverage is trivially 100%. Per rubric baseline for 0 params is 4; the description adds no parameter details because none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: listing every tool contract version and its pinned SHA-256. The verb 'list' and resource 'contracts' are specific, and it distinguishes itself from unrelated siblings like convert_units or create_workspace_handle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description begins with 'Introspection,' which conveys when to use it (for inspecting contracts) without needing explicit alternatives since no sibling does this. It provides clear context, though it doesn't explicitly mention when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_workspace_handleA

Check that a handle was minted by this server and was not tampered with.

ParametersJSON Schema
NameRequiredDescriptionDefault
handleYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It indicates this is a verification operation (likely read-only) but does not disclose the return format (e.g., boolean), potential error conditions (e.g., invalid or foreign handle), or any side effects. While the intent is clear, key behavioral details are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, concise sentence that states the core action and the verification criteria. It is front-loaded and contains no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple one-parameter tool and no output schema, the description is minimal but leaves important gaps: it does not specify the return value (true/false or error), how to handle invalid handles, or the relationship with create_workspace_handle. An agent could call it but would not know what to expect back.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one string parameter named 'handle' with no description. The tool description repeats the term without explaining what a handle is, its format, or how it relates to creation. With 0% schema coverage, the description should compensate but does not, leaving the parameter's meaning underspecified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('check') and resource ('a handle') and clearly states the scope: it verifies that the handle was minted by this server and hasn't been tampered with. This distinguishes it from siblings like create_workspace_handle (which mints) and list_contracts/convert_units (unrelated).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used to verify a handle's authenticity, but it does not explicitly state when to use it (e.g., before relying on a handle) or mention alternatives like create_workspace_handle as the source of valid handles. The guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedconvert_units
    • First observedcreate_workspace_handle
    • First observedlist_contracts
    • First observedverify_workspace_handle
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct role: contract introspection, unit conversion, handle creation, and handle verification. Even the two handle tools are complementary rather than overlapping, with create vs verify being unambiguous.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern: list_contracts, convert_units, create_workspace_handle, verify_workspace_handle. This makes the set predictable and easy for an agent to navigate.

Tool Count5/5

Four tools is a well-scoped size for a focused server: one meta/introspection tool, one utility tool, and a small handle lifecycle pair. No tool feels redundant or out of place.

Completeness4/5

The main gap is that workspace handles can be created and verified but not explicitly revoked or expired. For the stated contract-first scope, this is a minor workaround rather than a critical missing capability.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Trace MCP

    Mnehmos
    F
    license
    A
    quality
    Not graded
    maintenance
    Static analysis engine that detects schema mismatches between data producers (like MCP servers) and consumers (like client code), preventing runtime errors by validating contracts at development time.
    11
    -

  • heddle

    goweft
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables users to define and run MCP tools using declarative YAML configs with built-in trust enforcement, credential brokering, and tamper-evident audit logging.
    14
    MIT

  • Schema Drift Gate MCP

    clauxel
    F
    license
    Not graded
    quality
    D
    maintenance
    Paid remote MCP server that blocks breaking tool-schema changes by verifying schema drift, requiring approvals, and providing compatibility receipts and audit logs.
    -

  • contract-ops-mcp

    DrBaher
    A
    license
    Not graded
    quality
    A
    maintenance
    An MCP server that exposes nine local-first contract-ops CLIs as tools for contract extraction, linting, comparison, conversion, template vaults, and signed-contract vaults, with signing operations strictly human-gated.
    96 npm
    MIT