cortexdb-mcp 0.2.2__tar.gz → 0.3.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cortexdb_mcp-0.3.1/.gitignore +79 -0
- {cortexdb_mcp-0.2.2 → cortexdb_mcp-0.3.1}/Dockerfile +12 -12
- {cortexdb_mcp-0.2.2 → cortexdb_mcp-0.3.1}/PKG-INFO +91 -73
- cortexdb_mcp-0.3.1/README.md +261 -0
- {cortexdb_mcp-0.2.2 → cortexdb_mcp-0.3.1}/cortexdb_mcp/__init__.py +3 -3
- {cortexdb_mcp-0.2.2 → cortexdb_mcp-0.3.1}/cortexdb_mcp/__main__.py +5 -5
- {cortexdb_mcp-0.2.2 → cortexdb_mcp-0.3.1}/cortexdb_mcp/api.py +132 -132
- cortexdb_mcp-0.3.1/cortexdb_mcp/config.py +145 -0
- {cortexdb_mcp-0.2.2 → cortexdb_mcp-0.3.1}/cortexdb_mcp/insights.py +640 -640
- cortexdb_mcp-0.3.1/cortexdb_mcp/server.py +1028 -0
- {cortexdb_mcp-0.2.2 → cortexdb_mcp-0.3.1}/pyproject.toml +1 -1
- {cortexdb_mcp-0.2.2 → cortexdb_mcp-0.3.1}/tests/test_insights.py +514 -514
- cortexdb_mcp-0.3.1/tests/test_integration.py +67 -0
- cortexdb_mcp-0.3.1/tests/test_server.py +566 -0
- cortexdb_mcp-0.2.2/.gitignore +0 -45
- cortexdb_mcp-0.2.2/README.md +0 -243
- cortexdb_mcp-0.2.2/cortexdb_mcp/config.py +0 -40
- cortexdb_mcp-0.2.2/cortexdb_mcp/server.py +0 -1115
- cortexdb_mcp-0.2.2/tests/test_server.py +0 -223
- {cortexdb_mcp-0.2.2 → cortexdb_mcp-0.3.1}/tests/__init__.py +0 -0
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Rust
|
|
2
|
+
/target
|
|
3
|
+
**/*.rs.bk
|
|
4
|
+
|
|
5
|
+
# Environment / secrets
|
|
6
|
+
.env
|
|
7
|
+
.env.local
|
|
8
|
+
.env*.local
|
|
9
|
+
*.pem
|
|
10
|
+
*.key
|
|
11
|
+
.npmrc
|
|
12
|
+
|
|
13
|
+
# SQLite database
|
|
14
|
+
*.sqlite
|
|
15
|
+
*.sqlite-wal
|
|
16
|
+
*.sqlite-shm
|
|
17
|
+
|
|
18
|
+
# OS
|
|
19
|
+
.DS_Store
|
|
20
|
+
Thumbs.db
|
|
21
|
+
desktop.ini
|
|
22
|
+
|
|
23
|
+
# IDE
|
|
24
|
+
.idea/
|
|
25
|
+
.vscode/
|
|
26
|
+
*.swp
|
|
27
|
+
*.swo
|
|
28
|
+
|
|
29
|
+
# Data directories
|
|
30
|
+
cortexdb_data*/
|
|
31
|
+
/data/
|
|
32
|
+
# Per-bench tenant stores (RocksDB + Tantivy + HNSW state; regeneratable per run)
|
|
33
|
+
/data_*/
|
|
34
|
+
# Experimental per-branch stores (not tracked on this branch but left gitignored
|
|
35
|
+
# so checkout from other branches doesn't surface them in git status)
|
|
36
|
+
/event_memory_store/
|
|
37
|
+
/llm_cache/
|
|
38
|
+
|
|
39
|
+
# Benchmark inputs and per-run outputs (kept local, regenerated each run)
|
|
40
|
+
benchmarks/longmemeval/data/
|
|
41
|
+
benchmarks/longmemeval/server_results/
|
|
42
|
+
benchmarks/longmemeval/fast_results/
|
|
43
|
+
benchmarks/longmemeval/micro_results/
|
|
44
|
+
benchmarks/longmemeval/server_logs/
|
|
45
|
+
benchmarks/longmemeval/*.log
|
|
46
|
+
benchmarks/locomo/locomo_results*.json
|
|
47
|
+
benchmarks/locomo/server_results/
|
|
48
|
+
benchmarks/locomo/*.log
|
|
49
|
+
/answer_out.json
|
|
50
|
+
|
|
51
|
+
# Local Claude Code state
|
|
52
|
+
.claude/
|
|
53
|
+
.tmp/
|
|
54
|
+
|
|
55
|
+
# Python
|
|
56
|
+
__pycache__/
|
|
57
|
+
*.pyc
|
|
58
|
+
.venv/
|
|
59
|
+
venv/
|
|
60
|
+
|
|
61
|
+
# Node
|
|
62
|
+
node_modules/
|
|
63
|
+
dist/
|
|
64
|
+
.next/
|
|
65
|
+
|
|
66
|
+
# Egg info
|
|
67
|
+
*.egg-info/
|
|
68
|
+
|
|
69
|
+
# Scratch/debug text files at root
|
|
70
|
+
/*.txt
|
|
71
|
+
/*.log
|
|
72
|
+
|
|
73
|
+
# Local debug / marketing / private content (not for repo)
|
|
74
|
+
harness/.reports/
|
|
75
|
+
harness_data_*/
|
|
76
|
+
blog/
|
|
77
|
+
sales/
|
|
78
|
+
videos/
|
|
79
|
+
local-instance/
|
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
FROM python:3.12-slim
|
|
2
|
-
|
|
3
|
-
WORKDIR /app
|
|
4
|
-
|
|
5
|
-
COPY pyproject.toml README.md ./
|
|
6
|
-
COPY cortexdb_mcp/ cortexdb_mcp/
|
|
7
|
-
|
|
8
|
-
RUN pip install --no-cache-dir .
|
|
9
|
-
|
|
10
|
-
ENV CORTEXDB_URL=https://api.cortexdb.ai
|
|
11
|
-
|
|
12
|
-
CMD ["cortexdb-mcp"]
|
|
1
|
+
FROM python:3.12-slim
|
|
2
|
+
|
|
3
|
+
WORKDIR /app
|
|
4
|
+
|
|
5
|
+
COPY pyproject.toml README.md ./
|
|
6
|
+
COPY cortexdb_mcp/ cortexdb_mcp/
|
|
7
|
+
|
|
8
|
+
RUN pip install --no-cache-dir .
|
|
9
|
+
|
|
10
|
+
ENV CORTEXDB_URL=https://api-v1.cortexdb.ai
|
|
11
|
+
|
|
12
|
+
CMD ["cortexdb-mcp"]
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: cortexdb-mcp
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.1
|
|
4
4
|
Summary: MCP Server for CortexDB — expose memory operations to AI agents
|
|
5
5
|
License-Expression: MIT
|
|
6
6
|
Requires-Python: >=3.10
|
|
@@ -15,31 +15,33 @@ Description-Content-Type: text/markdown
|
|
|
15
15
|
|
|
16
16
|
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.
|
|
17
17
|
|
|
18
|
+
> **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.
|
|
19
|
+
|
|
18
20
|
## Quick Start
|
|
19
21
|
|
|
20
22
|
```bash
|
|
21
|
-
# Install
|
|
22
|
-
pip install -
|
|
23
|
+
# Install (the PyPI name is `cortexdb-mcp`)
|
|
24
|
+
pip install cortexdb-mcp
|
|
23
25
|
|
|
24
|
-
#
|
|
25
|
-
|
|
26
|
+
# Then run with zero config:
|
|
27
|
+
cortexdb-mcp
|
|
26
28
|
```
|
|
27
29
|
|
|
28
|
-
|
|
30
|
+
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).
|
|
29
31
|
|
|
30
|
-
|
|
31
|
-
export CORTEXDB_URL="https://api.cortexdb.ai"
|
|
32
|
-
export CORTEXDB_API_KEY="cx_live_your_key_here"
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
Run:
|
|
32
|
+
To target a custom deployment or pre-existing identity, set any of:
|
|
36
33
|
|
|
37
34
|
```bash
|
|
38
|
-
cortexdb
|
|
35
|
+
export CORTEXDB_URL="https://api-v1.cortexdb.ai" # base URL
|
|
36
|
+
export CORTEXDB_API_KEY="v4.public..." # PASETO bearer token
|
|
37
|
+
export CORTEXDB_ACTOR="user:alice" # ActorId, sent as X-Cortex-Actor
|
|
38
|
+
export CORTEXDB_SCOPE="org:acme/user:alice" # default scope path
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
## IDE Setup
|
|
42
42
|
|
|
43
|
+
Most clients just need a single line — the auto-signup handles the rest.
|
|
44
|
+
|
|
43
45
|
### Claude Desktop
|
|
44
46
|
|
|
45
47
|
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
@@ -48,16 +50,34 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
|
|
|
48
50
|
{
|
|
49
51
|
"mcpServers": {
|
|
50
52
|
"cortexdb": {
|
|
51
|
-
"command": "cortexdb-mcp"
|
|
52
|
-
"env": {
|
|
53
|
-
"CORTEXDB_URL": "https://api.cortexdb.ai",
|
|
54
|
-
"CORTEXDB_API_KEY": "cx_live_your_key_here"
|
|
55
|
-
}
|
|
53
|
+
"command": "cortexdb-mcp"
|
|
56
54
|
}
|
|
57
55
|
}
|
|
58
56
|
}
|
|
59
57
|
```
|
|
60
58
|
|
|
59
|
+
> **Windows note (audit POL-3):** if Claude Desktop / Cursor / Windsurf
|
|
60
|
+
> can't find `cortexdb-mcp` on PATH, give it the full path to the
|
|
61
|
+
> installed executable:
|
|
62
|
+
>
|
|
63
|
+
> ```json
|
|
64
|
+
> {
|
|
65
|
+
> "mcpServers": {
|
|
66
|
+
> "cortexdb": {
|
|
67
|
+
> "command": "C:\\Python313\\Scripts\\cortexdb-mcp.exe"
|
|
68
|
+
> }
|
|
69
|
+
> }
|
|
70
|
+
> }
|
|
71
|
+
> ```
|
|
72
|
+
>
|
|
73
|
+
> Locate it with `where cortexdb-mcp` in `cmd.exe` or
|
|
74
|
+
> `(Get-Command cortexdb-mcp).Source` in PowerShell.
|
|
75
|
+
>
|
|
76
|
+
> Some Windows terminals don't have UTF-8 enabled by default, which can
|
|
77
|
+
> garble emoji in `--help` output (they show as `?`). The server itself
|
|
78
|
+
> isn't affected — only the CLI banner. Run
|
|
79
|
+
> `chcp 65001` once per terminal session to fix.
|
|
80
|
+
|
|
61
81
|
### Claude Code (CLI)
|
|
62
82
|
|
|
63
83
|
Edit `~/.claude/mcp.json`:
|
|
@@ -66,11 +86,7 @@ Edit `~/.claude/mcp.json`:
|
|
|
66
86
|
{
|
|
67
87
|
"mcpServers": {
|
|
68
88
|
"cortexdb": {
|
|
69
|
-
"command": "cortexdb-mcp"
|
|
70
|
-
"env": {
|
|
71
|
-
"CORTEXDB_URL": "https://api.cortexdb.ai",
|
|
72
|
-
"CORTEXDB_API_KEY": "cx_live_your_key_here"
|
|
73
|
-
}
|
|
89
|
+
"command": "cortexdb-mcp"
|
|
74
90
|
}
|
|
75
91
|
}
|
|
76
92
|
}
|
|
@@ -84,11 +100,7 @@ Edit `~/.cursor/mcp.json`:
|
|
|
84
100
|
{
|
|
85
101
|
"mcpServers": {
|
|
86
102
|
"cortexdb": {
|
|
87
|
-
"command": "cortexdb-mcp"
|
|
88
|
-
"env": {
|
|
89
|
-
"CORTEXDB_URL": "https://api.cortexdb.ai",
|
|
90
|
-
"CORTEXDB_API_KEY": "cx_live_your_key_here"
|
|
91
|
-
}
|
|
103
|
+
"command": "cortexdb-mcp"
|
|
92
104
|
}
|
|
93
105
|
}
|
|
94
106
|
}
|
|
@@ -104,11 +116,7 @@ Edit `~/.codeium/windsurf/mcp_config.json`:
|
|
|
104
116
|
{
|
|
105
117
|
"mcpServers": {
|
|
106
118
|
"cortexdb": {
|
|
107
|
-
"command": "cortexdb-mcp"
|
|
108
|
-
"env": {
|
|
109
|
-
"CORTEXDB_URL": "https://api.cortexdb.ai",
|
|
110
|
-
"CORTEXDB_API_KEY": "cx_live_your_key_here"
|
|
111
|
-
}
|
|
119
|
+
"command": "cortexdb-mcp"
|
|
112
120
|
}
|
|
113
121
|
}
|
|
114
122
|
}
|
|
@@ -122,11 +130,21 @@ Add to `.vscode/mcp.json` in your project or `~/.vscode/mcp.json` globally:
|
|
|
122
130
|
{
|
|
123
131
|
"servers": {
|
|
124
132
|
"cortexdb": {
|
|
125
|
-
"command": "cortexdb-mcp"
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
133
|
+
"command": "cortexdb-mcp"
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Windows tip
|
|
140
|
+
|
|
141
|
+
On Windows, MCP clients sometimes need the absolute path:
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"mcpServers": {
|
|
146
|
+
"cortexdb": {
|
|
147
|
+
"command": "C:\\Python310\\Scripts\\cortexdb-mcp.exe"
|
|
130
148
|
}
|
|
131
149
|
}
|
|
132
150
|
}
|
|
@@ -136,43 +154,43 @@ Add to `.vscode/mcp.json` in your project or `~/.vscode/mcp.json` globally:
|
|
|
136
154
|
|
|
137
155
|
### Memory Operations
|
|
138
156
|
|
|
139
|
-
| Tool | Description |
|
|
140
|
-
|
|
141
|
-
| `memory_store` | Store a new memory
|
|
142
|
-
| `memory_search` | Search memories using natural language
|
|
143
|
-
| `memory_forget` | Delete memories
|
|
144
|
-
| `get_context` | Deep
|
|
145
|
-
| `advanced_search` | Search with structured filters (source
|
|
146
|
-
|
|
147
|
-
###
|
|
148
|
-
|
|
149
|
-
| Tool | Description |
|
|
150
|
-
|
|
151
|
-
| `memory_list` |
|
|
152
|
-
| `memory_get` |
|
|
153
|
-
| `
|
|
154
|
-
| `
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `entity_link` | Create a relationship between two entities |
|
|
157
|
+
| Tool | Maps to | Description |
|
|
158
|
+
|------|---------|-------------|
|
|
159
|
+
| `memory_store` | `POST /v1/experience` | Store a new memory. Source/tags/type become labels. |
|
|
160
|
+
| `memory_search` | `POST /v1/recall` | Search memories using natural language. |
|
|
161
|
+
| `memory_forget` | `POST /v1/forget` | Delete memories. With `query`, narrows by subject. |
|
|
162
|
+
| `get_context` | `POST /v1/recall` (holistic) | Deep context with facts + beliefs. |
|
|
163
|
+
| `advanced_search` | `POST /v1/recall` + temporal | Search with structured filters (time / source / type). |
|
|
164
|
+
|
|
165
|
+
### Event CRUD
|
|
166
|
+
|
|
167
|
+
| Tool | Maps to | Description |
|
|
168
|
+
|------|---------|-------------|
|
|
169
|
+
| `memory_list` | `GET /v1/events` | List events in scope, paginated. |
|
|
170
|
+
| `memory_get` | `GET /v1/events/{id}` | Fetch a single event (used for citations). |
|
|
171
|
+
| `memory_delete` | `POST /v1/forget` (memory_ids) | Delete one event by id. |
|
|
172
|
+
| `memory_bulk_delete` | `POST /v1/forget` or `/v1/erasures/preview` | Bulk delete with dry-run support. |
|
|
173
|
+
|
|
174
|
+
### Knowledge Graph (facts-backed in v1)
|
|
175
|
+
|
|
176
|
+
| Tool | Maps to | Description |
|
|
177
|
+
|------|---------|-------------|
|
|
178
|
+
| `entity_list` | `GET /v1/facts` | List fact subjects, ranked by count. |
|
|
179
|
+
| `entity_get` | `GET /v1/facts?subject=…` | Fact lineage for a subject. |
|
|
180
|
+
| `entity_edges` | `GET /v1/facts?subject=…` | Predicate/object pairs for an entity. |
|
|
181
|
+
| `entity_link` | `POST /v1/experience` | Store a sentence the extractor will turn into a fact. |
|
|
165
182
|
|
|
166
183
|
### Admin & Observability
|
|
167
184
|
|
|
168
|
-
| Tool | Description |
|
|
169
|
-
|
|
170
|
-
| `health_check` |
|
|
171
|
-
| `get_usage` |
|
|
172
|
-
| `get_insights` |
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
185
|
+
| Tool | Maps to | Description |
|
|
186
|
+
|------|---------|-------------|
|
|
187
|
+
| `health_check` | `GET /v1/auth/whoami` | Verify the bearer + reach the deployment policy. |
|
|
188
|
+
| `get_usage` | `GET /v1/auth/whoami` + headers | Tier, rate limit, token expiry. |
|
|
189
|
+
| `get_insights` | (in-process) | Proactive insights derived from stored episodes. |
|
|
190
|
+
|
|
191
|
+
### Removed from 0.3.0
|
|
192
|
+
|
|
193
|
+
`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.
|
|
176
194
|
|
|
177
195
|
## Resources
|
|
178
196
|
|
|
@@ -204,7 +222,7 @@ Pre-built prompt templates:
|
|
|
204
222
|
|
|
205
223
|
| Environment Variable | Default | Description |
|
|
206
224
|
|---|---|---|
|
|
207
|
-
| `CORTEXDB_URL` | `https://api.cortexdb.ai` | CortexDB server URL |
|
|
225
|
+
| `CORTEXDB_URL` | `https://api-v1.cortexdb.ai` | CortexDB server URL |
|
|
208
226
|
| `CORTEXDB_API_KEY` | (none) | API key for authentication |
|
|
209
227
|
| `CORTEXDB_TIMEOUT` | `30.0` | HTTP request timeout (seconds) |
|
|
210
228
|
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# CortexDB MCP Server
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
> **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.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
# Install (the PyPI name is `cortexdb-mcp`)
|
|
11
|
+
pip install cortexdb-mcp
|
|
12
|
+
|
|
13
|
+
# Then run with zero config:
|
|
14
|
+
cortexdb-mcp
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
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).
|
|
18
|
+
|
|
19
|
+
To target a custom deployment or pre-existing identity, set any of:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
export CORTEXDB_URL="https://api-v1.cortexdb.ai" # base URL
|
|
23
|
+
export CORTEXDB_API_KEY="v4.public..." # PASETO bearer token
|
|
24
|
+
export CORTEXDB_ACTOR="user:alice" # ActorId, sent as X-Cortex-Actor
|
|
25
|
+
export CORTEXDB_SCOPE="org:acme/user:alice" # default scope path
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## IDE Setup
|
|
29
|
+
|
|
30
|
+
Most clients just need a single line — the auto-signup handles the rest.
|
|
31
|
+
|
|
32
|
+
### Claude Desktop
|
|
33
|
+
|
|
34
|
+
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"mcpServers": {
|
|
39
|
+
"cortexdb": {
|
|
40
|
+
"command": "cortexdb-mcp"
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
> **Windows note (audit POL-3):** if Claude Desktop / Cursor / Windsurf
|
|
47
|
+
> can't find `cortexdb-mcp` on PATH, give it the full path to the
|
|
48
|
+
> installed executable:
|
|
49
|
+
>
|
|
50
|
+
> ```json
|
|
51
|
+
> {
|
|
52
|
+
> "mcpServers": {
|
|
53
|
+
> "cortexdb": {
|
|
54
|
+
> "command": "C:\\Python313\\Scripts\\cortexdb-mcp.exe"
|
|
55
|
+
> }
|
|
56
|
+
> }
|
|
57
|
+
> }
|
|
58
|
+
> ```
|
|
59
|
+
>
|
|
60
|
+
> Locate it with `where cortexdb-mcp` in `cmd.exe` or
|
|
61
|
+
> `(Get-Command cortexdb-mcp).Source` in PowerShell.
|
|
62
|
+
>
|
|
63
|
+
> Some Windows terminals don't have UTF-8 enabled by default, which can
|
|
64
|
+
> garble emoji in `--help` output (they show as `?`). The server itself
|
|
65
|
+
> isn't affected — only the CLI banner. Run
|
|
66
|
+
> `chcp 65001` once per terminal session to fix.
|
|
67
|
+
|
|
68
|
+
### Claude Code (CLI)
|
|
69
|
+
|
|
70
|
+
Edit `~/.claude/mcp.json`:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"mcpServers": {
|
|
75
|
+
"cortexdb": {
|
|
76
|
+
"command": "cortexdb-mcp"
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Cursor
|
|
83
|
+
|
|
84
|
+
Edit `~/.cursor/mcp.json`:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"mcpServers": {
|
|
89
|
+
"cortexdb": {
|
|
90
|
+
"command": "cortexdb-mcp"
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Or in Cursor Settings > MCP Servers > Add Server.
|
|
97
|
+
|
|
98
|
+
### Windsurf
|
|
99
|
+
|
|
100
|
+
Edit `~/.codeium/windsurf/mcp_config.json`:
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"mcpServers": {
|
|
105
|
+
"cortexdb": {
|
|
106
|
+
"command": "cortexdb-mcp"
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### VS Code (GitHub Copilot)
|
|
113
|
+
|
|
114
|
+
Add to `.vscode/mcp.json` in your project or `~/.vscode/mcp.json` globally:
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"servers": {
|
|
119
|
+
"cortexdb": {
|
|
120
|
+
"command": "cortexdb-mcp"
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Windows tip
|
|
127
|
+
|
|
128
|
+
On Windows, MCP clients sometimes need the absolute path:
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"mcpServers": {
|
|
133
|
+
"cortexdb": {
|
|
134
|
+
"command": "C:\\Python310\\Scripts\\cortexdb-mcp.exe"
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Tools
|
|
141
|
+
|
|
142
|
+
### Memory Operations
|
|
143
|
+
|
|
144
|
+
| Tool | Maps to | Description |
|
|
145
|
+
|------|---------|-------------|
|
|
146
|
+
| `memory_store` | `POST /v1/experience` | Store a new memory. Source/tags/type become labels. |
|
|
147
|
+
| `memory_search` | `POST /v1/recall` | Search memories using natural language. |
|
|
148
|
+
| `memory_forget` | `POST /v1/forget` | Delete memories. With `query`, narrows by subject. |
|
|
149
|
+
| `get_context` | `POST /v1/recall` (holistic) | Deep context with facts + beliefs. |
|
|
150
|
+
| `advanced_search` | `POST /v1/recall` + temporal | Search with structured filters (time / source / type). |
|
|
151
|
+
|
|
152
|
+
### Event CRUD
|
|
153
|
+
|
|
154
|
+
| Tool | Maps to | Description |
|
|
155
|
+
|------|---------|-------------|
|
|
156
|
+
| `memory_list` | `GET /v1/events` | List events in scope, paginated. |
|
|
157
|
+
| `memory_get` | `GET /v1/events/{id}` | Fetch a single event (used for citations). |
|
|
158
|
+
| `memory_delete` | `POST /v1/forget` (memory_ids) | Delete one event by id. |
|
|
159
|
+
| `memory_bulk_delete` | `POST /v1/forget` or `/v1/erasures/preview` | Bulk delete with dry-run support. |
|
|
160
|
+
|
|
161
|
+
### Knowledge Graph (facts-backed in v1)
|
|
162
|
+
|
|
163
|
+
| Tool | Maps to | Description |
|
|
164
|
+
|------|---------|-------------|
|
|
165
|
+
| `entity_list` | `GET /v1/facts` | List fact subjects, ranked by count. |
|
|
166
|
+
| `entity_get` | `GET /v1/facts?subject=…` | Fact lineage for a subject. |
|
|
167
|
+
| `entity_edges` | `GET /v1/facts?subject=…` | Predicate/object pairs for an entity. |
|
|
168
|
+
| `entity_link` | `POST /v1/experience` | Store a sentence the extractor will turn into a fact. |
|
|
169
|
+
|
|
170
|
+
### Admin & Observability
|
|
171
|
+
|
|
172
|
+
| Tool | Maps to | Description |
|
|
173
|
+
|------|---------|-------------|
|
|
174
|
+
| `health_check` | `GET /v1/auth/whoami` | Verify the bearer + reach the deployment policy. |
|
|
175
|
+
| `get_usage` | `GET /v1/auth/whoami` + headers | Tier, rate limit, token expiry. |
|
|
176
|
+
| `get_insights` | (in-process) | Proactive insights derived from stored episodes. |
|
|
177
|
+
|
|
178
|
+
### Removed from 0.3.0
|
|
179
|
+
|
|
180
|
+
`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.
|
|
181
|
+
|
|
182
|
+
## Resources
|
|
183
|
+
|
|
184
|
+
Resources provide read-only data that AI tools can access:
|
|
185
|
+
|
|
186
|
+
| Resource URI | Description |
|
|
187
|
+
|---|---|
|
|
188
|
+
| `cortexdb://health` | Server health status |
|
|
189
|
+
| `cortexdb://metrics` | Request metrics (total, active, errors, rate-limited) |
|
|
190
|
+
| `cortexdb://usage` | Usage statistics and tier limits |
|
|
191
|
+
| `cortexdb://episodes` | Recent 50 episodes |
|
|
192
|
+
| `cortexdb://entities` | Top 100 knowledge graph entities |
|
|
193
|
+
| `cortexdb://insights` | Proactive insights |
|
|
194
|
+
| `cortexdb://ontology` | Entity and relationship type schema |
|
|
195
|
+
|
|
196
|
+
## Prompts
|
|
197
|
+
|
|
198
|
+
Pre-built prompt templates:
|
|
199
|
+
|
|
200
|
+
| Prompt | Description |
|
|
201
|
+
|---|---|
|
|
202
|
+
| `investigate_incident` | Investigate an incident using stored memories |
|
|
203
|
+
| `summarize_knowledge` | Summarize everything known about a topic |
|
|
204
|
+
| `deployment_review` | Pre-deployment safety review |
|
|
205
|
+
| `onboard_to_codebase` | Onboard to a codebase using stored knowledge |
|
|
206
|
+
| `weekly_digest` | Generate a weekly activity summary |
|
|
207
|
+
|
|
208
|
+
## Configuration
|
|
209
|
+
|
|
210
|
+
| Environment Variable | Default | Description |
|
|
211
|
+
|---|---|---|
|
|
212
|
+
| `CORTEXDB_URL` | `https://api-v1.cortexdb.ai` | CortexDB server URL |
|
|
213
|
+
| `CORTEXDB_API_KEY` | (none) | API key for authentication |
|
|
214
|
+
| `CORTEXDB_TIMEOUT` | `30.0` | HTTP request timeout (seconds) |
|
|
215
|
+
|
|
216
|
+
## Examples
|
|
217
|
+
|
|
218
|
+
### Store a memory from Cursor
|
|
219
|
+
|
|
220
|
+
Ask your AI assistant:
|
|
221
|
+
> "Remember that the payments service was migrated to Stripe v3 on March 15th"
|
|
222
|
+
|
|
223
|
+
The assistant will call `memory_store` with the content.
|
|
224
|
+
|
|
225
|
+
### Search memories
|
|
226
|
+
|
|
227
|
+
> "What do we know about the payments service?"
|
|
228
|
+
|
|
229
|
+
The assistant calls `memory_search` and gets relevant context from CortexDB.
|
|
230
|
+
|
|
231
|
+
### Explore the knowledge graph
|
|
232
|
+
|
|
233
|
+
> "Show me all entities related to the auth service"
|
|
234
|
+
|
|
235
|
+
The assistant calls `entity_get` or `entity_edges` to traverse relationships.
|
|
236
|
+
|
|
237
|
+
### Pre-deployment review
|
|
238
|
+
|
|
239
|
+
> "Run a deployment review for the user-service"
|
|
240
|
+
|
|
241
|
+
Uses the `deployment_review` prompt to check for recent incidents, dependencies, and risks.
|
|
242
|
+
|
|
243
|
+
## Architecture
|
|
244
|
+
|
|
245
|
+
```
|
|
246
|
+
┌─────────────┐ stdio/SSE ┌──────────────┐ HTTP ┌──────────┐
|
|
247
|
+
│ AI Client │ ◄──────────────► │ MCP Server │ ◄──────────► │ CortexDB │
|
|
248
|
+
│ (Cursor, │ MCP JSON-RPC │ (this pkg) │ REST API │ Server │
|
|
249
|
+
│ Claude, │ │ │ │ │
|
|
250
|
+
│ VS Code) │ └──────────────┘ └──────────┘
|
|
251
|
+
└─────────────┘
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
The MCP server is a thin translation layer:
|
|
255
|
+
1. Receives MCP tool calls from the AI client
|
|
256
|
+
2. Translates them to CortexDB REST API calls
|
|
257
|
+
3. Formats responses for the AI to consume
|
|
258
|
+
|
|
259
|
+
## License
|
|
260
|
+
|
|
261
|
+
MIT
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
"""CortexDB MCP Server -- expose CortexDB memory operations to AI agents via MCP."""
|
|
2
|
-
|
|
3
|
-
__version__ = "0.
|
|
1
|
+
"""CortexDB MCP Server -- expose CortexDB memory operations to AI agents via MCP."""
|
|
2
|
+
|
|
3
|
+
__version__ = "0.3.1"
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
"""Allow ``python -m cortexdb_mcp`` to launch the MCP server."""
|
|
2
|
-
|
|
3
|
-
from cortexdb_mcp.server import main
|
|
4
|
-
|
|
5
|
-
main()
|
|
1
|
+
"""Allow ``python -m cortexdb_mcp`` to launch the MCP server."""
|
|
2
|
+
|
|
3
|
+
from cortexdb_mcp.server import main
|
|
4
|
+
|
|
5
|
+
main()
|