context-aware-mcp

A configurable MCP (Model Context Protocol) server with intelligent API routing across microservices. Define your services in JSON, and the server automatically routes natural language queries to the right endpoint.

Quick Start

# Initialize config with a template
npx context-aware-mcp init --template openstore

# Or start with a blank config
npx context-aware-mcp init

Installation

npm install -g context-aware-mcp

Or use directly with npx:

npx context-aware-mcp <command>

CLI Commands

All config commands support both --flags mode and interactive mode (run without flags for prompts).

Config Format

Services are defined in mcp-config.json:

{
  "$schema": "./mcp-config.schema.json",
  "version": "1.0",
  "defaults": { "environment": "qa", "swaggerPath": "/api/docs-json" },
  "services": {
    "my-service": {
      "keywords": ["order", "checkout"],
      "idPrefixes": ["ordr_"],
      "type": "rest",
      "environments": {
        "qa": { "url": "https://qa-my-service.example.com" },
        "local": { "url": "http://localhost:3001" }
      }
    }
  },
  "environmentKeywords": {
    "qa": ["from qa", "in qa"],
    "local": ["locally", "from local"]
  }
}

MCP Integration

Generate Claude Code or VS Code config:

# Project-level Claude Code config (.mcp.json)
npx context-aware-mcp install

# VS Code config (.vscode/mcp.json)
npx context-aware-mcp install --target vscode

# Both
npx context-aware-mcp install --target all

MCP Tools

The server exposes these tools to AI assistants:

• smart_api_call — Intelligent routing from natural language queries
• fetch_swagger — Fetch and cache OpenAPI specs
• call_api — Direct API calls to service endpoints
• list_services — List available services
• kafka_list_topics / kafka_describe_topic / kafka_read_messages / kafka_consumer_groups — Kafka operations

Development

npm install
npm run build
npm test

See CONTRIBUTING.md for details.

License

MIT