PT-MCP (Paul Test Man Context Protocol)

"Where am I now?"

Named after Paul Marcarelli, the Verizon "Test Man" who famously traversed America asking "Can you hear me now?", PT-MCP asks the essential question for AI coding assistants: "Where am I now?" - providing comprehensive context understanding through integrated knowledge graphs and semantic schemas.

The Paul Test Man Story

Just as Paul Test Man mapped Verizon's network coverage across America to ensure clear communication, PT-MCP maps your codebase's semantic landscape to ensure clear understanding. The server doesn't just return code structure - it returns meaning through:

• YAGO 4.5 Knowledge Graphs: Base knowledge graph segments relevant to your context
• Schema.org Domain Graphs: Domain-specific semantic understanding
• Codebase Analysis: Comprehensive structure, patterns, and relationships

Overview

PT-MCP helps AI coding assistants understand your codebase by providing:

• Comprehensive codebase analysis - File structure, language distribution, code metrics
• Context file generation - Multiple format support (.cursorrules, SPEC.md, etc.)
• Incremental updates - Efficient context regeneration based on changes
• Pattern extraction - Identify architectural and coding patterns
• Dependency analysis - Map internal and external dependencies
• API surface extraction - Document public interfaces
• Context validation - Ensure accuracy and completeness

Installation

npm install
npm run build

Usage

As an MCP Server

Add to your Claude Code configuration (~/.config/claude/config.json):

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

Available Tools

1. analyze_codebase

Perform comprehensive codebase analysis including structure, dependencies, and metrics.

{
  path: string;              // Root directory path
  languages?: string[];      // Languages to analyze (auto-detect if omitted)
  depth?: number;            // Analysis depth (1-5, default: 3)
  include_patterns?: string[]; // Glob patterns to include
  exclude_patterns?: string[]; // Glob patterns to exclude
  analysis_type?: 'quick' | 'standard' | 'deep'; // Default: 'standard'
}

Example:

{
  "path": "/path/to/project",
  "analysis_type": "standard",
  "exclude_patterns": ["**/node_modules/**", "**/.git/**"]
}

Returns:

• Total files, lines, and size
• Language distribution with percentages
• Directory structure and depth
• Entry points identification
• Package information (if available)

2. generate_context

Generate context files in specified format.

{
  path: string;
  format: 'cursorrules' | 'cursor_dir' | 'spec_md' | 'agents_md' | 'custom';
  output_path?: string;
  analysis_result?: any;
  options?: Record<string, any>;
}

Note: Implementation pending (stub currently returns placeholder)

3. update_context

Incrementally update existing context files based on code changes.

{
  path: string;
  changed_files: string[];
  context_format: string;
  force_full_regeneration?: boolean;
}

Note: Implementation pending (stub currently returns placeholder)

4. extract_patterns

Identify and extract architectural and coding patterns.

{
  path: string;
  pattern_types?: string[];
  min_occurrences?: number;
}

Note: Implementation pending (stub currently returns placeholder)

5. analyze_dependencies

Analyze and map internal and external dependencies.

{
  path: string;
  include_external?: boolean;
  include_internal?: boolean;
  max_depth?: number;
}

Note: Implementation pending (stub currently returns placeholder)

6. watch_project

Start monitoring project for changes and auto-update context.

{
  path: string;
  context_formats: string[];
  debounce_ms?: number;
  watch_patterns?: string[];
}

Note: Implementation pending (stub currently returns placeholder)

7. extract_api_surface

Extract and document public API surface.

{
  path: string;
  include_private?: boolean;
  output_format?: 'markdown' | 'json' | 'typescript';
}

Note: Implementation pending (stub currently returns placeholder)

8. validate_context

Validate accuracy and completeness of generated context files.

{
  path: string;
  context_path: string;
  checks?: string[];
}

Note: Implementation pending (stub currently returns placeholder)

Available Resources

context://project/{path}

Current project context including structure, patterns, and dependencies.

context://patterns/{path}

Architectural and coding patterns detected in the codebase.

context://dependencies/{path}

Internal and external dependency relationships.

Development Status

Phase 1: Foundation (✅ Complete)

• [x] MCP server boilerplate with stdio transport
• [x] Project structure and dependencies
• [x] analyze_codebase tool - fully functional
• [x] Stub implementations for remaining tools

Phase 2: Core Analysis (🚧 In Progress)

• [ ] Implement generate_context tool
• [ ] Implement extract_patterns tool
• [ ] Implement analyze_dependencies tool
• [ ] Add tree-sitter integration for deep code analysis

Phase 3: Advanced Features (📋 Planned)

• [ ] Implement update_context tool with incremental updates
• [ ] Implement watch_project tool with file system monitoring
• [ ] Implement extract_api_surface tool
• [ ] Implement validate_context tool

Architecture

context-manager-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/                # Tool implementations
│   │   ├── index.ts          # Tool registration
│   │   ├── analyze-codebase.ts
│   │   ├── generate-context.ts
│   │   ├── update-context.ts
│   │   ├── extract-patterns.ts
│   │   ├── analyze-dependencies.ts
│   │   ├── watch-project.ts
│   │   ├── extract-api-surface.ts
│   │   └── validate-context.ts
│   ├── resources/            # Resource handlers
│   │   └── index.ts
│   ├── analyzers/            # Code analysis engines (future)
│   ├── generators/           # Context generators (future)
│   ├── utils/                # Utility functions (future)
│   └── types/                # TypeScript type definitions (future)
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Testing

Test the MCP server locally:

# Build the project
npm run build

# Test analyze_codebase tool
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"analyze_codebase","arguments":{"path":"/path/to/project","analysis_type":"standard"}}}' | node dist/index.js

Contributing

This is a work in progress. See the specification document for the full implementation roadmap.

Next Steps

1. Implement context file generators for different formats
2. Add tree-sitter integration for deeper code analysis
3. Implement pattern extraction algorithms
4. Add file system watching and incremental updates
5. Create comprehensive test suite

License

MIT

Related Projects

• Giga AI - VS Code extension for context management
• Kilo Code CLI - CLI wrapper for VS Code extensions
• Model Context Protocol - Protocol specification