Trace MCP (Mnehmos)

跟踪MCP

静态分析引擎，用于检测数据生产者和消费者之间的模式不匹配。

它做什么

跟踪MCP发现以下各项之间不匹配：

• 后端API响应和前端期望
• MCP工具输出和使用它们的客户端代码
• 服务A的事件和服务B的处理程序

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

安装

# 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

配置

添加到您的MCP客户端配置中（例如。， claude_desktop_config.json 或Roo代码设置）：

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

工具参考

Trace MCP提供11种工具，分为三类：

岩心分析工具

代码生成工具

项目管理工具

______________________________________________________________________

工具详细信息

extract_schemas

从服务器源代码中提取MCP工具定义（ProducerSchemas）。扫描 server.tool() 调用并解析它们的Zod模式。

参数：

• rootDir （必填）：MCP服务器源代码根目录
• include：要包含的球形图案（默认值： **/*.ts)
• exclude：要排除的球形图案（默认值： node_modules, dist)

例子：

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

______________________________________________________________________

extract_file

从单个TypeScript文件中提取MCP工具定义。

参数：

• filePath （必填）：TypeScript文件的路径

______________________________________________________________________

trace_usage

跟踪客户端代码如何使用MCP工具。查找 callTool() 调用并跟踪在结果上访问哪些属性。

参数：

• rootDir （必填）：消费者源代码的根目录
• include：球状图案包括
• exclude：要排除的球形图案

______________________________________________________________________

trace_file

在单个TypeScript文件中跟踪MCP工具的使用情况。

参数：

• filePath （必填）：TypeScript文件的路径

______________________________________________________________________

compare

完整的分析管道：提取生产者模式，跟踪消费者使用情况，并对其进行比较以发现不匹配。

参数：

• producerDir （必需）：MCP服务器源目录的路径
• consumerDir （必需）：消费者/客户端源目录的路径
• format：输出格式(json, markdown, summary)
• strict：严格模式-将缺少的可选属性视为警告
• direction：数据流向(producer_to_consumer, consumer_to_producer, bidirectional)

示例输出（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

从生产者模式生成消费者代码。创建正确调用MCP工具的TypeScript函数、React钩子或Zustand操作。

参数：

• producerDir （必需）：MCP服务器源目录的路径
• toolName （必填）：脚手架工具名称
• target：输出格式(typescript, javascript, react-hook, zustand-action)
• includeErrorHandling：包括try/catch错误处理（默认值：true）
• includeTypes：包括TypeScript类型定义（默认值：true）

输出示例：

/**
 * Get character data
 * @trace-contract CONSUMER
 * Producer: ./server/character-tools.ts:23
 */
export async function getCharacter(
  client: McpClient,
  args: GetCharacterArgs
): Promise {
  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

根据消费者使用情况生成生产者模式存根。根据客户端代码调用MCP工具的方式创建MCP工具定义。

参数：

• consumerDir （必填）：消费者源目录的路径
• toolName （必填）：脚手架工具名称
• includeHandler：包含处理程序存根（默认值：true）

输出示例：

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

为已验证的生产者/消费者对添加交叉引用注释。在两个文件中记录合同关系。

参数：

• producerDir （必需）：MCP服务器源目录的路径
• consumerDir （必填）：消费者源目录的路径
• toolName （必填）：已验证工具的名称
• dryRun：不写预览（默认值：true）
• style：评论风格(jsdoc, inline, block)

示例预览：

// 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

使用初始化跟踪项目 .trace-mcp 用于监视模式和缓存的配置目录。

参数：

• projectDir （必需）：跟踪项目的根目录
• producerPath （必填）：生产者/服务器代码的相对路径
• consumerPath （必填）：消费者/客户代码的相对路径
• producerLanguage：语言(typescript, python, go, rust, json_schema)
• consumerLanguage：语言(typescript, python, go, rust, json_schema)

例子：

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

______________________________________________________________________

watch

监视项目文件的更改并自动重新验证合同。

参数：

• projectDir （必填）：根目录 .trace-mcp 配置
• action: start, stop, status，或 poll

行动：

• start：开始监视文件更改
• stop：停止观看
• status：检查当前观察者状态
• poll：获取待处理事件和上次验证结果

______________________________________________________________________

get_project_status

获取跟踪项目的状态，包括配置、缓存状态和上次验证结果。

参数：

• projectDir （必填）：根目录 .trace-mcp 配置

输出示例：

{
  "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 }
}

______________________________________________________________________

典型工作流程

1.快速一次性分析

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

2.连续验证（监视模式）

// 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 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",
});

______________________________________________________________________

路线图

• \[x\] MCP工具模式提取
• \[x\] 消费者使用追踪
• \[x\] 基本不匹配检测
• \[x\] 代码脚手架（消费者和生产者）
• \[x\] 合同意见
• \[x\] 具有自动重新验证功能的监视模式
• \[\]增强的TypeScript接口提取（超越Zod）
• \[\]OpenAPI/GraphQL适配器支持
• \[\]Python/Go/Rust语言支持（部分）

许可证

麻省理工学院