Which integrations are available for this server?

Supports GraphQL adapter integration for schema extraction and validation (roadmap feature). Provides partial support for analyzing Python code for schema extraction and usage tracing (roadmap feature). Generates React hooks from MCP tool schemas, providing type-safe client code that correctly consumes MCP server tools. Provides partial support for analyzing Rust code for schema extraction and usage tracing (roadmap feature). Analyzes TypeScript code to extract MCP tool schemas from server implementations and trace tool usage patterns in client code, detecting schema mismatches between producers and consumers. Extracts and validates Zod schemas from MCP tool definitions to ensure type safety between server tool outputs and client expectations.

How do I use Trace MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Trace MCP compare my backend tools with my frontend usage and show me any mismatches" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Trace MCP

by Mnehmos

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Trace MCP

Static analysis engine for detecting schema mismatches between data producers and consumers.

What It Does

Trace MCP finds mismatches between:

Backend API responses and frontend expectations
MCP tool outputs and client code that uses them
Service A's events and Service B's handlers

Producer returns:    { characterClass: "Fighter", hitPoints: 45 }
Consumer expects:    { class: "Fighter", hp: 45 }
Result:              ❌ Mismatch detected before runtime

Installation

# Clone the repository
git clone https://github.com/Mnehmos/trace-mcp.git

# Navigate to the directory
cd trace-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Add to your MCP client configuration (e.g., claude_desktop_config.json or Roo-Code settings):

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

Tools Reference

Trace MCP provides 11 tools organized into three categories:

Core Analysis Tools

Tool	Description
`extract_schemas`	Extract MCP tool definitions from server source code
`extract_file`	Extract schemas from a single file
`trace_usage`	Trace how client code uses MCP tools
`trace_file`	Trace tool usage in a single file
`compare`	Full pipeline: extract → trace → compare → report

Code Generation Tools

Tool	Description
`scaffold_consumer`	Generate client code from producer schema
`scaffold_producer`	Generate server stub from client usage
`comment_contract`	Add cross-reference comments to validated pairs

Project Management Tools

Tool	Description
`init_project`	Initialize a trace project with `.trace-mcp` config
`watch`	Watch files for changes and auto-revalidate
`get_project_status`	Get project config, cache state, and validation results

Tool Details

`extract_schemas`

Extract MCP tool definitions (ProducerSchemas) from server source code. Scans for server.tool() calls and parses their Zod schemas.

Parameters:

rootDir (required): Root directory of MCP server source code
include: Glob patterns to include (default: **/*.ts)
exclude: Glob patterns to exclude (default: node_modules, dist)

Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend/src",
});
// Returns: { success: true, count: 12, schemas: [...] }

`extract_file`

Extract MCP tool definitions from a single TypeScript file.

Parameters:

filePath (required): Path to a TypeScript file

`trace_usage`

Trace how client code uses MCP tools. Finds callTool() invocations and tracks which properties are accessed on results.

Parameters:

rootDir (required): Root directory of consumer source code
include: Glob patterns to include
exclude: Glob patterns to exclude

`trace_file`

Trace MCP tool usage in a single TypeScript file.

Parameters:

filePath (required): Path to a TypeScript file

`compare`

Full analysis pipeline: extract producer schemas, trace consumer usage, and compare them to find mismatches.

Parameters:

producerDir (required): Path to MCP server source directory
consumerDir (required): Path to consumer/client source directory
format: Output format (json, markdown, summary)
strict: Strict mode - treat missing optional properties as warnings
direction: Data flow direction (producer_to_consumer, consumer_to_producer, bidirectional)

Example Output (Markdown):

# Trace MCP Analysis Report

**Generated**: 2025-12-11T02:11:48.624Z

## Summary

| Metric      | Count |
| ----------- | ----- |
| Total Tools | 12    |
| Total Calls | 34    |
| Matches     | 31    |
| Mismatches  | 3     |

## Mismatches

### get_character

- **Type**: MISSING_PROPERTY
- **Description**: Consumer expects "characterClass" but producer has "class"
- **Consumer**: ./components/CharacterSheet.tsx:45
- **Producer**: ./tools/character.ts:23

`scaffold_consumer`

Generate consumer code from a producer schema. Creates TypeScript functions, React hooks, or Zustand actions that correctly call MCP tools.

Parameters:

producerDir (required): Path to MCP server source directory
toolName (required): Name of the tool to scaffold
target: Output format (typescript, javascript, react-hook, zustand-action)
includeErrorHandling: Include try/catch error handling (default: true)
includeTypes: Include TypeScript type definitions (default: true)

Example Output:

/**
 * Get character data
 * @trace-contract CONSUMER
 * Producer: ./server/character-tools.ts:23
 */
export async function getCharacter(
  client: McpClient,
  args: GetCharacterArgs
): Promise<GetCharacterResult> {
  try {
    const result = await client.callTool("get_character", args);
    return JSON.parse(result.content[0].text);
  } catch (error) {
    console.error("Error calling get_character:", error);
    throw error;
  }
}

`scaffold_producer`

Generate producer schema stub from consumer usage. Creates MCP tool definition based on how client code calls it.

Parameters:

consumerDir (required): Path to consumer source directory
toolName (required): Name of the tool to scaffold
includeHandler: Include handler stub (default: true)

Example Output:

import { z } from "zod";

// Tool: get_character
// Scaffolded from consumer at ./components/CharacterSheet.tsx:14
// @trace-contract PRODUCER (scaffolded)

server.tool(
  "get_character",
  "TODO: Add description",
  {
    characterId: z.string(),
  },
  async (args) => {
    // TODO: Implement handler
    // Consumer expects: name, race, level, stats, characterClass
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            name: null, // TODO
            race: null, // TODO
            level: null, // TODO
          }),
        },
      ],
    };
  }
);

`comment_contract`

Add cross-reference comments to validated producer/consumer pairs. Documents the contract relationship in both files.

Parameters:

producerDir (required): Path to MCP server source directory
consumerDir (required): Path to consumer source directory
toolName (required): Name of the validated tool
dryRun: Preview without writing (default: true)
style: Comment style (jsdoc, inline, block)

Example Preview:

// Producer comment:
/*
 * @trace-contract PRODUCER
 * Tool: get_character
 * Consumer: ./components/CharacterSheet.tsx:14
 * Args: characterId
 * Validated: 2025-12-11
 */

// Consumer comment:
/*
 * @trace-contract CONSUMER
 * Tool: get_character
 * Producer: ./server/character-tools.ts:23
 * Required Args: characterId
 * Validated: 2025-12-11
 */

`init_project`

Initialize a trace project with .trace-mcp config directory for watch mode and caching.

Parameters:

projectDir (required): Root directory for the trace project
producerPath (required): Relative path to producer/server code
consumerPath (required): Relative path to consumer/client code
producerLanguage: Language (typescript, python, go, rust, json_schema)
consumerLanguage: Language (typescript, python, go, rust, json_schema)

Example:

const result = await client.callTool("init_project", {
  projectDir: "./my-app",
  producerPath: "./backend/src",
  consumerPath: "./frontend/src",
});
// Creates: ./my-app/.trace-mcp/config.json

`watch`

Watch project files for changes and auto-revalidate contracts.

Parameters:

projectDir (required): Root directory with .trace-mcp config
action: start, stop, status, or poll

Actions:

start: Begin watching for file changes
stop: Stop watching
status: Check current watcher state
poll: Get pending events and last validation result

`get_project_status`

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

Parameters:

projectDir (required): Root directory with .trace-mcp config

Example Output:

{
  "success": true,
  "exists": true,
  "projectDir": "/path/to/project",
  "config": {
    "producer": { "path": "./server", "language": "typescript" },
    "consumer": { "path": "./client", "language": "typescript" }
  },
  "isWatching": true,
  "watcherStatus": { "running": true, "pendingChanges": 0 }
}

Typical Workflow

1. Quick One-Off Analysis

// Compare backend vs frontend, get markdown report
const result = await client.callTool("compare", {
  producerDir: "./backend/src",
  consumerDir: "./frontend/src",
  format: "markdown",
});

2. Continuous Validation (Watch Mode)

// Initialize project
await client.callTool("init_project", {
  projectDir: ".",
  producerPath: "./server",
  consumerPath: "./client",
});

// Start watching
await client.callTool("watch", {
  projectDir: ".",
  action: "start",
});

// Later: poll for results
const status = await client.callTool("watch", {
  projectDir: ".",
  action: "poll",
});

3. Generate Missing Code

// Generate client code from server schema
const consumer = await client.callTool("scaffold_consumer", {
  producerDir: "./server",
  toolName: "get_character",
  target: "react-hook",
});

// Or generate server stub from client usage
const producer = await client.callTool("scaffold_producer", {
  consumerDir: "./client",
  toolName: "save_settings",
});

Roadmap

MCP tool schema extraction
Consumer usage tracing
Basic mismatch detection
Code scaffolding (consumer & producer)
Contract comments
Watch mode with auto-revalidation
Enhanced TypeScript interface extraction (beyond Zod)
OpenAPI/GraphQL adapter support
Python/Go/Rust language support (partial)

License

MIT

Available Tools

11 tools

comment_contractC

Add cross-reference comments to validated producer/consumer pairs. Documents the contract relationship in both files.

ParametersJSON Schema

Name	Required	Description
`producerDir`	Yes	Path to MCP server source directory
`consumerDir`	Yes	Path to consumer source directory
`toolName`	Yes	Name of the validated tool
`dryRun`	No	Preview comments without writing to files (default: true)
`style`	No	Comment style

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations provided, the description must fully disclose behavioral traits. It states it adds comments to files, implying writes, but does not specify if it is destructive, whether it requires prior validation, or what happens on dryRun=false. Important 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?

Two concise sentences that front-load the core purpose. Every sentence adds value with no redundant information. Ideal structure for quick comprehension.

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?

Despite good schema coverage, the description lacks context about the validation prerequisite, the commenting process, dryRun behavior, and file modification implications. For a tool with no output schema and annotations, more complete context is needed.

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

Parameters3/5

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

The input schema has 100% description coverage, so the schema already explains each parameter. The description adds context about 'validated pairs,' but does not provide significant additional meaning beyond the schema. Baseline of 3 is appropriate.

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 the tool adds cross-reference comments to producer/consumer pairs and documents the contract relationship. The verb 'add' and resource 'comments' are specific, and it distinguishes from sibling tools like compare or extract_file. However, it does not clarify what 'validated' means, slightly reducing clarity.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus alternatives. The description implies it is for documenting contract relationships after validation, but it does not mention prerequisites, when not to use it, or compare to sibling tools. Usage context is left implicit.

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

compareC

Full analysis pipeline: extract producer schemas, trace consumer usage, and compare them to find mismatches. Returns a detailed report.

ParametersJSON Schema

Name	Required	Description
`producerDir`	Yes	Path to MCP server source directory
`consumerDir`	Yes	Path to consumer/client source directory
`format`	No	Output format
`strict`	No	Strict mode for comparison
`direction`	No	Data flow direction (default: producer_to_consumer)

TDQS

C2.9/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 mentions the pipeline steps and output format but lacks critical details: whether this is a read-only analysis or modifies data, performance characteristics, error handling, or what 'detailed report' entails. For a complex 5-parameter tool with no annotations, this is insufficient.

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 a single, efficient sentence that front-loads the core purpose. It avoids unnecessary words, though it could be slightly more structured by separating the pipeline steps from the output. Every phrase contributes to understanding the tool's function.

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?

For a complex analysis tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain the report structure, error conditions, or behavioral implications like whether it's safe to run repeatedly. Given the lack of structured data, more detail is needed to guide effective use.

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

Parameters3/5

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

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds minimal value beyond the schema: it implies 'producerDir' and 'consumerDir' are for schemas and usage tracing, and 'format' controls the report output, but doesn't explain parameter interactions or provide additional context. Baseline 3 is appropriate given high schema coverage.

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 the tool performs a 'full analysis pipeline' with specific actions: extract schemas, trace usage, and compare for mismatches, returning a detailed report. It uses specific verbs and identifies the resource as producer/consumer schemas, but doesn't explicitly differentiate from siblings like 'extract_schemas' or 'trace_usage' which handle parts of this pipeline.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. The description mentions the pipeline steps but doesn't specify prerequisites, appropriate contexts, or when to choose this over sibling tools like 'extract_schemas' for schema extraction alone or 'trace_usage' for usage tracing.

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

extract_fileB

Extract MCP tool definitions from a single TypeScript file.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	Yes	Path to a TypeScript file

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 full burden but only states what the tool does, not how it behaves. It doesn't disclose error conditions (e.g., invalid file paths), output format, whether it's read-only or has side effects, performance characteristics, or any constraints. This leaves significant behavioral gaps for a tool that presumably parses and analyzes code.

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?

The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and appropriately sized for a single-parameter tool with straightforward functionality.

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?

For a tool that extracts structured definitions from code (a non-trivial operation), the description is incomplete. With no annotations and no output schema, it doesn't explain what the extracted definitions look like, error handling, or limitations. The context signals indicate moderate complexity (parsing TypeScript), but the description doesn't address this adequately.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents the single parameter 'filePath' as 'Path to a TypeScript file'. The description adds no additional parameter semantics beyond implying the file must contain MCP tool definitions. Baseline 3 is appropriate when the schema does the heavy lifting.

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 specific action ('extract') and resource ('MCP tool definitions') with precise scope ('from a single TypeScript file'). It distinguishes from siblings like extract_schemas (which extracts schemas rather than tool definitions) and trace_file/trace_usage (which trace usage rather than extract definitions).

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

Usage Guidelines2/5

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

No guidance is provided about when to use this tool versus alternatives. While the description implies it works on TypeScript files, it doesn't mention prerequisites (e.g., file must exist), exclusions (e.g., non-TypeScript files), or when to choose other extraction-related siblings like extract_schemas or trace_file.

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

extract_schemasC

Extract MCP tool definitions (ProducerSchemas) from server source code. Scans for server.tool() calls and parses their Zod schemas.

ParametersJSON Schema

Name	Required	Description
`rootDir`	Yes	Root directory of MCP server source code
`include`	No	Glob patterns to include
`exclude`	No	Glob patterns to exclude

TDQS

C2.9/5.0

Behavior2/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 of behavioral disclosure. It mentions scanning and parsing actions but doesn't describe what happens during execution: whether it's read-only, if it modifies files, error handling, performance characteristics, or output format. For a tool with 3 parameters and no annotations, this leaves significant behavioral gaps.

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 appropriately concise with two sentences that directly state the tool's function. It's front-loaded with the core purpose and avoids unnecessary details. However, it could be slightly more structured by explicitly separating purpose from method.

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 the tool has 3 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what the extracted schemas look like, how they're returned, error conditions, or typical use cases. For a tool performing code analysis with multiple configuration options, more context is needed to guide effective usage.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all parameters (rootDir, include, exclude) with descriptions. The description adds no additional parameter semantics beyond implying source code scanning context. It doesn't explain parameter interactions, default behaviors, or examples. Baseline 3 is appropriate when schema does the heavy lifting.

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 the tool's purpose: 'Extract MCP tool definitions (ProducerSchemas) from server source code' with specific verbs 'scans' and 'parses'. It identifies the resource (server source code) and method (scanning for server.tool() calls). However, it doesn't explicitly differentiate from sibling tools like 'extract_file' or 'trace_file' that might also work with source code.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'extract_file' (which might extract files rather than schemas) or 'trace_file' (which might trace usage). There's no context about prerequisites, when this extraction is needed, or what scenarios warrant its use over other tools.

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

get_project_statusB

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

ParametersJSON Schema

Name	Required	Description	Default
`projectDir`	Yes	Root directory with .trace-mcp config

TDQS

B3.2/5.0

Behavior2/5

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

No annotations provided, so the description must disclose behavioral traits. It states the output conceptually but does not mention side effects, permissions, or whether it is read-only. The agent cannot infer safety or side effects without more detail.

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?

The description is a single, well-structured sentence that front-loads the action and resource. It is concise with no extraneous words.

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

Completeness4/5

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

Given the tool's simplicity (one parameter, no output schema), the description provides sufficient context about what is returned. It could optionally mention that no validation or mutation occurs, but overall it is adequate.

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

Parameters3/5

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

Schema description coverage is 100%, and the description adds little beyond the schema's 'Root directory with .trace-mcp config'. The description of the parameter is clear but not enriched by the tool description.

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 the purpose: 'Get the status of a trace project' and specifies what is included (config, cache state, last validation result). It effectively distinguishes from sibling tools like init_project or trace_file, which are more about creation or extraction.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus alternatives. The description lacks prerequisites or context for appropriate usage, leaving the agent to infer from the tool name alone.

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

init_projectA

Initialize a trace project with .trace-mcp config directory. Creates project structure for watch mode and caching.

ParametersJSON Schema

Name	Required	Description
`projectDir`	Yes	Root directory for the trace project
`producerPath`	Yes	Relative path to producer/server code
`consumerPath`	Yes	Relative path to consumer/client code
`producerLanguage`	No	Producer language (default: typescript)
`consumerLanguage`	No	Consumer language (default: typescript)

TDQS

A3.6/5.0

Behavior3/5

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

No annotations provided. Description says it creates project structure, but doesn't disclose idempotency, overwrite behavior, or side effects. Adequate but could be more transparent.

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?

Two concise sentences with no wasted words. Action verb front-loaded. Every sentence adds value.

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?

For a setup tool with 5 parameters and no output schema, description is too minimal. Does not explain return value, what files are created, or what happens if project already exists. Incomplete for effective agent usage.

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

Parameters3/5

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

Schema coverage is 100%; each parameter is documented in schema. Description adds no additional parameter context beyond schema. Baseline score of 3 is appropriate.

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?

Description clearly states verb (initialize) and resource (trace project), and specifies what it creates (.trace-mcp config directory, project structure for watch mode and caching). Distinguishes from siblings like scaffold_consumer which focus on code scaffolding.

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?

Implies use when starting a trace project, but no explicit guidance on when to use vs alternatives like scaffold_consumer or get_project_status. No exclusions or prerequisites mentioned.

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

scaffold_consumerA

Generate consumer code from a producer schema. Creates TypeScript functions, React hooks, or Zustand actions that correctly call MCP tools.

ParametersJSON Schema

Name	Required	Description
`producerDir`	Yes	Path to MCP server source directory
`toolName`	Yes	Name of the tool to scaffold consumer for
`target`	No	Output target format
`includeErrorHandling`	No	Include try/catch error handling
`includeTypes`	No	Include TypeScript type definitions

TDQS

A3.5/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 mentions the tool 'Generates' code, implying a read-only or creation operation, but lacks details on permissions needed, whether it overwrites existing files, error handling behavior, or output format specifics. For a code generation tool with zero annotation coverage, this is a significant gap.

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?

The description is a single, well-structured sentence that efficiently conveys the tool's purpose, output formats, and goal. Every word earns its place with no redundancy or unnecessary details, making it easy to parse and understand quickly.

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 tool's complexity (code generation with multiple output targets) and no annotations or output schema, the description is adequate but incomplete. It covers the 'what' but lacks details on behavioral traits, error handling, or output structure. For a tool with 5 parameters and no structured safety hints, more context would be beneficial.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description does not add any additional meaning beyond what the schema provides (e.g., it doesn't explain the relationship between producerDir and toolName or provide examples). Baseline 3 is appropriate when the schema does the heavy lifting.

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 specific action ('Generate consumer code') and resource ('from a producer schema'), specifying the output formats (TypeScript functions, React hooks, or Zustand actions) and their purpose ('correctly call MCP tools'). It distinguishes from siblings like scaffold_producer by focusing on consumer-side code generation rather than producer/server creation.

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 when needing to create client-side code for MCP tools, but does not explicitly state when to use this tool versus alternatives (e.g., manually writing code or using other scaffolding tools). No exclusions or prerequisites are mentioned, leaving the context somewhat open-ended.

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

scaffold_producerA

Generate producer schema stub from consumer usage. Creates MCP tool definition based on how client code calls it.

ParametersJSON Schema

Name	Required	Description
`consumerDir`	Yes	Path to consumer source directory
`toolName`	Yes	Name of the tool to scaffold producer for
`includeHandler`	No	Include handler stub

TDQS

A3.7/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. It discloses the tool's generative behavior ('Creates MCP tool definition'), but doesn't specify output format, error handling, or side effects like file system changes, leaving gaps for a mutation tool.

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?

Two concise sentences front-load the core purpose and action, with zero wasted words. The structure efficiently communicates the tool's function without redundancy or unnecessary elaboration.

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?

For a 3-parameter mutation tool with no annotations or output schema, the description is minimally adequate but incomplete. It covers the what and how at a high level but lacks details on behavioral traits, output expectations, or integration with sibling tools.

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

Parameters3/5

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

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds no additional parameter semantics beyond implying that consumerDir and toolName relate to analyzing client code, which is already suggested by the schema descriptions.

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 specific action ('Generate producer schema stub from consumer usage') and the resource ('MCP tool definition'), distinguishing it from siblings like scaffold_consumer by focusing on producer-side generation based on client code analysis.

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 when needing to create a tool definition from existing consumer code, but lacks explicit guidance on when to use this versus alternatives like scaffold_consumer or init_project, and doesn't mention prerequisites or exclusions.

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

trace_fileC

Trace MCP tool usage in a single TypeScript file.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	Yes	Path to a TypeScript file

TDQS

C2.9/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 states what the tool does but lacks details on traits like whether it's read-only or destructive, output format (e.g., logs, reports), error handling, or performance implications (e.g., speed, resource usage). This leaves significant gaps in understanding how the tool behaves beyond its basic function.

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?

The description is a single, clear sentence that efficiently conveys the core purpose without any wasted words. It's front-loaded with the essential information, making it easy to parse and understand quickly, which is ideal for conciseness.

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 the complexity of tracing tool usage and the lack of annotations and output schema, the description is insufficiently complete. It doesn't explain what 'trace' entails (e.g., logging calls, analyzing dependencies), what the output looks like, or any behavioral nuances. For a tool with no structured support, more descriptive context is needed to guide effective use.

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

Parameters3/5

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

The input schema has 100% description coverage, with 'filePath' clearly documented as 'Path to a TypeScript file'. The description adds no additional parameter semantics beyond this, such as file format constraints or path validation rules. Given the high schema coverage, a baseline score of 3 is appropriate as the schema handles the heavy lifting.

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 the tool's purpose with a specific verb ('Trace') and resource ('MCP tool usage in a single TypeScript file'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'trace_usage' or 'extract_file', which could have overlapping functionality, preventing a perfect score.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context (e.g., debugging vs. analysis), or comparisons to siblings like 'trace_usage' or 'extract_file', leaving the agent to infer usage scenarios without explicit direction.

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

trace_usageB

Trace how client code uses MCP tools. Finds callTool() invocations and tracks which properties are accessed on results.

ParametersJSON Schema

Name	Required	Description
`rootDir`	Yes	Root directory of consumer source code
`include`	No	Glob patterns to include
`exclude`	No	Glob patterns to exclude

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 full burden but lacks behavioral details. It doesn't disclose whether this is a read-only analysis tool, what permissions are needed, how results are returned, or any performance implications. The description explains the analysis goal but not the operational behavior.

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?

The description is perfectly concise with two clear sentences that each earn their place. The first sentence states the overall purpose, and the second provides specific technical details about what it finds and tracks.

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?

For a tool with 3 parameters, no annotations, and no output schema, the description is incomplete. It explains what the tool analyzes but doesn't cover how results are returned, what format they take, or any behavioral constraints. The agent would need to guess about the output and operational characteristics.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds no additional parameter context beyond what's in the schema, maintaining the baseline score for high schema coverage.

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 specific action ('Trace'), target ('client code uses MCP tools'), and mechanism ('Finds callTool() invocations and tracks which properties are accessed on results'). It distinguishes itself from siblings like trace_file by focusing on tool usage analysis rather than file-level tracing.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like trace_file or other siblings. The description explains what it does but offers no context about appropriate scenarios, prerequisites, or exclusions.

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

watchA

Watch project files for changes and auto-revalidate contracts. Actions: start (begin watching), stop (end watching), status (check state), poll (get pending events).

ParametersJSON Schema

Name	Required	Description	Default
`projectDir`	Yes	Root directory with .trace-mcp config
`action`	No	Watch action (default: start)

TDQS

A3.7/5.0

Behavior3/5

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

No annotations are provided, so the description must fully disclose behavioral traits. It explains the four actions and their purposes, but lacks details on side effects, permissions, error handling, or whether the tool is safe/destructive. The behavior is partially transparent.

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?

The description is a single sentence followed by a bullet-like list of the four actions. It is concise, front-loaded, and contains no extraneous information. Every part earns its place.

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?

The tool has four distinct actions and no output schema. The description does not explain what each action returns (e.g., status output, poll format) or elaborate on 'auto-revalidate contracts'. This leaves gaps for an AI agent to infer behavior. It is complete enough for a simple understanding but lacks depth for robust usage.

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

Parameters3/5

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

The input schema has 100% description coverage, so the schema already documents both parameters (projectDir and action with enum). The description adds minimal extra meaning beyond restating the actions, which are already in the enum descriptions. Baseline 3 is appropriate.

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 watches project files for changes and auto-revalidates contracts, listing four specific actions (start, stop, status, poll). This distinguishes it from all sibling tools, which do not offer file watching.

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 for file monitoring but does not explicitly state when to use it versus alternatives, nor does it provide when-not or prerequisites. Among siblings, no tool duplicates this functionality, so guidelines are adequate but not 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.

11 tool updatesv1.0.0Dec 11, 2025
- First observedcomment_contract
- First observedcompare
- First observedextract_file
- First observedextract_schemas
- First observedget_project_status
- First observedinit_project
- First observedscaffold_consumer
- First observedscaffold_producer
- First observedtrace_file
- First observedtrace_usage
- First observedwatch

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.5/5.0

Scored 2026-04-18 07:50 across 11 tools

Disambiguation4/5

Most tools have distinct purposes, but there is some overlap between 'trace_file' and 'trace_usage' that could cause confusion, as both involve tracing tool usage. However, 'trace_file' is file-specific while 'trace_usage' is broader, and descriptions help clarify this. Other tools like 'extract_file' vs. 'extract_schemas' are well-differentiated by scope.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with clear verb_noun structures, such as 'comment_contract', 'compare', 'extract_file', and 'scaffold_consumer'. There are no deviations in naming conventions, making the set predictable and easy to understand.

Tool Count5/5

With 11 tools, the count is well-scoped for a trace and contract validation server. Each tool serves a specific role in the workflow, from initialization ('init_project') to analysis ('compare') and scaffolding ('scaffold_consumer'), without feeling excessive or insufficient for the domain.

Completeness5/5

The tool set provides complete coverage for the trace and contract validation domain, including project setup ('init_project', 'get_project_status'), extraction ('extract_file', 'extract_schemas'), tracing ('trace_file', 'trace_usage'), analysis ('compare'), scaffolding ('scaffold_producer', 'scaffold_consumer'), documentation ('comment_contract'), and monitoring ('watch'). No obvious gaps exist in the lifecycle.

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Fixzi — MCP & API Schema Drift Monitor
io.github.rohitcodilya
Monitor MCP servers, API contracts and AI outputs for schema drift. Alerts on breaking changes.
API Testing Monitoring
21
MCP Surface Lint A
io.github.DLeibner
Statically audits MCP tool surfaces for token cost, schema quality, and design issues.
Developer Tools Code Analysis
11
mcp-spec-compliance-mcp
io.github.CSOAI-ORG
MCP Spec Compliance MCP — audits any MCP server.json against the official Model Context Protocol
Testing & QA Tools Developer Tools
2
Agentic Platform A
io.github.andysalvo
Free MCP tools: the only MCP linter, health checks, cost estimation, and trust evaluation.
Developer Tools Monitoring Observability
31