# 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

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

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

## Installation

```bash
npm install -g context-aware-mcp
```

Or use directly with `npx`:

```bash
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`:

```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:

```bash
# 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

```bash
npm install
npm run build
npm test
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

MIT