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

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:

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)