cortexdb-mcp 0.2.0__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.
Files changed (13) hide show
  1. cortexdb_mcp-0.2.0/.gitignore +45 -0
  2. cortexdb_mcp-0.2.0/Dockerfile +12 -0
  3. cortexdb_mcp-0.2.0/PKG-INFO +276 -0
  4. cortexdb_mcp-0.2.0/README.md +263 -0
  5. cortexdb_mcp-0.2.0/cortexdb_mcp/__init__.py +3 -0
  6. cortexdb_mcp-0.2.0/cortexdb_mcp/api.py +132 -0
  7. cortexdb_mcp-0.2.0/cortexdb_mcp/config.py +40 -0
  8. cortexdb_mcp-0.2.0/cortexdb_mcp/insights.py +640 -0
  9. cortexdb_mcp-0.2.0/cortexdb_mcp/server.py +1085 -0
  10. cortexdb_mcp-0.2.0/pyproject.toml +21 -0
  11. cortexdb_mcp-0.2.0/tests/__init__.py +0 -0
  12. cortexdb_mcp-0.2.0/tests/test_insights.py +514 -0
  13. cortexdb_mcp-0.2.0/tests/test_server.py +223 -0
cortexdb_mcp-0.2.0/.gitignore ADDED
@@ -0,0 +1,45 @@
1
+ # Rust
2
+ /target
3
+ **/*.rs.bk
4
+
5
+ # Environment / secrets
6
+ .env
7
+ .env.local
8
+ .env*.local
9
+ *.pem
10
+ *.key
11
+
12
+ # SQLite database
13
+ website/data/
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
+
33
+ # Python
34
+ __pycache__/
35
+ *.pyc
36
+ .venv/
37
+ venv/
38
+
39
+ # Node
40
+ node_modules/
41
+ dist/
42
+ .next/
43
+
44
+ # Egg info
45
+ *.egg-info/
cortexdb_mcp-0.2.0/Dockerfile ADDED
@@ -0,0 +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=http://localhost:3141
11
+
12
+ CMD ["cortexdb-mcp"]
cortexdb_mcp-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,276 @@
1
+ Metadata-Version: 2.4
2
+ Name: cortexdb-mcp
3
+ Version: 0.2.0
4
+ Summary: MCP Server for CortexDB — expose memory operations to AI agents
5
+ License-Expression: MIT
6
+ Requires-Python: >=3.10
7
+ Requires-Dist: fastapi>=0.110
8
+ Requires-Dist: httpx>=0.27
9
+ Requires-Dist: mcp>=1.0
10
+ Requires-Dist: pydantic>=2.0
11
+ Requires-Dist: uvicorn>=0.29
12
+ Description-Content-Type: text/markdown
13
+
14
+ # CortexDB MCP Server
15
+
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
+
18
+ ## Quick Start
19
+
20
+ ```bash
21
+ # Install
22
+ pip install -e .
23
+
24
+ # Or with uvx (no install needed)
25
+ uvx --from . cortexdb-mcp
26
+ ```
27
+
28
+ Set your environment variables:
29
+
30
+ ```bash
31
+ export CORTEXDB_URL="https://api.cortexdb.ai" # or http://localhost:3141
32
+ export CORTEXDB_API_KEY="cx_live_your_key_here"
33
+ ```
34
+
35
+ Run:
36
+
37
+ ```bash
38
+ cortexdb-mcp
39
+ ```
40
+
41
+ ## IDE Setup
42
+
43
+ ### Claude Desktop
44
+
45
+ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
46
+
47
+ ```json
48
+ {
49
+ "mcpServers": {
50
+ "cortexdb": {
51
+ "command": "cortexdb-mcp",
52
+ "env": {
53
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
54
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
55
+ }
56
+ }
57
+ }
58
+ }
59
+ ```
60
+
61
+ ### Claude Code (CLI)
62
+
63
+ Edit `~/.claude/mcp.json`:
64
+
65
+ ```json
66
+ {
67
+ "mcpServers": {
68
+ "cortexdb": {
69
+ "command": "cortexdb-mcp",
70
+ "env": {
71
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
72
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
73
+ }
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ ### Cursor
80
+
81
+ Edit `~/.cursor/mcp.json`:
82
+
83
+ ```json
84
+ {
85
+ "mcpServers": {
86
+ "cortexdb": {
87
+ "command": "cortexdb-mcp",
88
+ "env": {
89
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
90
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
91
+ }
92
+ }
93
+ }
94
+ }
95
+ ```
96
+
97
+ Or in Cursor Settings > MCP Servers > Add Server.
98
+
99
+ ### Windsurf
100
+
101
+ Edit `~/.codeium/windsurf/mcp_config.json`:
102
+
103
+ ```json
104
+ {
105
+ "mcpServers": {
106
+ "cortexdb": {
107
+ "command": "cortexdb-mcp",
108
+ "env": {
109
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
110
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
111
+ }
112
+ }
113
+ }
114
+ }
115
+ ```
116
+
117
+ ### VS Code (GitHub Copilot)
118
+
119
+ Add to `.vscode/mcp.json` in your project or `~/.vscode/mcp.json` globally:
120
+
121
+ ```json
122
+ {
123
+ "servers": {
124
+ "cortexdb": {
125
+ "command": "cortexdb-mcp",
126
+ "env": {
127
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
128
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
129
+ }
130
+ }
131
+ }
132
+ }
133
+ ```
134
+
135
+ ### Docker
136
+
137
+ ```bash
138
+ docker build -t cortexdb-mcp .
139
+ docker run -e CORTEXDB_URL=https://api.cortexdb.ai -e CORTEXDB_API_KEY=cx_live_... cortexdb-mcp
140
+ ```
141
+
142
+ ## Tools
143
+
144
+ ### Memory Operations
145
+
146
+ | Tool | Description |
147
+ |------|-------------|
148
+ | `memory_store` | Store a new memory with optional source, type, tags, TTL |
149
+ | `memory_search` | Search memories using natural language (hybrid retrieval) |
150
+ | `memory_forget` | Delete memories with audit trail (GDPR-compliant) |
151
+ | `get_context` | Deep contextual retrieval combining search + graph |
152
+ | `advanced_search` | Search with structured filters (source, type, time range) |
153
+
154
+ ### Episode Management
155
+
156
+ | Tool | Description |
157
+ |------|-------------|
158
+ | `memory_list` | List episodes with pagination and type filter |
159
+ | `memory_get` | Get a specific episode by ID |
160
+ | `memory_update` | Update episode content or metadata |
161
+ | `memory_delete` | Delete a specific episode by ID |
162
+ | `memory_bulk_delete` | Bulk delete with query matching and dry-run support |
163
+
164
+ ### Knowledge Graph
165
+
166
+ | Tool | Description |
167
+ |------|-------------|
168
+ | `entity_list` | List entities (people, services, projects, concepts) |
169
+ | `entity_get` | Get entity details including relationships and recent episodes |
170
+ | `entity_edges` | Get all relationships for an entity |
171
+ | `entity_link` | Create a relationship between two entities |
172
+
173
+ ### Admin & Observability
174
+
175
+ | Tool | Description |
176
+ |------|-------------|
177
+ | `health_check` | Check CortexDB server health |
178
+ | `get_usage` | View usage stats and tier limits |
179
+ | `get_insights` | Generate proactive insights (incident spikes, gaps, risks) |
180
+ | `get_ontology` | View entity types and relationship types |
181
+ | `export_data` | Export memories as JSON |
182
+ | `import_data` | Import memories from JSON |
183
+
184
+ ## Resources
185
+
186
+ Resources provide read-only data that AI tools can access:
187
+
188
+ | Resource URI | Description |
189
+ |---|---|
190
+ | `cortexdb://health` | Server health status |
191
+ | `cortexdb://metrics` | Request metrics (total, active, errors, rate-limited) |
192
+ | `cortexdb://usage` | Usage statistics and tier limits |
193
+ | `cortexdb://episodes` | Recent 50 episodes |
194
+ | `cortexdb://entities` | Top 100 knowledge graph entities |
195
+ | `cortexdb://insights` | Proactive insights |
196
+ | `cortexdb://ontology` | Entity and relationship type schema |
197
+
198
+ ## Prompts
199
+
200
+ Pre-built prompt templates:
201
+
202
+ | Prompt | Description |
203
+ |---|---|
204
+ | `investigate_incident` | Investigate an incident using stored memories |
205
+ | `summarize_knowledge` | Summarize everything known about a topic |
206
+ | `deployment_review` | Pre-deployment safety review |
207
+ | `onboard_to_codebase` | Onboard to a codebase using stored knowledge |
208
+ | `weekly_digest` | Generate a weekly activity summary |
209
+
210
+ ## Configuration
211
+
212
+ | Environment Variable | Default | Description |
213
+ |---|---|---|
214
+ | `CORTEXDB_URL` | `http://localhost:3141` | CortexDB server URL |
215
+ | `CORTEXDB_API_KEY` | (none) | API key for authentication |
216
+ | `CORTEXDB_TIMEOUT` | `30.0` | HTTP request timeout (seconds) |
217
+
218
+ ## Examples
219
+
220
+ ### Store a memory from Cursor
221
+
222
+ Ask your AI assistant:
223
+ > "Remember that the payments service was migrated to Stripe v3 on March 15th"
224
+
225
+ The assistant will call `memory_store` with the content.
226
+
227
+ ### Search memories
228
+
229
+ > "What do we know about the payments service?"
230
+
231
+ The assistant calls `memory_search` and gets relevant context from CortexDB.
232
+
233
+ ### Explore the knowledge graph
234
+
235
+ > "Show me all entities related to the auth service"
236
+
237
+ The assistant calls `entity_get` or `entity_edges` to traverse relationships.
238
+
239
+ ### Pre-deployment review
240
+
241
+ > "Run a deployment review for the user-service"
242
+
243
+ Uses the `deployment_review` prompt to check for recent incidents, dependencies, and risks.
244
+
245
+ ## Development
246
+
247
+ ```bash
248
+ # Install in dev mode
249
+ pip install -e ".[dev]"
250
+
251
+ # Run tests
252
+ pytest
253
+
254
+ # Run the server locally
255
+ CORTEXDB_URL=http://localhost:3141 CORTEXDB_API_KEY=test cortexdb-mcp
256
+ ```
257
+
258
+ ## Architecture
259
+
260
+ ```
261
+ ┌─────────────┐ stdio/SSE ┌──────────────┐ HTTP ┌──────────┐
262
+ │ AI Client │ ◄──────────────► │ MCP Server │ ◄──────────► │ CortexDB │
263
+ │ (Cursor, │ MCP JSON-RPC │ (this pkg) │ REST API │ Server │
264
+ │ Claude, │ │ │ │ │
265
+ │ VS Code) │ └──────────────┘ └──────────┘
266
+ └─────────────┘
267
+ ```
268
+
269
+ The MCP server is a thin translation layer:
270
+ 1. Receives MCP tool calls from the AI client
271
+ 2. Translates them to CortexDB REST API calls
272
+ 3. Formats responses for the AI to consume
273
+
274
+ ## License
275
+
276
+ MIT
cortexdb_mcp-0.2.0/README.md ADDED
@@ -0,0 +1,263 @@
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
+ ## Quick Start
6
+
7
+ ```bash
8
+ # Install
9
+ pip install -e .
10
+
11
+ # Or with uvx (no install needed)
12
+ uvx --from . cortexdb-mcp
13
+ ```
14
+
15
+ Set your environment variables:
16
+
17
+ ```bash
18
+ export CORTEXDB_URL="https://api.cortexdb.ai" # or http://localhost:3141
19
+ export CORTEXDB_API_KEY="cx_live_your_key_here"
20
+ ```
21
+
22
+ Run:
23
+
24
+ ```bash
25
+ cortexdb-mcp
26
+ ```
27
+
28
+ ## IDE Setup
29
+
30
+ ### Claude Desktop
31
+
32
+ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
33
+
34
+ ```json
35
+ {
36
+ "mcpServers": {
37
+ "cortexdb": {
38
+ "command": "cortexdb-mcp",
39
+ "env": {
40
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
41
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
42
+ }
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ### Claude Code (CLI)
49
+
50
+ Edit `~/.claude/mcp.json`:
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "cortexdb": {
56
+ "command": "cortexdb-mcp",
57
+ "env": {
58
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
59
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
60
+ }
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ ### Cursor
67
+
68
+ Edit `~/.cursor/mcp.json`:
69
+
70
+ ```json
71
+ {
72
+ "mcpServers": {
73
+ "cortexdb": {
74
+ "command": "cortexdb-mcp",
75
+ "env": {
76
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
77
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
78
+ }
79
+ }
80
+ }
81
+ }
82
+ ```
83
+
84
+ Or in Cursor Settings > MCP Servers > Add Server.
85
+
86
+ ### Windsurf
87
+
88
+ Edit `~/.codeium/windsurf/mcp_config.json`:
89
+
90
+ ```json
91
+ {
92
+ "mcpServers": {
93
+ "cortexdb": {
94
+ "command": "cortexdb-mcp",
95
+ "env": {
96
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
97
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
98
+ }
99
+ }
100
+ }
101
+ }
102
+ ```
103
+
104
+ ### VS Code (GitHub Copilot)
105
+
106
+ Add to `.vscode/mcp.json` in your project or `~/.vscode/mcp.json` globally:
107
+
108
+ ```json
109
+ {
110
+ "servers": {
111
+ "cortexdb": {
112
+ "command": "cortexdb-mcp",
113
+ "env": {
114
+ "CORTEXDB_URL": "https://api.cortexdb.ai",
115
+ "CORTEXDB_API_KEY": "cx_live_your_key_here"
116
+ }
117
+ }
118
+ }
119
+ }
120
+ ```
121
+
122
+ ### Docker
123
+
124
+ ```bash
125
+ docker build -t cortexdb-mcp .
126
+ docker run -e CORTEXDB_URL=https://api.cortexdb.ai -e CORTEXDB_API_KEY=cx_live_... cortexdb-mcp
127
+ ```
128
+
129
+ ## Tools
130
+
131
+ ### Memory Operations
132
+
133
+ | Tool | Description |
134
+ |------|-------------|
135
+ | `memory_store` | Store a new memory with optional source, type, tags, TTL |
136
+ | `memory_search` | Search memories using natural language (hybrid retrieval) |
137
+ | `memory_forget` | Delete memories with audit trail (GDPR-compliant) |
138
+ | `get_context` | Deep contextual retrieval combining search + graph |
139
+ | `advanced_search` | Search with structured filters (source, type, time range) |
140
+
141
+ ### Episode Management
142
+
143
+ | Tool | Description |
144
+ |------|-------------|
145
+ | `memory_list` | List episodes with pagination and type filter |
146
+ | `memory_get` | Get a specific episode by ID |
147
+ | `memory_update` | Update episode content or metadata |
148
+ | `memory_delete` | Delete a specific episode by ID |
149
+ | `memory_bulk_delete` | Bulk delete with query matching and dry-run support |
150
+
151
+ ### Knowledge Graph
152
+
153
+ | Tool | Description |
154
+ |------|-------------|
155
+ | `entity_list` | List entities (people, services, projects, concepts) |
156
+ | `entity_get` | Get entity details including relationships and recent episodes |
157
+ | `entity_edges` | Get all relationships for an entity |
158
+ | `entity_link` | Create a relationship between two entities |
159
+
160
+ ### Admin & Observability
161
+
162
+ | Tool | Description |
163
+ |------|-------------|
164
+ | `health_check` | Check CortexDB server health |
165
+ | `get_usage` | View usage stats and tier limits |
166
+ | `get_insights` | Generate proactive insights (incident spikes, gaps, risks) |
167
+ | `get_ontology` | View entity types and relationship types |
168
+ | `export_data` | Export memories as JSON |
169
+ | `import_data` | Import memories from JSON |
170
+
171
+ ## Resources
172
+
173
+ Resources provide read-only data that AI tools can access:
174
+
175
+ | Resource URI | Description |
176
+ |---|---|
177
+ | `cortexdb://health` | Server health status |
178
+ | `cortexdb://metrics` | Request metrics (total, active, errors, rate-limited) |
179
+ | `cortexdb://usage` | Usage statistics and tier limits |
180
+ | `cortexdb://episodes` | Recent 50 episodes |
181
+ | `cortexdb://entities` | Top 100 knowledge graph entities |
182
+ | `cortexdb://insights` | Proactive insights |
183
+ | `cortexdb://ontology` | Entity and relationship type schema |
184
+
185
+ ## Prompts
186
+
187
+ Pre-built prompt templates:
188
+
189
+ | Prompt | Description |
190
+ |---|---|
191
+ | `investigate_incident` | Investigate an incident using stored memories |
192
+ | `summarize_knowledge` | Summarize everything known about a topic |
193
+ | `deployment_review` | Pre-deployment safety review |
194
+ | `onboard_to_codebase` | Onboard to a codebase using stored knowledge |
195
+ | `weekly_digest` | Generate a weekly activity summary |
196
+
197
+ ## Configuration
198
+
199
+ | Environment Variable | Default | Description |
200
+ |---|---|---|
201
+ | `CORTEXDB_URL` | `http://localhost:3141` | CortexDB server URL |
202
+ | `CORTEXDB_API_KEY` | (none) | API key for authentication |
203
+ | `CORTEXDB_TIMEOUT` | `30.0` | HTTP request timeout (seconds) |
204
+
205
+ ## Examples
206
+
207
+ ### Store a memory from Cursor
208
+
209
+ Ask your AI assistant:
210
+ > "Remember that the payments service was migrated to Stripe v3 on March 15th"
211
+
212
+ The assistant will call `memory_store` with the content.
213
+
214
+ ### Search memories
215
+
216
+ > "What do we know about the payments service?"
217
+
218
+ The assistant calls `memory_search` and gets relevant context from CortexDB.
219
+
220
+ ### Explore the knowledge graph
221
+
222
+ > "Show me all entities related to the auth service"
223
+
224
+ The assistant calls `entity_get` or `entity_edges` to traverse relationships.
225
+
226
+ ### Pre-deployment review
227
+
228
+ > "Run a deployment review for the user-service"
229
+
230
+ Uses the `deployment_review` prompt to check for recent incidents, dependencies, and risks.
231
+
232
+ ## Development
233
+
234
+ ```bash
235
+ # Install in dev mode
236
+ pip install -e ".[dev]"
237
+
238
+ # Run tests
239
+ pytest
240
+
241
+ # Run the server locally
242
+ CORTEXDB_URL=http://localhost:3141 CORTEXDB_API_KEY=test cortexdb-mcp
243
+ ```
244
+
245
+ ## Architecture
246
+
247
+ ```
248
+ ┌─────────────┐ stdio/SSE ┌──────────────┐ HTTP ┌──────────┐
249
+ │ AI Client │ ◄──────────────► │ MCP Server │ ◄──────────► │ CortexDB │
250
+ │ (Cursor, │ MCP JSON-RPC │ (this pkg) │ REST API │ Server │
251
+ │ Claude, │ │ │ │ │
252
+ │ VS Code) │ └──────────────┘ └──────────┘
253
+ └─────────────┘
254
+ ```
255
+
256
+ The MCP server is a thin translation layer:
257
+ 1. Receives MCP tool calls from the AI client
258
+ 2. Translates them to CortexDB REST API calls
259
+ 3. Formats responses for the AI to consume
260
+
261
+ ## License
262
+
263
+ MIT
cortexdb_mcp-0.2.0/cortexdb_mcp/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """CortexDB MCP Server -- expose CortexDB memory operations to AI agents via MCP."""
2
+
3
+ __version__ = "0.2.0"