MCP Coding Advisor

Senior developer escalation MCP server that provides troubleshooting and implementation guidance.

Overview

This MCP server exposes a single advise tool that coding agents (like Kilo Code) can call to get senior-engineer guidance. It enriches requests with skills lookup, Context7 documentation, and web search when needed, then calls Claude via APIPie.ai to generate structured responses.

Features

• Two modes: Troubleshoot bugs/errors or get implementation plans for new features
• Enrichment pipeline: Parallel skills lookup and Context7 documentation search
• Intelligent fallback: Web search augmentation when no enrichment data is found
• Structured output: Consistent markdown formatting for both modes
• Production-ready: Robust error handling, timeouts, and logging to stderr

Installation

npm install

Development

# Run in development mode (uses tsx)
npm run dev

# Type check
npm run type-check

# Build for production
npm run build

# Run built version
npm start

Configuration

Environment Variables

Create a .env file (for development) or set these in your MCP server configuration:

# Required
APIPIE_API_KEY=your-apipie-key-here

# Optional
APIPIE_MODEL=claude-sonnet-4-5  # or any APIPie-supported model
CONTEXT7_API_KEY=your-context7-key-here  # for higher rate limits

Kilo Code MCP Configuration

Add the following to your Kilo Code MCP settings file:

Linux: ~/.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json macOS: ~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json Windows: %APPDATA%\Code\User\globalStorage\kilocode.kilo-code\settings\mcp_settings.json

{
  "mcpServers": {
    "coding-advisor": {
      "command": "npx",
      "args": ["tsx", "/home/kilroy/build/escalate_mcp/src/index.ts"],
      "env": {
        "APIPIE_API_KEY": "your-apipie-key-here",
        "CONTEXT7_API_KEY": "your-context7-key-here"
      }
    }
  }
}

Important: Use the absolute path to your project directory. The example above assumes the project is at /home/kilroy/build/escalate_mcp.

Usage

The agent calls the advise tool with a JSON string payload. Two modes are supported:

Troubleshoot Mode

{
  "mode": "troubleshoot",
  "tech": "nestjs",
  "task": "JWT guard blocking WebSocket connections",
  "errorOutput": "UnauthorizedException: Unauthorized...",
  "failedAttempts": [
    {
      "description": "Added @UseGuards(JwtAuthGuard) to gateway class",
      "outcome": "All connections rejected immediately"
    }
  ],
  "codeSnippets": [
    {
      "filename": "chat.gateway.ts",
      "code": "@UseGuards(JwtAuthGuard)\n@WebSocketGateway()\nexport class ChatGateway {}"
    }
  ]
}

Implement Mode

{
  "mode": "implement",
  "tech": "react",
  "featureDescription": "Add dark mode toggle to the header",
  "filesTouched": [
    {
      "path": "src/components/Header.tsx",
      "relevantContent": "export default function Header() {\n  return (\n    <header>\n      <h1>My App</h1>\n    </header>\n  );\n}"
    }
  ],
  "constraints": "Must use existing theme context, no new dependencies"
}

Response Format

Troubleshoot Mode Response

• Issue: One clear sentence naming the problem
• Why previous attempts missed: Explanation of why each failed attempt didn't work
• Root cause: The actual technical reason, specific
• Solution: Step-by-step fix, no fluff
• Example: Minimal targeted code snippet showing the fix
• Watch out for: Gotchas, follow-up issues, things to verify after the fix

Implement Mode Response

• Overview: 2-3 sentences on the approach and why
• Files to modify: Markdown table with File, Change, Reason
• Implementation steps: Numbered, in the order to implement them
• Key code patterns: Critical interfaces, function signatures, or tricky logic
• Integration points: How this feature wires into the existing system
• Risks / watch out for: Gotchas specific to this codebase or stack

Architecture

The server follows a clean pipeline:

1. Input Validation: Zod schema validation of the JSON payload
2. Enrichment: Parallel skills lookup (via npx skills find) and Context7 documentation search
3. Prompt Building: System prompt assembly with enrichment data, user message with structured format requirements
4. LLM Call: APIPie.ai call with optional web search prefix
5. Response Assembly: Metadata header + LLM response

Error Handling

• Schema validation errors return clear messages for agent self-correction
• Skills and Context7 failures degrade gracefully (treated as found: false)
• LLM call failures return isError: true with descriptive messages
• All unexpected errors are caught and logged to stderr

Project Structure

src/
  index.ts          # MCP server entrypoint, tool registration, orchestration
  schema.ts         # Zod schemas for both request modes
  prompt-builder.ts # System prompt + user message assembly
  skills.ts         # npx skills find subprocess runner
  context7.ts       # Context7 REST API client
  llm.ts            # APIPie.ai call (OpenAI-compatible)

Dependencies

• @modelcontextprotocol/sdk: Official MCP server SDK
• zod: Runtime schema validation and type inference
• typescript, tsx, @types/node: Development tooling

License

MIT