context-aware-mcp

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

| Command | Description | |---------|-------------| | init | Create a new mcp-config.json (blank or from template) | | add-service | Add a service to config | | add-env | Add an environment URL to a service | | set-swagger | Set swagger path for a service | | remove-service | Remove a service | | remove-env | Remove an environment from a service | | list | List configured services | | validate | Validate mcp-config.json | | build | Compile TypeScript | | install | Generate MCP config for Claude Code or VS Code |

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