mnehmos.trace.mcp 1.0.0

package/README.md

@@ -0,0 +1,1662 @@
+# 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
+
+```bash
+# 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):
+
+```json
+{
+  "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.
+
+```typescript
+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.
+
+```yaml
+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:**
+
+```typescript
+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`.
+
+```typescript
+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:**
+
+```typescript
+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.
+
+```typescript
+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:**
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:**
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+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:**
+
+```typescript
+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
+
+```graphql
+# 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
+
+```typescript
+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
+
+```typescript
+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:**
+
+```typescript
+// 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
+
+```python
+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
+
+```python
+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)
+
+```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
+
+```python
+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:**
+
+```typescript
+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
+
+```go
+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
+
+```go
+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
+
+```go
+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
+
+```go
+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
+
+```go
+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:**
+
+```typescript
+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
+
+```protobuf
+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
+
+```protobuf
+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
+
+```protobuf
+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
+
+```protobuf
+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
+
+```protobuf
+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:**
+
+```typescript
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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:**
+
+```typescript
+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/):
+
+```
+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`](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:**
+
+```typescript
+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):**
+
+```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:**
+
+```typescript
+/**
+ * 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:**
+
+```typescript
+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:**
+
+```javascript
+// 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:**
+
+```typescript
+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:**
+
+```json
+{
+  "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
+
+```typescript
+// 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)
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+- [x] MCP tool schema extraction
+- [x] Consumer usage tracing
+- [x] Basic mismatch detection
+- [x] Code scaffolding (consumer & producer)
+- [x] Contract comments
+- [x] Watch mode with auto-revalidation
+- [x] OpenAPI/Swagger adapter support
+- [x] TypeScript interface extraction
+- [x] tRPC router support
+- [x] Pluggable adapter registry
+- [x] Pattern Matcher abstraction (Phase 2)
+- [x] Cross-file import resolution (Phase 2)
+- [x] REST endpoint detection - Express & Fastify (Phase 2)
+- [x] HTTP client tracing - fetch & axios (Phase 2)
+- [x] GraphQL support - SDL, Apollo Server, Apollo Client (Phase 2)
+- [x] Python language support - FastAPI, Flask, MCP tools, Pydantic (Phase 3)
+- [x] Go language support - Chi, Gin, stdlib handlers, structs (Phase 3)
+- [x] gRPC/Protobuf support - proto3, messages, services, streaming (Phase 3)
+- [x] Python HTTP client tracing - requests, httpx, aiohttp (Phase 3)
+
+### Planned
+
+- [ ] JSON Schema adapter
+- [ ] WebSocket message tracing
+- [ ] OpenTelemetry integration
+- [ ] Rust language support
+- [ ] Java/Kotlin language support
+
+## License
+
+MIT