.cline•5.31 kB
# TypeScript API MCP Server Architecture
## System Overview
The TypeScript API MCP Server is designed to provide AI agents with the ability to efficiently query and understand TypeScript APIs. It loads TypeDoc-generated JSON documentation and exposes it through a set of query endpoints following the Model Context Protocol (MCP).
## Components
### 1. TypeDoc Integration
- **Purpose**: Generate structured JSON documentation from TypeScript source code
- **Implementation**: Uses TypeDoc to extract type information, JSDoc comments, and relationships between symbols
- **Input**: TypeScript source files
- **Output**: JSON documentation with detailed API information
### 2. Data Indexing System
- **Purpose**: Efficiently index and organize TypeDoc JSON for fast querying
- **Implementation**: Creates multiple indexes (by ID, name, kind) for quick lookups
- **Key Features**:
- Symbol indexing by ID
- Symbol indexing by name
- Symbol categorization by kind (class, interface, function, etc.)
- Relationship tracking (inheritance, implementation)
### 3. MCP Server
- **Purpose**: Expose TypeScript API information through MCP tools and resources
- **Implementation**: Uses the MCP SDK to create a server with tools and resources
- **Components**:
- Server configuration
- Tool definitions
- Resource templates
- Request handlers
### 4. Query Handlers
- **Purpose**: Process queries and return relevant API information
- **Implementation**: Set of specialized handlers for different query types
- **Key Handlers**:
- Symbol search
- Member listing
- Type hierarchy resolution
- Implementation finding
- Usage discovery
## Data Flow
1. **Documentation Generation**:
- TypeScript source code → TypeDoc → JSON documentation
2. **Server Initialization**:
- Load JSON documentation
- Build indexes
- Register MCP tools and resources
3. **Query Processing**:
- Receive query from agent
- Route to appropriate handler
- Execute query against indexes
- Format and return results
## File Structure
```
typescript-api-mcp/
├── src/
│ ├── sample-api/ # Sample TypeScript API for testing
│ │ ├── types.ts # Type definitions
│ │ ├── task-manager.ts # Classes and implementations
│ │ ├── utils.ts # Utility functions
│ │ └── index.ts # API exports
│ │
│ └── mcp-server/ # MCP server implementation
│ ├── types.ts # Type definitions for the server
│ ├── utils.ts # Utility functions
│ ├── handlers.ts # Query handlers
│ ├── schemas.ts # JSON schemas for tools
│ ├── server.ts # Server implementation
│ └── index.ts # Entry point
│
├── tests/ # Test files
│ └── handlers.test.ts # Tests for API parsing
│
├── docs/ # Generated documentation
│ └── api.json # TypeDoc JSON output
│
├── dist/ # Compiled JavaScript
├── package.json # Project configuration
└── tsconfig.json # TypeScript configuration
```
## Key Interfaces
### TypeDoc JSON Structure
The system works with TypeDoc JSON, which follows this general structure:
```typescript
interface TypeDocJson {
id: number;
name: string;
kind: number;
kindString: string;
children?: TypeDocSymbol[];
}
interface TypeDocSymbol {
id: number;
name: string;
kind: number;
kindString?: string;
comment?: { summary?: Array<{ kind: string; text: string }> };
children?: TypeDocSymbol[];
signatures?: TypeDocSignature[];
type?: TypeDocType;
// ... other properties
}
```
### MCP Tools
The server exposes these main tools:
1. `search_symbols`: Find symbols by name/pattern
2. `get_symbol_details`: Get detailed information about a symbol
3. `list_members`: List class/interface members
4. `get_parameter_info`: Get function parameter details
5. `find_implementations`: Find implementations of interfaces
6. `search_by_return_type`: Find functions by return type
7. `search_by_description`: Search in JSDoc comments
8. `get_type_hierarchy`: Get inheritance relationships
9. `find_usages`: Find symbol usages
## Design Decisions
1. **Separation of Concerns**:
- Split functionality into multiple files for better maintainability
- Clear separation between TypeDoc parsing, indexing, and query handling
2. **Efficient Indexing**:
- Multiple indexes for fast lookups
- In-memory storage for quick access
3. **Comprehensive Query Capabilities**:
- Wide range of tools to cover different query needs
- Support for both direct lookups and relationship exploration
4. **Extensibility**:
- Modular design allows for adding new query capabilities
- Clear interfaces for extending functionality
## Future Enhancements
1. **Persistent Storage**: Option to cache indexed data for faster startup
2. **Advanced Search**: Fuzzy matching and semantic search capabilities
3. **Code Generation**: Generate example code for API usage
4. **Visualization**: Generate visual representations of type hierarchies
5. **Cross-Reference Analysis**: More advanced relationship tracking