mcp-server-codebase-analyser

# MCP Server Codebase Analyzer A production-grade MCP (Model Context Protocol) server that analyzes TypeScript codebases, detects code health issues, fetches system incidents, and generates actionable remediation plans. Supports dual transport (STDIO for local dev, SSE for cloud deployment). Built with ts-morph, Express, and Zod validation. --- ## 🚀 Features ### Three Core Tools: 1. **`analyze_codebase_health`** — Scans TypeScript repositories for: - Large files (potential refactoring candidates) - Missing explicit function types (weak typing) - Circular dependencies (architectural issues) - Uses `ts-morph` for AST-level analysis 2. **`fetch_system_incidents`** — Returns structured incident data: - Mock incident data (perfect for testing/demos) - Configurable delays and failure modes - LLM-friendly JSON responses 3. **`generate_remediation_plan`** — Creates actionable fix plans: - Root cause analysis from stack traces - Step-by-step remediation steps - Code suggestions and best practices - Risk level assessment All tools return structured success/error envelopes designed for LLM consumption. ## Architecture Overview ```mermaid flowchart LR Client[McpClient] --> Runtime[RuntimeSelector] Runtime -->|stdio| Stdio[StdioTransportAdapter] Runtime -->|sse| Sse[SseTransportAdapter] Stdio --> Server[McpServer] Sse --> Server Server --> Registry[ToolRegistry] Registry --> ToolA[analyze_codebase_health] Registry --> ToolB[fetch_system_incidents] Registry --> ToolC[generate_remediation_plan] ``` ## Local Run (STDIO) 1. Install dependencies: - `npm install` 2. Start server: - `npm run dev:stdio` 3. The server starts over stdin/stdout and is ready for local MCP clients. ## Run with SSE (Express) 1. Set environment: - `TRANSPORT=sse` - optional: `AUTH_TOKEN=your-secret-token` 2. Start server: - `npm run dev:sse` 3. Endpoints: - `GET /events` for SSE stream - `POST /messages?sessionId=...` for MCP JSON-RPC messages ## Connect From Cursor For local usage, register Nexus-Core as a stdio MCP server: - command: `node` - args: `dist/index.js` (after build) or `tsx src/index.ts` (dev) - env: `TRANSPORT=stdio` For hosted usage, configure your MCP client to use the SSE endpoint: - stream URL: `https://<host>/events` - message URL: `https://<host>/messages?sessionId=<session-id>` - add `Authorization: Bearer <AUTH_TOKEN>` if token auth is enabled. ## Example Prompts - "Analyze my repo" - "Fetch incidents" - "Fix this error" ## Environment Variables See `.env.example` for all supported settings. Important controls: - `TRANSPORT`: `stdio` or `sse` - `TOOL_TIMEOUT_MS`: hard timeout for each tool call - `TS_MORPH_MAX_FILES`, `TS_MORPH_MAX_DEPTH`: analysis guardrails - `INCIDENT_API_TIMEOUT_MS`, `INCIDENT_API_RETRIES`: external dependency controls - `SSE_HEARTBEAT_MS`, `SSE_SESSION_TTL_MS`: SSE session lifecycle ## Production Deployment ### Docker - Build image: `docker build -t nexus-core .` - Run container: - `docker run -e TRANSPORT=sse -e PORT=8080 -p 8080:8080 nexus-core` ### Cloud Run Use `deploy.sh`: ```bash PROJECT_ID=<gcp-project> REGION=<region> SERVICE=nexus-core ./deploy.sh ``` This script: 1. Builds container image 2. Pushes to GCR 3. Deploys to Cloud Run ## Reliability and Error Model - All tool requests are validated with Zod. - No tool execution returns unhandled exceptions. - Errors use a standard envelope with: - `code` - `message` - `retryable` - `suggestedAction` - `meta` (`requestId`, `toolName`, timing)