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