# 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