Metadata-Version: 2.4
Name: cortexdb-mcp
Version: 0.2.0
Summary: MCP Server for CortexDB — expose memory operations to AI agents
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: uvicorn>=0.29
Description-Content-Type: text/markdown

# CortexDB MCP Server

MCP (Model Context Protocol) server that gives AI tools persistent long-term memory via CortexDB. Works with Claude Desktop, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

## Quick Start

```bash
# Install
pip install -e .

# Or with uvx (no install needed)
uvx --from . cortexdb-mcp
```

Set your environment variables:

```bash
export CORTEXDB_URL="https://api.cortexdb.ai"   # or http://localhost:3141
export CORTEXDB_API_KEY="cx_live_your_key_here"
```

Run:

```bash
cortexdb-mcp
```

## IDE Setup

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}
```

### Claude Code (CLI)

Edit `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}
```

Or in Cursor Settings > MCP Servers > Add Server.

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}
```

### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json` in your project or `~/.vscode/mcp.json` globally:

```json
{
  "servers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}
```

### Docker

```bash
docker build -t cortexdb-mcp .
docker run -e CORTEXDB_URL=https://api.cortexdb.ai -e CORTEXDB_API_KEY=cx_live_... cortexdb-mcp
```

## Tools

### Memory Operations

| Tool | Description |
|------|-------------|
| `memory_store` | Store a new memory with optional source, type, tags, TTL |
| `memory_search` | Search memories using natural language (hybrid retrieval) |
| `memory_forget` | Delete memories with audit trail (GDPR-compliant) |
| `get_context` | Deep contextual retrieval combining search + graph |
| `advanced_search` | Search with structured filters (source, type, time range) |

### Episode Management

| Tool | Description |
|------|-------------|
| `memory_list` | List episodes with pagination and type filter |
| `memory_get` | Get a specific episode by ID |
| `memory_update` | Update episode content or metadata |
| `memory_delete` | Delete a specific episode by ID |
| `memory_bulk_delete` | Bulk delete with query matching and dry-run support |

### Knowledge Graph

| Tool | Description |
|------|-------------|
| `entity_list` | List entities (people, services, projects, concepts) |
| `entity_get` | Get entity details including relationships and recent episodes |
| `entity_edges` | Get all relationships for an entity |
| `entity_link` | Create a relationship between two entities |

### Admin & Observability

| Tool | Description |
|------|-------------|
| `health_check` | Check CortexDB server health |
| `get_usage` | View usage stats and tier limits |
| `get_insights` | Generate proactive insights (incident spikes, gaps, risks) |
| `get_ontology` | View entity types and relationship types |
| `export_data` | Export memories as JSON |
| `import_data` | Import memories from JSON |

## Resources

Resources provide read-only data that AI tools can access:

| Resource URI | Description |
|---|---|
| `cortexdb://health` | Server health status |
| `cortexdb://metrics` | Request metrics (total, active, errors, rate-limited) |
| `cortexdb://usage` | Usage statistics and tier limits |
| `cortexdb://episodes` | Recent 50 episodes |
| `cortexdb://entities` | Top 100 knowledge graph entities |
| `cortexdb://insights` | Proactive insights |
| `cortexdb://ontology` | Entity and relationship type schema |

## Prompts

Pre-built prompt templates:

| Prompt | Description |
|---|---|
| `investigate_incident` | Investigate an incident using stored memories |
| `summarize_knowledge` | Summarize everything known about a topic |
| `deployment_review` | Pre-deployment safety review |
| `onboard_to_codebase` | Onboard to a codebase using stored knowledge |
| `weekly_digest` | Generate a weekly activity summary |

## Configuration

| Environment Variable | Default | Description |
|---|---|---|
| `CORTEXDB_URL` | `http://localhost:3141` | CortexDB server URL |
| `CORTEXDB_API_KEY` | (none) | API key for authentication |
| `CORTEXDB_TIMEOUT` | `30.0` | HTTP request timeout (seconds) |

## Examples

### Store a memory from Cursor

Ask your AI assistant:
> "Remember that the payments service was migrated to Stripe v3 on March 15th"

The assistant will call `memory_store` with the content.

### Search memories

> "What do we know about the payments service?"

The assistant calls `memory_search` and gets relevant context from CortexDB.

### Explore the knowledge graph

> "Show me all entities related to the auth service"

The assistant calls `entity_get` or `entity_edges` to traverse relationships.

### Pre-deployment review

> "Run a deployment review for the user-service"

Uses the `deployment_review` prompt to check for recent incidents, dependencies, and risks.

## Development

```bash
# Install in dev mode
pip install -e ".[dev]"

# Run tests
pytest

# Run the server locally
CORTEXDB_URL=http://localhost:3141 CORTEXDB_API_KEY=test cortexdb-mcp
```

## Architecture

```
┌─────────────┐     stdio/SSE     ┌──────────────┐     HTTP     ┌──────────┐
│  AI Client  │ ◄──────────────► │  MCP Server  │ ◄──────────► │ CortexDB │
│  (Cursor,   │     MCP JSON-RPC  │  (this pkg)  │   REST API   │  Server  │
│   Claude,   │                   │              │              │          │
│   VS Code)  │                   └──────────────┘              └──────────┘
└─────────────┘
```

The MCP server is a thin translation layer:
1. Receives MCP tool calls from the AI client
2. Translates them to CortexDB REST API calls
3. Formats responses for the AI to consume

## License

MIT
