PT-MCP (Paul Test Man Context Protocol)

# 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 ```bash npm install npm run build ``` ## Usage ### As an MCP Server Add to your Claude Code configuration (`~/.config/claude/config.json`): ```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. ```typescript { 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:** ```json { "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. ```typescript { 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. ```typescript { 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. ```typescript { 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. ```typescript { 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. ```typescript { 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. ```typescript { 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. ```typescript { 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: ```bash # 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](../context-manager-mcp-spec.md) 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](https://gigamind.dev/context) - VS Code extension for context management - [Kilo Code CLI](../projects/kilocode/cli/) - CLI wrapper for VS Code extensions - [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol specification