Claude Code Connector MCP

# Quick Start Guide Get started building the Claude Code Connector MCP in 5 minutes. --- ## Prerequisites - Node.js 18+ installed - TypeScript knowledge - Familiarity with MCP protocol (read [MCP docs](https://modelcontextprotocol.io/docs)) - Claude Desktop installed (for testing) --- ## Initial Setup ### 1. Install Dependencies ```bash cd claude-code-connector-mcp npm install ``` This installs: - `@modelcontextprotocol/sdk` - MCP protocol implementation - `zod` - Runtime validation - TypeScript tooling - Jest for testing ### 2. Verify Build Works ```bash npm run build ``` Should compile TypeScript to `dist/` directory. ### 3. Run Tests (Currently Empty) ```bash npm test ``` Should pass (no tests yet). --- ## Project Structure ``` claude-code-connector-mcp/ ├── PRODUCT_SPEC.md # Complete product specification (READ THIS) ├── ROADMAP.md # Implementation phases ├── AGENT_INSTRUCTIONS.md # Developer guidelines (READ THIS) ├── TODO.md # Implementation checklist ├── README.md # Project overview ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── jest.config.js # Jest test configuration ├── src/ │ ├── index.ts # MCP server entry point (START HERE) │ ├── models/ │ │ └── types.ts # TypeScript types and interfaces │ ├── tools/ # Tool implementations (Phase 1) │ ├── services/ # Business logic │ ├── resources/ # MCP resources (Phase 4) │ ├── prompts/ # MCP prompts (Phase 4) │ └── utils/ # Utilities └── tests/ ├── unit/ # Unit tests ├── integration/ # Integration tests └── e2e/ # End-to-end tests ``` --- ## What to Read First **CRITICAL - Read in this order**: 1. **[PRODUCT_SPEC.md](./PRODUCT_SPEC.md)** (30 min) - Complete feature specification - All tools, resources, prompts, slash commands - Data models and examples 2. **[AGENT_INSTRUCTIONS.md](./AGENT_INSTRUCTIONS.md)** (15 min) - Development guidelines - Code standards - Testing approach 3. **[ROADMAP.md](./ROADMAP.md)** (10 min) - Implementation phases - Timeline and priorities - Success criteria 4. **[src/models/types.ts](./src/models/types.ts)** (5 min) - Data structures - Type definitions --- ## Start Development - Phase 1 ### Step 1: Implement `register_project` Tool **File**: `src/tools/register_project.ts` ```typescript import { Project, RegisterProjectArgs, MCPError, ErrorCode } from '../models/types'; import { ProjectManager } from '../services/project_manager'; export async function registerProject(args: RegisterProjectArgs): Promise<{ success: boolean; projectId: string; message: string; }> { // TODO: Implement // 1. Validate arguments // 2. Check if project already exists // 3. Validate path exists // 4. Generate ID if not provided // 5. Save to projects.json // 6. Return success throw new Error('Not implemented'); } ``` ### Step 2: Create ProjectManager Service **File**: `src/services/project_manager.ts` ```typescript import { Project, ProjectRegistry } from '../models/types'; import { readFile, writeFile } from 'fs/promises'; import { homedir } from 'os'; import { join } from 'path'; export class ProjectManager { private projectsPath: string; constructor() { this.projectsPath = join(homedir(), '.claude', 'projects.json'); } async loadProjects(): Promise<ProjectRegistry> { // TODO: Implement // 1. Read projects.json // 2. Parse JSON // 3. Return registry // Handle file not existing (return empty) throw new Error('Not implemented'); } async saveProjects(registry: ProjectRegistry): Promise<void> { // TODO: Implement // 1. Create .claude directory if needed // 2. Write JSON to file // 3. Handle errors throw new Error('Not implemented'); } async addProject(project: Project): Promise<void> { // TODO: Implement throw new Error('Not implemented'); } async getProject(id: string): Promise<Project | null> { // TODO: Implement throw new Error('Not implemented'); } } ``` ### Step 3: Wire Up to MCP Server **File**: `src/index.ts` Update the `CallToolRequestSchema` handler: ```typescript server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { switch (name) { case 'register_project': { const result = await registerProject(args as RegisterProjectArgs); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } default: throw new Error(`Unknown tool: ${name}`); } } catch (error) { if (error instanceof MCPError) { return { content: [ { type: 'text', text: JSON.stringify({ error: error.code, message: error.message, suggestion: error.suggestion, }, null, 2), }, ], isError: true, }; } throw error; } }); ``` ### Step 4: Write Tests **File**: `tests/unit/register_project.test.ts` ```typescript import { registerProject } from '../../src/tools/register_project'; import { ErrorCode } from '../../src/models/types'; describe('register_project', () => { it('should register a valid project', async () => { const result = await registerProject({ name: 'Test Project', rootPath: '/tmp/test-project', }); expect(result.success).toBe(true); expect(result.projectId).toBeDefined(); }); it('should reject non-existent path', async () => { await expect( registerProject({ name: 'Bad Project', rootPath: '/nonexistent/path', }) ).rejects.toThrow(); }); // Add more tests... }); ``` ### Step 5: Test Locally ```bash # Build npm run build # Configure Claude Desktop # Edit: ~/Library/Application Support/Claude/claude_desktop_config.json { "mcpServers": { "claude-code": { "command": "node", "args": ["/absolute/path/to/dist/index.js"] } } } # Restart Claude Desktop # Try: "Register a project called 'test' at /tmp/test" ``` --- ## Development Workflow ### Daily Workflow ```bash # Start TypeScript watch mode npm run dev # In another terminal, run tests on changes npm test -- --watch # Make changes, tests re-run automatically ``` ### Commit Workflow ```bash # Make changes git add . git commit -m "feat: implement register_project tool" # Run full test suite npm test # Build to verify npm run build # Push git push origin phase-1/register-project ``` --- ## Testing Your MCP Server ### 1. Unit Tests (Fastest) ```bash npm test ``` ### 2. Integration Tests ```bash npm run test:integration ``` ### 3. Manual Testing with Claude Desktop 1. Build: `npm run build` 2. Configure Claude Desktop (see above) 3. Restart Claude Desktop 4. Test tools in conversation ### 4. Debugging Add to `src/index.ts`: ```typescript console.error('Tool called:', name, args); ``` View logs in Claude Desktop: Help → Show Debug Logs --- ## Common Issues ### "Module not found" ```bash npm install npm run build ``` ### "Tool not responding" Check Claude Desktop debug logs. Ensure: - Path in config is absolute - File is built (`dist/index.js` exists) - No syntax errors (check `npm run build`) ### "Tests failing" ```bash # Clear jest cache npx jest --clearCache # Run specific test npm test -- register_project.test.ts ``` --- ## Next Steps 1. ✅ Read PRODUCT_SPEC.md 2. ✅ Read AGENT_INSTRUCTIONS.md 3. ✅ Install dependencies 4. ⏭️ Implement `register_project` tool 5. ⏭️ Implement ProjectManager service 6. ⏭️ Write tests 7. ⏭️ Test manually in Claude Desktop 8. ⏭️ Continue to next tool in Phase 1 --- ## Getting Help - **Product questions**: Ask Brian (PM) - **Technical questions**: Check MCP docs, then ask Brian - **Stuck**: Update TODO.md with blocker, ask Brian --- ## Resources - **MCP SDK Docs**: https://github.com/modelcontextprotocol/typescript-sdk - **MCP Protocol**: https://modelcontextprotocol.io/docs - **TypeScript Handbook**: https://www.typescriptlang.org/docs/handbook/ - **Jest Docs**: https://jestjs.io/docs/getting-started --- **Ready to start? Begin with Phase 1, register_project tool. Good luck!**