mnehmos.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
REST endpoints and HTTP client calls
GraphQL schemas and Apollo Client hooks

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

Features

Core Capabilities

Feature	Description
Schema Extraction	Extract schemas from MCP tools, OpenAPI, TypeScript, tRPC, REST endpoints, GraphQL
Usage Tracing	Track how client code consumes schemas via property access patterns
Mismatch Detection	Compare producer schemas against consumer expectations
Code Generation	Scaffold consumer code from producer schemas (and vice versa)
Watch Mode	Continuous validation on file changes

Phase 2 Capabilities

Feature	Description
Pattern Matcher	Extensible pattern detection supporting call, decorator, property, export, and chain patterns
Import Resolution	Cross-file type resolution with import graph building and circular dependency handling
REST Detection	Express and Fastify endpoint extraction with validation middleware support
HTTP Client Tracing	fetch() and axios call detection with URL extraction and type inference
GraphQL Support	SDL schema parsing, Apollo Server resolvers, and Apollo Client hook tracing

Phase 3 Capabilities

Feature	Description
Python AST Parser	FastAPI, Flask, and MCP tool extraction with Pydantic model support
Go Language Parser	Struct/interface extraction with Chi, Gin, and stdlib HTTP handler detection
gRPC/Protobuf Support	Proto3 parsing with message, enum, service, and streaming RPC extraction
Python HTTP Clients	requests, httpx, and aiohttp library detection with response property tracing

Test Coverage

1047 tests passing across 16 test suites:

Test Suite	Tests
Pattern Matcher	85
REST Detection	87
HTTP Client Tracing	90
GraphQL Support	109
Import Resolution	56
Core (adapters, OpenAPI, tRPC)	234
Python AST	121
gRPC/Protobuf	124
Go Parser	106
Python HTTP Clients	35

Installation

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

# Navigate to the directory
cd mnehmos.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": {}
    }
  }
}

Supported Formats

Trace MCP supports schema extraction and comparison across multiple specification formats through a pluggable adapter registry.

Summary of Supported Frameworks

Category	Frameworks
API Specs	OpenAPI 3.0+, Swagger
RPC	MCP (Zod), tRPC, gRPC/Protobuf
REST Servers	Express, Fastify, FastAPI, Flask, Chi, Gin, Go stdlib
HTTP Clients	fetch(), axios, requests, httpx, aiohttp
GraphQL	SDL schemas, Apollo Server, Apollo Client
Type Systems	TypeScript interfaces, Zod schemas, Pydantic models, Go structs

Supported Languages

Language	Producer Detection	Consumer Tracing
TypeScript	MCP tools, tRPC, Express, Fastify, GraphQL resolvers	callTool(), fetch, axios, Apollo Client
Python	FastAPI, Flask, MCP tools, Pydantic models	requests, httpx, aiohttp
Go	Chi, Gin, stdlib handlers, structs, interfaces	—
Protobuf	Messages, enums, services, streaming RPCs	—

MCP Server Schemas (Zod)

Extract MCP tool definitions from server source code using Zod schemas.

server.tool(
  "get_character",
  "Fetch character data",
  {
    characterId: z.string().describe("Character ID"),
  },
  async (args) => {
    // implementation
  }
);

Schema ID Format: endpoint:GET:/tools/get_character@./server.ts

OpenAPI / Swagger Specifications

Extract schemas from OpenAPI 3.0+ specifications, supporting endpoints, request bodies, responses, and component schemas.

openapi: 3.0.0
info:
  title: Character API
  version: 1.0.0
paths:
  /characters/{id}:
    get:
      parameters:
        - name: id
          in: path
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Character'
components:
  schemas:
    Character:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        class:
          type: string
      required:
        - id
        - name
        - class

Schema ID Format: endpoint:GET:/characters/{id}@./api.yaml

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.openapi.yaml", "**/*.swagger.json"],
});

TypeScript Interfaces & Types

Extract exported interfaces, type aliases, and enums from TypeScript source files. Supports utility types including Pick, Omit, Partial, Required, and Record.

export interface Character {
  id: string;
  name: string;
  class: "Fighter" | "Wizard" | "Rogue";
  hitPoints: number;
  stats: {
    strength: number;
    dexterity: number;
    constitution: number;
  };
}

export type ReadonlyCharacter = Readonly<Character>;

export enum CharacterClass {
  Fighter = "Fighter",
  Wizard = "Wizard",
  Rogue = "Rogue",
}

Schema ID Format: interface:Character@./types.ts

Supported Utility Types:

Pick<T, K> - Select properties from interface
Omit<T, K> - Exclude properties from interface
Partial<T> - Make all properties optional
Required<T> - Make all properties required
Record<K, T> - Object with specific keys and value type

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./shared",
  include: ["**/*.ts", "**/*.tsx"],
});
// Returns interfaces with ID format: interface:CharacterClass@./types.ts

tRPC Routers

Extract procedure schemas from tRPC routers, including input/output types, query, mutation, and subscription handlers. Handles nested routers and middleware.

import { z } from "zod";
import { publicProcedure, router } from "./trpc";

export const appRouter = router({
  users: router({
    getById: publicProcedure
      .input(z.string())
      .output(z.object({
        id: z.string(),
        name: z.string(),
        email: z.string().email(),
      }))
      .query(async ({ input }) => {
        // implementation
      }),
    
    create: publicProcedure
      .input(z.object({
        name: z.string(),
        email: z.string().email(),
      }))
      .output(z.object({
        id: z.string(),
        name: z.string(),
        email: z.string(),
      }))
      .mutation(async ({ input }) => {
        // implementation
      }),

    onChange: publicProcedure
      .output(z.object({
        userId: z.string(),
        action: z.enum(["created", "updated", "deleted"]),
      }))
      .subscription(async () => {
        // implementation
      }),
  }),
});

Schema ID Format: trpc:users.getById@./router.ts

Detected Elements:

Router definitions (router({ ... }))
Nested routers (users: router({ ... }))
Procedures (.query(), .mutation(), .subscription())
Input schemas (.input(zod_schema))
Output schemas (.output(zod_schema))

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend/trpc",
  include: ["**/*.router.ts"],
});
// Returns procedures with ID format: trpc:users.getById@./router.ts

REST Endpoints (Express & Fastify)

Extract endpoint schemas from Express and Fastify applications, including route parameters, request bodies, response types, and validation middleware.

Express

import express from "express";
import { z } from "zod";

const app = express();

// Basic route with typed response
app.get("/users/:id", (req, res) => {
  const user: User = getUserById(req.params.id);
  res.json(user);
});

// Route with Zod validation middleware
app.post("/users", 
  validate(z.object({
    name: z.string(),
    email: z.string().email(),
  })),
  (req, res) => {
    res.status(201).json({ id: "123", ...req.body });
  }
);

// Router-based routes
const router = express.Router();
router.get("/health", (req, res) => res.json({ status: "ok" }));
app.use("/api", router);

Schema ID Format: rest:GET:/users/:id@./app.ts

Fastify

import Fastify from "fastify";

const fastify = Fastify();

// Route with JSON Schema validation
fastify.post("/users", {
  schema: {
    body: {
      type: "object",
      properties: {
        name: { type: "string" },
        email: { type: "string", format: "email" },
      },
      required: ["name", "email"],
    },
    response: {
      201: {
        type: "object",
        properties: {
          id: { type: "string" },
          name: { type: "string" },
        },
      },
    },
  },
}, async (request, reply) => {
  return { id: "123", name: request.body.name };
});

// Shorthand methods
fastify.get("/health", async () => ({ status: "ok" }));

Schema ID Format: rest:POST:/users@./server.ts

Detected Elements:

HTTP methods: GET, POST, PUT, PATCH, DELETE
Path parameters (:id, :userId)
Request body schemas (Zod, Joi, celebrate, JSON Schema)
Response type inference
Router prefixes and mounting

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.ts"],
});
// Returns endpoints with ID format: rest:GET:/users/:id@./routes.ts

HTTP Clients (fetch & axios)

Trace HTTP client calls to detect consumer expectations for API responses.

fetch() API

// Basic fetch with type assertion
const response = await fetch("/api/users");
const users: User[] = await response.json();

// fetch with request options
const newUser = await fetch("/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Alice" }),
}).then(res => res.json()) as CreateUserResponse;

// Template literal URLs
const userId = "123";
const user = await fetch(`/api/users/${userId}`).then(r => r.json());

// Property access tracking
console.log(user.name, user.email, user.profile.avatar);

Detected Elements:

URL extraction (static strings, template literals, variables)
HTTP method detection
Type assertions and generics
Property access patterns on response data

axios

import axios from "axios";

// Basic GET request
const { data: users } = await axios.get<User[]>("/api/users");

// POST with typed response
const response = await axios.post<CreateUserResponse>("/api/users", {
  name: "Bob",
  email: "bob@example.com",
});

// Instance with base URL
const api = axios.create({ baseURL: "https://api.example.com" });
const profile = await api.get<Profile>("/me");

// Destructured property access
const { name, email } = response.data;

Schema ID Format: http-client:GET:/api/users@./client.ts

Detected Elements:

axios methods: .get(), .post(), .put(), .patch(), .delete()
Generic type parameters (axios.get<User>)
Instance creation with axios.create()
Base URL resolution
Response data property access

Usage Example:

const result = await client.callTool("trace_usage", {
  rootDir: "./frontend/src",
  include: ["**/*.ts", "**/*.tsx"],
});
// Returns HTTP client calls with ID format: http-client:GET:/api/users@./api.ts

GraphQL (SDL & Apollo)

Extract schemas from GraphQL SDL files and trace Apollo Server resolvers and Apollo Client hooks.

SDL Schema Files

# schema.graphql
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
}

type Query {
  user(id: ID!): User
  users: [User!]!
  post(id: ID!): Post
}

type Mutation {
  createUser(name: String!, email: String!): User!
  createPost(title: String!, content: String!, authorId: ID!): Post!
}

Schema ID Format: graphql:Query.user@./schema.graphql

Apollo Server Resolvers

import { ApolloServer } from "@apollo/server";

const resolvers = {
  Query: {
    user: async (_, { id }) => {
      return db.users.findById(id);
    },
    users: async () => {
      return db.users.findAll();
    },
  },
  Mutation: {
    createUser: async (_, { name, email }) => {
      return db.users.create({ name, email });
    },
  },
  User: {
    posts: async (parent) => {
      return db.posts.findByAuthor(parent.id);
    },
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

Schema ID Format: graphql-resolver:Query.user@./resolvers.ts

Apollo Client Hooks

import { useQuery, useMutation, gql } from "@apollo/client";

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
    }
  }
`;

const CREATE_USER = gql`
  mutation CreateUser($name: String!, $email: String!) {
    createUser(name: $name, email: $email) {
      id
      name
    }
  }
`;

function UserProfile({ userId }: { userId: string }) {
  const { data, loading, error } = useQuery(GET_USER, {
    variables: { id: userId },
  });

  const [createUser] = useMutation(CREATE_USER);

  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  return <div>{data.user.name}</div>;
}

Schema ID Format: graphql-client:GetUser@./UserProfile.tsx

Detected Elements:

SDL types: scalar, object, input, enum, interface, union
Query and Mutation definitions
Field arguments and return types
Apollo Client hooks: useQuery, useMutation, useLazyQuery, useSubscription
Operation names and variables
Selected fields in queries

Usage Example:

// Extract GraphQL schemas
const schemas = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.graphql", "**/resolvers.ts"],
});

// Trace Apollo Client usage
const usage = await client.callTool("trace_usage", {
  rootDir: "./frontend/src",
  include: ["**/*.tsx"],
});

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

Python (FastAPI, Flask, MCP Tools)

Extract endpoint schemas from Python web frameworks and MCP tool definitions with full Pydantic model support.

FastAPI

from fastapi import FastAPI, APIRouter
from pydantic import BaseModel
from typing import Optional, List

class Character(BaseModel):
    id: str
    name: str
    character_class: str
    level: int = 1
    skills: List[str] = []

class CreateCharacterRequest(BaseModel):
    name: str
    character_class: str
    background: Optional[str] = None

app = FastAPI()
router = APIRouter(prefix="/api/v1")

@app.get("/characters/{character_id}")
async def get_character(character_id: str) -> Character:
    return Character(id=character_id, name="Hero", character_class="Fighter")

@router.post("/characters")
async def create_character(request: CreateCharacterRequest) -> Character:
    return Character(id="123", name=request.name, character_class=request.character_class)

app.include_router(router)

Schema ID Format: python:GET:/characters/{character_id}@./main.py

Flask

from flask import Flask, Blueprint, request, jsonify

app = Flask(__name__)
api = Blueprint("api", __name__, url_prefix="/api")

@app.route("/health")
def health_check():
    return jsonify({"status": "ok"})

@api.route("/users/<user_id>", methods=["GET"])
def get_user(user_id):
    return jsonify({"id": user_id, "name": "Alice"})

@api.route("/users", methods=["POST"])
def create_user():
    data = request.get_json()
    return jsonify({"id": "123", **data}), 201

app.register_blueprint(api)

Schema ID Format: python:GET:/api/users/<user_id>@./app.py

MCP Tools (Python)

from mcp import Server

server = Server("character-tools")

@server.tool()
async def get_character(character_id: str) -> dict:
    """Fetch character data by ID."""
    return {"id": character_id, "name": "Hero", "class": "Fighter"}

@mcp.tool()
def roll_dice(dice: str, modifier: int = 0) -> dict:
    """Roll dice with optional modifier."""
    return {"result": 15, "expression": dice, "modifier": modifier}

Schema ID Format: python-mcp:get_character@./tools.py

Pydantic Models

from pydantic import BaseModel, Field
from typing import Optional, List, Dict, Union, Literal
from enum import Enum

class CharacterClass(str, Enum):
    FIGHTER = "Fighter"
    WIZARD = "Wizard"
    ROGUE = "Rogue"

class Stats(BaseModel):
    strength: int = Field(ge=1, le=20)
    dexterity: int = Field(ge=1, le=20)
    constitution: int = Field(ge=1, le=20)

class Character(BaseModel):
    id: str
    name: str
    character_class: CharacterClass
    level: int = Field(default=1, ge=1, le=20)
    stats: Stats
    equipment: List[str] = []
    metadata: Optional[Dict[str, str]] = None

Detected Elements:

Decorators: @app.get(), @app.post(), @router.*, @app.route(), @blueprint.route()
MCP decorators: @mcp.tool(), @server.tool()
Pydantic BaseModel classes with field extraction
Type annotations: Optional, Union, List, Dict, Literal
Enum types

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.py"],
});
// Returns endpoints with ID format: python:GET:/characters/{id}@./main.py

Go Language (Chi, Gin, stdlib)

Extract struct definitions, interfaces, and HTTP endpoint schemas from Go source files.

Structs with JSON Tags

package models

type Character struct {
    ID        string   `json:"id"`
    Name      string   `json:"name"`
    Class     string   `json:"class"`
    Level     int      `json:"level"`
    HitPoints int      `json:"hp"`
    Skills    []string `json:"skills,omitempty"`
}

type Stats struct {
    Strength     int `json:"str"`
    Dexterity    int `json:"dex"`
    Constitution int `json:"con"`
}

// Embedded struct
type CharacterWithStats struct {
    Character
    Stats Stats `json:"stats"`
}

Schema ID Format: go-struct:Character@./models/character.go

Interfaces

package services

type CharacterService interface {
    GetByID(id string) (*Character, error)
    Create(req CreateRequest) (*Character, error)
    Update(id string, req UpdateRequest) (*Character, error)
    Delete(id string) error
}

type Repository interface {
    Find(query Query) ([]Character, error)
    Save(character *Character) error
}

Schema ID Format: go-interface:CharacterService@./services/character.go

stdlib HTTP Handlers

package main

import (
    "encoding/json"
    "net/http"
)

func main() {
    http.HandleFunc("/health", healthHandler)
    http.HandleFunc("/api/characters", charactersHandler)
    http.HandleFunc("/api/characters/", characterByIDHandler)
    http.ListenAndServe(":8080", nil)
}

func healthHandler(w http.ResponseWriter, r *http.Request) {
    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}

func charactersHandler(w http.ResponseWriter, r *http.Request) {
    switch r.Method {
    case http.MethodGet:
        // List characters
    case http.MethodPost:
        // Create character
    }
}

Schema ID Format: go-http:GET:/health@./main.go

Chi Router

package main

import (
    "github.com/go-chi/chi/v5"
    "net/http"
)

func main() {
    r := chi.NewRouter()
    
    r.Get("/health", healthHandler)
    
    r.Route("/api/characters", func(r chi.Router) {
        r.Get("/", listCharacters)
        r.Post("/", createCharacter)
        r.Get("/{id}", getCharacter)        // Chi param: {id}
        r.Put("/{id}", updateCharacter)
        r.Delete("/{id}", deleteCharacter)
    })
    
    http.ListenAndServe(":8080", r)
}

Schema ID Format: go-http:GET:/api/characters/{id}@./main.go

Gin Framework

package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default()
    
    r.GET("/health", healthHandler)
    
    api := r.Group("/api")
    {
        api.GET("/characters", listCharacters)
        api.POST("/characters", createCharacter)
        api.GET("/characters/:id", getCharacter)  // Gin param: :id
        api.PUT("/characters/:id", updateCharacter)
        api.DELETE("/characters/:id", deleteCharacter)
    }
    
    r.Run(":8080")
}

Schema ID Format: go-http:GET:/api/characters/:id@./main.go

Detected Elements:

Struct definitions with JSON tags
Embedded structs
Interface definitions
http.HandleFunc() patterns
Chi router: r.Get(), r.Post(), r.Route(), {param} syntax
Gin framework: r.GET(), r.POST(), r.Group(), :param syntax

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.go"],
});
// Returns structs, interfaces, and endpoints

gRPC / Protobuf

Parse Protocol Buffer definitions (proto3) to extract message types, enums, services, and RPC methods.

Basic Messages

syntax = "proto3";

package character;

message Character {
    string id = 1;
    string name = 2;
    CharacterClass character_class = 3;
    int32 level = 4;
    Stats stats = 5;
    repeated string skills = 6;
}

message Stats {
    int32 strength = 1;
    int32 dexterity = 2;
    int32 constitution = 3;
}

Schema ID Format: proto-message:character.Character@./character.proto

Enums

enum CharacterClass {
    CHARACTER_CLASS_UNSPECIFIED = 0;
    CHARACTER_CLASS_FIGHTER = 1;
    CHARACTER_CLASS_WIZARD = 2;
    CHARACTER_CLASS_ROGUE = 3;
}

enum DamageType {
    DAMAGE_TYPE_UNSPECIFIED = 0;
    DAMAGE_TYPE_SLASHING = 1;
    DAMAGE_TYPE_PIERCING = 2;
    DAMAGE_TYPE_FIRE = 3;
}

Schema ID Format: proto-enum:character.CharacterClass@./character.proto

Oneof and Map Fields

message Equipment {
    string id = 1;
    string name = 2;
    
    oneof item_type {
        Weapon weapon = 10;
        Armor armor = 11;
        Consumable consumable = 12;
    }
}

message Inventory {
    string character_id = 1;
    map<string, int32> item_counts = 2;
    map<string, Equipment> equipped = 3;
}

Schema ID Format: proto-message:character.Equipment@./equipment.proto

Services and RPCs

service CharacterService {
    // Unary RPC
    rpc GetCharacter(GetCharacterRequest) returns (Character);
    
    // Server streaming
    rpc ListCharacters(ListRequest) returns (stream Character);
    
    // Client streaming
    rpc UploadInventory(stream Item) returns (UploadResponse);
    
    // Bidirectional streaming
    rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

message GetCharacterRequest {
    string id = 1;
}

message ListRequest {
    int32 page_size = 1;
    string page_token = 2;
}

Schema ID Format: proto-service:character.CharacterService@./character.proto RPC Format: proto-rpc:CharacterService.GetCharacter@./character.proto

Well-Known Types

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/any.proto";
import "google/protobuf/struct.proto";

message CharacterEvent {
    string character_id = 1;
    string event_type = 2;
    google.protobuf.Timestamp created_at = 3;
    google.protobuf.Duration duration = 4;
    google.protobuf.Any payload = 5;
    google.protobuf.Struct metadata = 6;
}

Detected Elements:

Messages with all field types (scalar, message, enum, repeated)
Enums with numeric values
oneof field groups
map<K, V> fields
Nested message definitions
Service definitions with all streaming modes:
- Unary: rpc Method(Request) returns (Response)
- Server streaming: rpc Method(Request) returns (stream Response)
- Client streaming: rpc Method(stream Request) returns (Response)
- Bidirectional: rpc Method(stream Request) returns (stream Response)
Well-known types: Timestamp, Duration, Any, Struct

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./proto",
  include: ["**/*.proto"],
});
// Returns messages, enums, and services

Python HTTP Clients (requests, httpx, aiohttp)

Trace HTTP client calls in Python code to detect consumer expectations.

requests Library

import requests

# Basic GET
response = requests.get("https://api.example.com/characters")
characters = response.json()

# GET with path parameter
character = requests.get(f"https://api.example.com/characters/{char_id}").json()

# POST with JSON body
new_char = requests.post(
    "https://api.example.com/characters",
    json={"name": "Hero", "class": "Fighter"}
).json()

# Session with base URL
session = requests.Session()
session.headers.update({"Authorization": "Bearer token"})
user = session.get("https://api.example.com/me").json()

# Property access tracking
print(character["name"], character["stats"]["strength"])

Schema ID Format: python-http:GET:/characters@./client.py

httpx Library

import httpx

# Sync client
response = httpx.get("https://api.example.com/characters")
data = response.json()

# Async client
async with httpx.AsyncClient(base_url="https://api.example.com") as client:
    response = await client.get("/characters")
    characters = response.json()
    
    response = await client.post("/characters", json={"name": "Hero"})
    new_char = response.json()

Schema ID Format: python-http:GET:/characters@./client.py

aiohttp Library

import aiohttp

async with aiohttp.ClientSession() as session:
    # GET request
    async with session.get("https://api.example.com/characters") as response:
        characters = await response.json()
    
    # POST request
    async with session.post(
        "https://api.example.com/characters",
        json={"name": "Hero", "class": "Fighter"}
    ) as response:
        new_char = await response.json()
    
    # Property access
    print(new_char["id"], new_char["name"])

Schema ID Format: python-http:POST:/characters@./client.py

Detected Elements:

requests.get(), requests.post(), etc.
httpx.get(), httpx.post(), AsyncClient methods
aiohttp.ClientSession methods
URL extraction (static strings, f-strings)
HTTP method detection
Response property access (dictionary key access)

Usage Example:

const result = await client.callTool("trace_usage", {
  rootDir: "./python-client",
  include: ["**/*.py"],
});
// Returns HTTP client calls with property access patterns

Architecture

Pattern Matcher Framework

The pattern matcher provides an extensible system for detecting code patterns across different frameworks. Located in src/patterns/:

src/patterns/
├── base.ts          # BasePattern abstract class
├── types.ts         # PatternMatch, PatternContext interfaces
├── registry.ts      # PatternRegistry for plugin management
├── extractors.ts    # Node extractors for AST traversal
├── errors.ts        # Pattern-specific error types
├── rest/            # Express, Fastify patterns
├── http-clients/    # fetch, axios patterns
└── graphql/         # Apollo patterns

Supported Pattern Types:

Call patterns: Function/method calls (app.get(), fetch())
Decorator patterns: TypeScript/Python decorators (@Controller())
Property patterns: Object property assignments
Export patterns: Module exports (export const router = ...)
Chain patterns: Method chaining (router.get().post())

Import Resolution

Cross-file type resolution with import graph building. Located in src/languages/import-resolver.ts:

Resolves import { Type } from "./types"
Handles barrel exports (export * from)
Supports path aliases via tsconfig.json
Detects and handles circular dependencies
Caches resolved types for performance

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. Also supports OpenAPI, TypeScript interfaces, tRPC routers, REST endpoints, and GraphQL schemas.

Parameters:

rootDir (required): Root directory of 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, HTTP client calls, and GraphQL hooks, tracking 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):

# mnehmos.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",
});

4. Extract Multiple Formats

// Extract from MCP server
const mcpSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend/mcp",
  include: ["**/*.ts"],
});

// Extract from OpenAPI specification
const openApiSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.openapi.yaml"],
});

// Extract from tRPC router
const trpcSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend/trpc",
  include: ["**/*.router.ts"],
});

// Extract TypeScript interfaces
const interfaceSchemas = await client.callTool("extract_schemas", {
  rootDir: "./shared",
  include: ["**/*.types.ts"],
});

// Extract REST endpoints (Express/Fastify)
const restSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend/routes",
  include: ["**/*.ts"],
});

// Extract GraphQL schemas
const graphqlSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend/graphql",
  include: ["**/*.graphql", "**/resolvers.ts"],
});

5. Full-Stack GraphQL Validation

// Extract GraphQL schema and resolvers
const producer = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.graphql", "**/resolvers/**/*.ts"],
});

// Trace Apollo Client hooks
const consumer = await client.callTool("trace_usage", {
  rootDir: "./frontend/src",
  include: ["**/*.tsx"],
});

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

Roadmap

Completed

Planned

License

MIT

mnehmos.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
REST endpoints and HTTP client calls
GraphQL schemas and Apollo Client hooks

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

Features

Core Capabilities

Feature	Description
Schema Extraction	Extract schemas from MCP tools, OpenAPI, TypeScript, tRPC, REST endpoints, GraphQL
Usage Tracing	Track how client code consumes schemas via property access patterns
Mismatch Detection	Compare producer schemas against consumer expectations
Code Generation	Scaffold consumer code from producer schemas (and vice versa)
Watch Mode	Continuous validation on file changes

Phase 2 Capabilities

Feature	Description
Pattern Matcher	Extensible pattern detection supporting call, decorator, property, export, and chain patterns
Import Resolution	Cross-file type resolution with import graph building and circular dependency handling
REST Detection	Express and Fastify endpoint extraction with validation middleware support
HTTP Client Tracing	fetch() and axios call detection with URL extraction and type inference
GraphQL Support	SDL schema parsing, Apollo Server resolvers, and Apollo Client hook tracing

Phase 3 Capabilities

Feature	Description
Python AST Parser	FastAPI, Flask, and MCP tool extraction with Pydantic model support
Go Language Parser	Struct/interface extraction with Chi, Gin, and stdlib HTTP handler detection
gRPC/Protobuf Support	Proto3 parsing with message, enum, service, and streaming RPC extraction
Python HTTP Clients	requests, httpx, and aiohttp library detection with response property tracing

Test Coverage

1047 tests passing across 16 test suites:

Test Suite	Tests
Pattern Matcher	85
REST Detection	87
HTTP Client Tracing	90
GraphQL Support	109
Import Resolution	56
Core (adapters, OpenAPI, tRPC)	234
Python AST	121
gRPC/Protobuf	124
Go Parser	106
Python HTTP Clients	35

Installation

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

# Navigate to the directory
cd mnehmos.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": {}
    }
  }
}

Supported Formats

Trace MCP supports schema extraction and comparison across multiple specification formats through a pluggable adapter registry.

Summary of Supported Frameworks

Category	Frameworks
API Specs	OpenAPI 3.0+, Swagger
RPC	MCP (Zod), tRPC, gRPC/Protobuf
REST Servers	Express, Fastify, FastAPI, Flask, Chi, Gin, Go stdlib
HTTP Clients	fetch(), axios, requests, httpx, aiohttp
GraphQL	SDL schemas, Apollo Server, Apollo Client
Type Systems	TypeScript interfaces, Zod schemas, Pydantic models, Go structs

Supported Languages

Language	Producer Detection	Consumer Tracing
TypeScript	MCP tools, tRPC, Express, Fastify, GraphQL resolvers	callTool(), fetch, axios, Apollo Client
Python	FastAPI, Flask, MCP tools, Pydantic models	requests, httpx, aiohttp
Go	Chi, Gin, stdlib handlers, structs, interfaces	—
Protobuf	Messages, enums, services, streaming RPCs	—

MCP Server Schemas (Zod)

Extract MCP tool definitions from server source code using Zod schemas.

server.tool(
  "get_character",
  "Fetch character data",
  {
    characterId: z.string().describe("Character ID"),
  },
  async (args) => {
    // implementation
  }
);

Schema ID Format: endpoint:GET:/tools/get_character@./server.ts

OpenAPI / Swagger Specifications

Extract schemas from OpenAPI 3.0+ specifications, supporting endpoints, request bodies, responses, and component schemas.

openapi: 3.0.0
info:
  title: Character API
  version: 1.0.0
paths:
  /characters/{id}:
    get:
      parameters:
        - name: id
          in: path
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Character'
components:
  schemas:
    Character:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        class:
          type: string
      required:
        - id
        - name
        - class

Schema ID Format: endpoint:GET:/characters/{id}@./api.yaml

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.openapi.yaml", "**/*.swagger.json"],
});

TypeScript Interfaces & Types

Extract exported interfaces, type aliases, and enums from TypeScript source files. Supports utility types including Pick, Omit, Partial, Required, and Record.

export interface Character {
  id: string;
  name: string;
  class: "Fighter" | "Wizard" | "Rogue";
  hitPoints: number;
  stats: {
    strength: number;
    dexterity: number;
    constitution: number;
  };
}

export type ReadonlyCharacter = Readonly<Character>;

export enum CharacterClass {
  Fighter = "Fighter",
  Wizard = "Wizard",
  Rogue = "Rogue",
}

Schema ID Format: interface:Character@./types.ts

Supported Utility Types:

Pick<T, K> - Select properties from interface
Omit<T, K> - Exclude properties from interface
Partial<T> - Make all properties optional
Required<T> - Make all properties required
Record<K, T> - Object with specific keys and value type

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./shared",
  include: ["**/*.ts", "**/*.tsx"],
});
// Returns interfaces with ID format: interface:CharacterClass@./types.ts

tRPC Routers

Extract procedure schemas from tRPC routers, including input/output types, query, mutation, and subscription handlers. Handles nested routers and middleware.

import { z } from "zod";
import { publicProcedure, router } from "./trpc";

export const appRouter = router({
  users: router({
    getById: publicProcedure
      .input(z.string())
      .output(z.object({
        id: z.string(),
        name: z.string(),
        email: z.string().email(),
      }))
      .query(async ({ input }) => {
        // implementation
      }),
    
    create: publicProcedure
      .input(z.object({
        name: z.string(),
        email: z.string().email(),
      }))
      .output(z.object({
        id: z.string(),
        name: z.string(),
        email: z.string(),
      }))
      .mutation(async ({ input }) => {
        // implementation
      }),

    onChange: publicProcedure
      .output(z.object({
        userId: z.string(),
        action: z.enum(["created", "updated", "deleted"]),
      }))
      .subscription(async () => {
        // implementation
      }),
  }),
});

Schema ID Format: trpc:users.getById@./router.ts

Detected Elements:

Router definitions (router({ ... }))
Nested routers (users: router({ ... }))
Procedures (.query(), .mutation(), .subscription())
Input schemas (.input(zod_schema))
Output schemas (.output(zod_schema))

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend/trpc",
  include: ["**/*.router.ts"],
});
// Returns procedures with ID format: trpc:users.getById@./router.ts

REST Endpoints (Express & Fastify)

Extract endpoint schemas from Express and Fastify applications, including route parameters, request bodies, response types, and validation middleware.

Express

import express from "express";
import { z } from "zod";

const app = express();

// Basic route with typed response
app.get("/users/:id", (req, res) => {
  const user: User = getUserById(req.params.id);
  res.json(user);
});

// Route with Zod validation middleware
app.post("/users", 
  validate(z.object({
    name: z.string(),
    email: z.string().email(),
  })),
  (req, res) => {
    res.status(201).json({ id: "123", ...req.body });
  }
);

// Router-based routes
const router = express.Router();
router.get("/health", (req, res) => res.json({ status: "ok" }));
app.use("/api", router);

Schema ID Format: rest:GET:/users/:id@./app.ts

Fastify

import Fastify from "fastify";

const fastify = Fastify();

// Route with JSON Schema validation
fastify.post("/users", {
  schema: {
    body: {
      type: "object",
      properties: {
        name: { type: "string" },
        email: { type: "string", format: "email" },
      },
      required: ["name", "email"],
    },
    response: {
      201: {
        type: "object",
        properties: {
          id: { type: "string" },
          name: { type: "string" },
        },
      },
    },
  },
}, async (request, reply) => {
  return { id: "123", name: request.body.name };
});

// Shorthand methods
fastify.get("/health", async () => ({ status: "ok" }));

Schema ID Format: rest:POST:/users@./server.ts

Detected Elements:

HTTP methods: GET, POST, PUT, PATCH, DELETE
Path parameters (:id, :userId)
Request body schemas (Zod, Joi, celebrate, JSON Schema)
Response type inference
Router prefixes and mounting

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.ts"],
});
// Returns endpoints with ID format: rest:GET:/users/:id@./routes.ts

HTTP Clients (fetch & axios)

Trace HTTP client calls to detect consumer expectations for API responses.

fetch() API

// Basic fetch with type assertion
const response = await fetch("/api/users");
const users: User[] = await response.json();

// fetch with request options
const newUser = await fetch("/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Alice" }),
}).then(res => res.json()) as CreateUserResponse;

// Template literal URLs
const userId = "123";
const user = await fetch(`/api/users/${userId}`).then(r => r.json());

// Property access tracking
console.log(user.name, user.email, user.profile.avatar);

Detected Elements:

URL extraction (static strings, template literals, variables)
HTTP method detection
Type assertions and generics
Property access patterns on response data

axios

import axios from "axios";

// Basic GET request
const { data: users } = await axios.get<User[]>("/api/users");

// POST with typed response
const response = await axios.post<CreateUserResponse>("/api/users", {
  name: "Bob",
  email: "bob@example.com",
});

// Instance with base URL
const api = axios.create({ baseURL: "https://api.example.com" });
const profile = await api.get<Profile>("/me");

// Destructured property access
const { name, email } = response.data;

Schema ID Format: http-client:GET:/api/users@./client.ts

Detected Elements:

axios methods: .get(), .post(), .put(), .patch(), .delete()
Generic type parameters (axios.get<User>)
Instance creation with axios.create()
Base URL resolution
Response data property access

Usage Example:

const result = await client.callTool("trace_usage", {
  rootDir: "./frontend/src",
  include: ["**/*.ts", "**/*.tsx"],
});
// Returns HTTP client calls with ID format: http-client:GET:/api/users@./api.ts

GraphQL (SDL & Apollo)

Extract schemas from GraphQL SDL files and trace Apollo Server resolvers and Apollo Client hooks.

SDL Schema Files

# schema.graphql
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
}

type Query {
  user(id: ID!): User
  users: [User!]!
  post(id: ID!): Post
}

type Mutation {
  createUser(name: String!, email: String!): User!
  createPost(title: String!, content: String!, authorId: ID!): Post!
}

Schema ID Format: graphql:Query.user@./schema.graphql

Apollo Server Resolvers

import { ApolloServer } from "@apollo/server";

const resolvers = {
  Query: {
    user: async (_, { id }) => {
      return db.users.findById(id);
    },
    users: async () => {
      return db.users.findAll();
    },
  },
  Mutation: {
    createUser: async (_, { name, email }) => {
      return db.users.create({ name, email });
    },
  },
  User: {
    posts: async (parent) => {
      return db.posts.findByAuthor(parent.id);
    },
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

Schema ID Format: graphql-resolver:Query.user@./resolvers.ts

Apollo Client Hooks

import { useQuery, useMutation, gql } from "@apollo/client";

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
    }
  }
`;

const CREATE_USER = gql`
  mutation CreateUser($name: String!, $email: String!) {
    createUser(name: $name, email: $email) {
      id
      name
    }
  }
`;

function UserProfile({ userId }: { userId: string }) {
  const { data, loading, error } = useQuery(GET_USER, {
    variables: { id: userId },
  });

  const [createUser] = useMutation(CREATE_USER);

  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  return <div>{data.user.name}</div>;
}

Schema ID Format: graphql-client:GetUser@./UserProfile.tsx

Detected Elements:

SDL types: scalar, object, input, enum, interface, union
Query and Mutation definitions
Field arguments and return types
Apollo Client hooks: useQuery, useMutation, useLazyQuery, useSubscription
Operation names and variables
Selected fields in queries

Usage Example:

// Extract GraphQL schemas
const schemas = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.graphql", "**/resolvers.ts"],
});

// Trace Apollo Client usage
const usage = await client.callTool("trace_usage", {
  rootDir: "./frontend/src",
  include: ["**/*.tsx"],
});

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

Python (FastAPI, Flask, MCP Tools)

Extract endpoint schemas from Python web frameworks and MCP tool definitions with full Pydantic model support.

FastAPI

from fastapi import FastAPI, APIRouter
from pydantic import BaseModel
from typing import Optional, List

class Character(BaseModel):
    id: str
    name: str
    character_class: str
    level: int = 1
    skills: List[str] = []

class CreateCharacterRequest(BaseModel):
    name: str
    character_class: str
    background: Optional[str] = None

app = FastAPI()
router = APIRouter(prefix="/api/v1")

@app.get("/characters/{character_id}")
async def get_character(character_id: str) -> Character:
    return Character(id=character_id, name="Hero", character_class="Fighter")

@router.post("/characters")
async def create_character(request: CreateCharacterRequest) -> Character:
    return Character(id="123", name=request.name, character_class=request.character_class)

app.include_router(router)

Schema ID Format: python:GET:/characters/{character_id}@./main.py

Flask

from flask import Flask, Blueprint, request, jsonify

app = Flask(__name__)
api = Blueprint("api", __name__, url_prefix="/api")

@app.route("/health")
def health_check():
    return jsonify({"status": "ok"})

@api.route("/users/<user_id>", methods=["GET"])
def get_user(user_id):
    return jsonify({"id": user_id, "name": "Alice"})

@api.route("/users", methods=["POST"])
def create_user():
    data = request.get_json()
    return jsonify({"id": "123", **data}), 201

app.register_blueprint(api)

Schema ID Format: python:GET:/api/users/<user_id>@./app.py

MCP Tools (Python)

from mcp import Server

server = Server("character-tools")

@server.tool()
async def get_character(character_id: str) -> dict:
    """Fetch character data by ID."""
    return {"id": character_id, "name": "Hero", "class": "Fighter"}

@mcp.tool()
def roll_dice(dice: str, modifier: int = 0) -> dict:
    """Roll dice with optional modifier."""
    return {"result": 15, "expression": dice, "modifier": modifier}

Schema ID Format: python-mcp:get_character@./tools.py

Pydantic Models

from pydantic import BaseModel, Field
from typing import Optional, List, Dict, Union, Literal
from enum import Enum

class CharacterClass(str, Enum):
    FIGHTER = "Fighter"
    WIZARD = "Wizard"
    ROGUE = "Rogue"

class Stats(BaseModel):
    strength: int = Field(ge=1, le=20)
    dexterity: int = Field(ge=1, le=20)
    constitution: int = Field(ge=1, le=20)

class Character(BaseModel):
    id: str
    name: str
    character_class: CharacterClass
    level: int = Field(default=1, ge=1, le=20)
    stats: Stats
    equipment: List[str] = []
    metadata: Optional[Dict[str, str]] = None

Detected Elements:

Decorators: @app.get(), @app.post(), @router.*, @app.route(), @blueprint.route()
MCP decorators: @mcp.tool(), @server.tool()
Pydantic BaseModel classes with field extraction
Type annotations: Optional, Union, List, Dict, Literal
Enum types

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.py"],
});
// Returns endpoints with ID format: python:GET:/characters/{id}@./main.py

Go Language (Chi, Gin, stdlib)

Extract struct definitions, interfaces, and HTTP endpoint schemas from Go source files.

Structs with JSON Tags

package models

type Character struct {
    ID        string   `json:"id"`
    Name      string   `json:"name"`
    Class     string   `json:"class"`
    Level     int      `json:"level"`
    HitPoints int      `json:"hp"`
    Skills    []string `json:"skills,omitempty"`
}

type Stats struct {
    Strength     int `json:"str"`
    Dexterity    int `json:"dex"`
    Constitution int `json:"con"`
}

// Embedded struct
type CharacterWithStats struct {
    Character
    Stats Stats `json:"stats"`
}

Schema ID Format: go-struct:Character@./models/character.go

Interfaces

package services

type CharacterService interface {
    GetByID(id string) (*Character, error)
    Create(req CreateRequest) (*Character, error)
    Update(id string, req UpdateRequest) (*Character, error)
    Delete(id string) error
}

type Repository interface {
    Find(query Query) ([]Character, error)
    Save(character *Character) error
}

Schema ID Format: go-interface:CharacterService@./services/character.go

stdlib HTTP Handlers

package main

import (
    "encoding/json"
    "net/http"
)

func main() {
    http.HandleFunc("/health", healthHandler)
    http.HandleFunc("/api/characters", charactersHandler)
    http.HandleFunc("/api/characters/", characterByIDHandler)
    http.ListenAndServe(":8080", nil)
}

func healthHandler(w http.ResponseWriter, r *http.Request) {
    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}

func charactersHandler(w http.ResponseWriter, r *http.Request) {
    switch r.Method {
    case http.MethodGet:
        // List characters
    case http.MethodPost:
        // Create character
    }
}

Schema ID Format: go-http:GET:/health@./main.go

Chi Router

package main

import (
    "github.com/go-chi/chi/v5"
    "net/http"
)

func main() {
    r := chi.NewRouter()
    
    r.Get("/health", healthHandler)
    
    r.Route("/api/characters", func(r chi.Router) {
        r.Get("/", listCharacters)
        r.Post("/", createCharacter)
        r.Get("/{id}", getCharacter)        // Chi param: {id}
        r.Put("/{id}", updateCharacter)
        r.Delete("/{id}", deleteCharacter)
    })
    
    http.ListenAndServe(":8080", r)
}

Schema ID Format: go-http:GET:/api/characters/{id}@./main.go

Gin Framework

package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default()
    
    r.GET("/health", healthHandler)
    
    api := r.Group("/api")
    {
        api.GET("/characters", listCharacters)
        api.POST("/characters", createCharacter)
        api.GET("/characters/:id", getCharacter)  // Gin param: :id
        api.PUT("/characters/:id", updateCharacter)
        api.DELETE("/characters/:id", deleteCharacter)
    }
    
    r.Run(":8080")
}

Schema ID Format: go-http:GET:/api/characters/:id@./main.go

Detected Elements:

Struct definitions with JSON tags
Embedded structs
Interface definitions
http.HandleFunc() patterns
Chi router: r.Get(), r.Post(), r.Route(), {param} syntax
Gin framework: r.GET(), r.POST(), r.Group(), :param syntax

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.go"],
});
// Returns structs, interfaces, and endpoints

gRPC / Protobuf

Parse Protocol Buffer definitions (proto3) to extract message types, enums, services, and RPC methods.

Basic Messages

syntax = "proto3";

package character;

message Character {
    string id = 1;
    string name = 2;
    CharacterClass character_class = 3;
    int32 level = 4;
    Stats stats = 5;
    repeated string skills = 6;
}

message Stats {
    int32 strength = 1;
    int32 dexterity = 2;
    int32 constitution = 3;
}

Schema ID Format: proto-message:character.Character@./character.proto

Enums

enum CharacterClass {
    CHARACTER_CLASS_UNSPECIFIED = 0;
    CHARACTER_CLASS_FIGHTER = 1;
    CHARACTER_CLASS_WIZARD = 2;
    CHARACTER_CLASS_ROGUE = 3;
}

enum DamageType {
    DAMAGE_TYPE_UNSPECIFIED = 0;
    DAMAGE_TYPE_SLASHING = 1;
    DAMAGE_TYPE_PIERCING = 2;
    DAMAGE_TYPE_FIRE = 3;
}

Schema ID Format: proto-enum:character.CharacterClass@./character.proto

Oneof and Map Fields

message Equipment {
    string id = 1;
    string name = 2;
    
    oneof item_type {
        Weapon weapon = 10;
        Armor armor = 11;
        Consumable consumable = 12;
    }
}

message Inventory {
    string character_id = 1;
    map<string, int32> item_counts = 2;
    map<string, Equipment> equipped = 3;
}

Schema ID Format: proto-message:character.Equipment@./equipment.proto

Services and RPCs

service CharacterService {
    // Unary RPC
    rpc GetCharacter(GetCharacterRequest) returns (Character);
    
    // Server streaming
    rpc ListCharacters(ListRequest) returns (stream Character);
    
    // Client streaming
    rpc UploadInventory(stream Item) returns (UploadResponse);
    
    // Bidirectional streaming
    rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

message GetCharacterRequest {
    string id = 1;
}

message ListRequest {
    int32 page_size = 1;
    string page_token = 2;
}

Schema ID Format: proto-service:character.CharacterService@./character.proto RPC Format: proto-rpc:CharacterService.GetCharacter@./character.proto

Well-Known Types

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/any.proto";
import "google/protobuf/struct.proto";

message CharacterEvent {
    string character_id = 1;
    string event_type = 2;
    google.protobuf.Timestamp created_at = 3;
    google.protobuf.Duration duration = 4;
    google.protobuf.Any payload = 5;
    google.protobuf.Struct metadata = 6;
}

Detected Elements:

Messages with all field types (scalar, message, enum, repeated)
Enums with numeric values
oneof field groups
map<K, V> fields
Nested message definitions
Service definitions with all streaming modes:
- Unary: rpc Method(Request) returns (Response)
- Server streaming: rpc Method(Request) returns (stream Response)
- Client streaming: rpc Method(stream Request) returns (Response)
- Bidirectional: rpc Method(stream Request) returns (stream Response)
Well-known types: Timestamp, Duration, Any, Struct

Usage Example:

const result = await client.callTool("extract_schemas", {
  rootDir: "./proto",
  include: ["**/*.proto"],
});
// Returns messages, enums, and services

Python HTTP Clients (requests, httpx, aiohttp)

Trace HTTP client calls in Python code to detect consumer expectations.

requests Library

import requests

# Basic GET
response = requests.get("https://api.example.com/characters")
characters = response.json()

# GET with path parameter
character = requests.get(f"https://api.example.com/characters/{char_id}").json()

# POST with JSON body
new_char = requests.post(
    "https://api.example.com/characters",
    json={"name": "Hero", "class": "Fighter"}
).json()

# Session with base URL
session = requests.Session()
session.headers.update({"Authorization": "Bearer token"})
user = session.get("https://api.example.com/me").json()

# Property access tracking
print(character["name"], character["stats"]["strength"])

Schema ID Format: python-http:GET:/characters@./client.py

httpx Library

import httpx

# Sync client
response = httpx.get("https://api.example.com/characters")
data = response.json()

# Async client
async with httpx.AsyncClient(base_url="https://api.example.com") as client:
    response = await client.get("/characters")
    characters = response.json()
    
    response = await client.post("/characters", json={"name": "Hero"})
    new_char = response.json()

Schema ID Format: python-http:GET:/characters@./client.py

aiohttp Library

import aiohttp

async with aiohttp.ClientSession() as session:
    # GET request
    async with session.get("https://api.example.com/characters") as response:
        characters = await response.json()
    
    # POST request
    async with session.post(
        "https://api.example.com/characters",
        json={"name": "Hero", "class": "Fighter"}
    ) as response:
        new_char = await response.json()
    
    # Property access
    print(new_char["id"], new_char["name"])

Schema ID Format: python-http:POST:/characters@./client.py

Detected Elements:

requests.get(), requests.post(), etc.
httpx.get(), httpx.post(), AsyncClient methods
aiohttp.ClientSession methods
URL extraction (static strings, f-strings)
HTTP method detection
Response property access (dictionary key access)

Usage Example:

const result = await client.callTool("trace_usage", {
  rootDir: "./python-client",
  include: ["**/*.py"],
});
// Returns HTTP client calls with property access patterns

Architecture

Pattern Matcher Framework

The pattern matcher provides an extensible system for detecting code patterns across different frameworks. Located in src/patterns/:

src/patterns/
├── base.ts          # BasePattern abstract class
├── types.ts         # PatternMatch, PatternContext interfaces
├── registry.ts      # PatternRegistry for plugin management
├── extractors.ts    # Node extractors for AST traversal
├── errors.ts        # Pattern-specific error types
├── rest/            # Express, Fastify patterns
├── http-clients/    # fetch, axios patterns
└── graphql/         # Apollo patterns

Supported Pattern Types:

Call patterns: Function/method calls (app.get(), fetch())
Decorator patterns: TypeScript/Python decorators (@Controller())
Property patterns: Object property assignments
Export patterns: Module exports (export const router = ...)
Chain patterns: Method chaining (router.get().post())

Import Resolution

Cross-file type resolution with import graph building. Located in src/languages/import-resolver.ts:

Resolves import { Type } from "./types"
Handles barrel exports (export * from)
Supports path aliases via tsconfig.json
Detects and handles circular dependencies
Caches resolved types for performance

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`

Parameters:

rootDir (required): Root directory of 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, HTTP client calls, and GraphQL hooks, tracking 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):

# mnehmos.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",
});

4. Extract Multiple Formats

// Extract from MCP server
const mcpSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend/mcp",
  include: ["**/*.ts"],
});

// Extract from OpenAPI specification
const openApiSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.openapi.yaml"],
});

// Extract from tRPC router
const trpcSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend/trpc",
  include: ["**/*.router.ts"],
});

// Extract TypeScript interfaces
const interfaceSchemas = await client.callTool("extract_schemas", {
  rootDir: "./shared",
  include: ["**/*.types.ts"],
});

// Extract REST endpoints (Express/Fastify)
const restSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend/routes",
  include: ["**/*.ts"],
});

// Extract GraphQL schemas
const graphqlSchemas = await client.callTool("extract_schemas", {
  rootDir: "./backend/graphql",
  include: ["**/*.graphql", "**/resolvers.ts"],
});

5. Full-Stack GraphQL Validation

// Extract GraphQL schema and resolvers
const producer = await client.callTool("extract_schemas", {
  rootDir: "./backend",
  include: ["**/*.graphql", "**/resolvers/**/*.ts"],
});

// Trace Apollo Client hooks
const consumer = await client.callTool("trace_usage", {
  rootDir: "./frontend/src",
  include: ["**/*.tsx"],
});

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