Metadata-Version: 2.4
Name: cortexdb-mcp
Version: 0.3.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.

> **0.3.0 rewrites the server against the v1 CortexDB API.** Default surface is now `https://api-v1.cortexdb.ai`. The server **auto-signs-up anonymously** on first launch — no API key required.

## Quick Start

```bash
# Install (the PyPI name is `cortexdb-mcp`)
pip install cortexdb-mcp

# Then run with zero config:
cortexdb-mcp
```

That's it. On first launch the server hits `POST /v1/auth/signup`, mints a free-tier PASETO token + scope for itself, and caches them under `~/.config/cortexdb-mcp/state.json` (Linux/macOS) or `%APPDATA%\cortexdb-mcp\state.json` (Windows). Re-launches reuse the cached identity until the token expires (7 days).

To target a custom deployment or pre-existing identity, set any of:

```bash
export CORTEXDB_URL="https://api-v1.cortexdb.ai"   # base URL
export CORTEXDB_API_KEY="v4.public..."             # PASETO bearer token
export CORTEXDB_ACTOR="user:alice"                 # ActorId, sent as X-Cortex-Actor
export CORTEXDB_SCOPE="org:acme/user:alice"        # default scope path
```

## IDE Setup

Most clients just need a single line — the auto-signup handles the rest.

### 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"
    }
  }
}
```

### Claude Code (CLI)

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

```json
{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp"
    }
  }
}
```

### Cursor

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

```json
{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp"
    }
  }
}
```

Or in Cursor Settings > MCP Servers > Add Server.

### Windsurf

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

```json
{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp"
    }
  }
}
```

### VS Code (GitHub Copilot)

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

```json
{
  "servers": {
    "cortexdb": {
      "command": "cortexdb-mcp"
    }
  }
}
```

### Windows tip

On Windows, MCP clients sometimes need the absolute path:

```json
{
  "mcpServers": {
    "cortexdb": {
      "command": "C:\\Python310\\Scripts\\cortexdb-mcp.exe"
    }
  }
}
```

## Tools

### Memory Operations

| Tool | Maps to | Description |
|------|---------|-------------|
| `memory_store` | `POST /v1/experience` | Store a new memory. Source/tags/type become labels. |
| `memory_search` | `POST /v1/recall` | Search memories using natural language. |
| `memory_forget` | `POST /v1/forget` | Delete memories. With `query`, narrows by subject. |
| `get_context` | `POST /v1/recall` (holistic) | Deep context with facts + beliefs. |
| `advanced_search` | `POST /v1/recall` + temporal | Search with structured filters (time / source / type). |

### Event CRUD

| Tool | Maps to | Description |
|------|---------|-------------|
| `memory_list` | `GET /v1/events` | List events in scope, paginated. |
| `memory_get` | `GET /v1/events/{id}` | Fetch a single event (used for citations). |
| `memory_delete` | `POST /v1/forget` (memory_ids) | Delete one event by id. |
| `memory_bulk_delete` | `POST /v1/forget` or `/v1/erasures/preview` | Bulk delete with dry-run support. |

### Knowledge Graph (facts-backed in v1)

| Tool | Maps to | Description |
|------|---------|-------------|
| `entity_list` | `GET /v1/facts` | List fact subjects, ranked by count. |
| `entity_get` | `GET /v1/facts?subject=…` | Fact lineage for a subject. |
| `entity_edges` | `GET /v1/facts?subject=…` | Predicate/object pairs for an entity. |
| `entity_link` | `POST /v1/experience` | Store a sentence the extractor will turn into a fact. |

### Admin & Observability

| Tool | Maps to | Description |
|------|---------|-------------|
| `health_check` | `GET /v1/auth/whoami` | Verify the bearer + reach the deployment policy. |
| `get_usage` | `GET /v1/auth/whoami` + headers | Tier, rate limit, token expiry. |
| `get_insights` | (in-process) | Proactive insights derived from stored episodes. |

### Removed from 0.3.0

`memory_update`, `export_data`, `import_data`, `get_ontology` — v1 has no direct equivalents. Updates: store a new event; bulk import: see `/v1/import` directly with the v1 envelope shape; ontology: not part of the v1 surface.

## 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` | `https://api.cortexdb.ai` | 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.

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