Trace

Trace MCP is a static analysis engine that helps you detect schema mismatches between data producers and consumers. It analyzes how producers expose data and how consumers use it, catching mismatches before they reach runtime and guiding you to align contracts across services, tools, and frontends.

How to use

You use this MCP server by wiring it into your development workflow so clients and producers validate contracts as you build. You can run a quick one-off analysis to compare producer schemas with consumer usage and generate a concise report. For ongoing quality, you can initialize a trace project, start a watcher, and poll for results as you develop, ensuring that producer sureties and consumer expectations stay in sync.

In practice you typically perform three kinds of actions: extract producer schemas from server code, trace how consumer code uses those tools, and compare the results to surface any mismatches. You can also scaffold missing client or server code from the contracts, or annotate code with cross-reference comments to document the contract relationship.

How to install

# Prerequisites
- Node.js (16+ recommended) and npm
- Git

# Install the MCP tooling or run in your project as shown
# Example: clone the MCP server tooling, install dependencies, and build
git clone https://github.com/Mnehmos/trace-mcp.git
cd trace-mcp
npm install
npm run build

Configuration

Configure how the MCP server runs in your client environment. You add an MCP server definition that points to the tracing tool so your client can call it as a local service.

{
  "mcpServers": {
    "trace_mcp": {
      "command": "node",
      "args": ["/path/to/trace-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Security and best practices

Keep your MCP endpoints and tooling behind appropriate access controls. When you run local stdio-based servers, restrict access to your development environment and avoid exposing internal tooling to untrusted networks. Use environment variables for sensitive configuration instead of hard-coding credentials.

Examples and notes

Trace MCP provides a comprehensive set of tools to analyze, generate, and manage contracts. Examples shown in practice include extracting schemas, tracing client usage, comparing producer and consumer contracts, scaffolding client or server code, and adding cross-reference comments to validated pairs.

Typical workflow

1. Quick One-Off Analysis: Run a compare to see producer vs. consumer contracts in a report format.

2. Continuous Validation (Watch Mode): Initialize a trace project, start watching for file changes, and poll for results to stay up to date as you code.

3. Generate Missing Code: Scaffold consumer code from a server schema or scaffold a server stub from consumer usage to fill gaps quickly.

Troubleshooting

If tests fail or mismatches are reported, review the precise producer and consumer locations listed in the mismatch report, adjust the schemas or usage accordingly, and re-run the analysis to verify the fixes. Ensure your tooling paths are correct and that you are running the analysis in the intended project directories.

Notes

The tooling supports a pipeline that extracts schemas, traces usage, and compares results. It also includes scaffolding and contract commenting to help you maintain a clear, verifiable contract between data producers and consumers.

Available tools

extract_schemas

Extract MCP tool definitions from server source code by scanning for server.tool() calls and parsing Zod schemas.

extract_file

Extract MCP tool definitions from a single TypeScript file.

trace_usage

Trace how client code uses MCP tools by finding callTool invocations and tracking accessed properties on results.

trace_file

Trace MCP tool usage in a single TypeScript file.

compare

Full pipeline: extract producer schemas, trace consumer usage, and compare to surface mismatches with a generated report.

scaffold_consumer

Generate client code from producer schemas, including TypeScript functions and hooks to call MCP tools.

scaffold_producer

Generate server stubs from consumer usage to implement MCP tools.

comment_contract

Add cross-reference comments documenting validated producer/consumer pairs in both files.

init_project

Initialize a trace project with a dedicated config and support for watch mode and caching.

watch

Watch project files for changes and auto-revalidate contracts.

get_project_status

Get the status of a trace project including config, cache state, and last validation result.