cortexdb-mcp 0.7.4__tar.gz → 0.8.0__tar.gz

{cortexdb_mcp-0.7.4 → cortexdb_mcp-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdb-mcp
-Version: 0.7.4
+Version: 0.8.0
 Summary: MCP Server for CortexDB — expose memory operations to AI agents
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -41,7 +41,7 @@ cortexdb-mcp --tool-profile code
 This materially reduces tool-schema context while retaining natural-language
 retrieval, typed traversal, prefix symbol discovery, and directory inventory.
 
-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).
+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); the cached `expires_at` is checked at load, and a token the server rejects with 401 is discarded and re-minted automatically, so no hand-deletion of `state.json` is needed. Signup runs against any configured `CORTEXDB_URL`, self-hosted included; a deployment with no minter answers 503 and the server carries on unauthenticated.
 
 To target a custom deployment or pre-existing identity, set any of:
 

{cortexdb_mcp-0.7.4 → cortexdb_mcp-0.8.0}/README.md

@@ -1,284 +1,284 @@
-# 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
-```
-
-For a coding agent that only needs repository intelligence, select the compact
-read-only surface (four tools: explore, impact, inventory, graph):
-
-```bash
-cortexdb-mcp --tool-profile code
-```
-
-This materially reduces tool-schema context while retaining natural-language
-retrieval, typed traversal, prefix symbol discovery, and directory inventory.
-
-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"
-    }
-  }
-}
-```
-
-> **Windows note (audit POL-3):** if Claude Desktop / Cursor / Windsurf
-> can't find `cortexdb-mcp` on PATH, give it the full path to the
-> installed executable:
->
-> ```json
-> {
->   "mcpServers": {
->     "cortexdb": {
->       "command": "C:\\Python313\\Scripts\\cortexdb-mcp.exe"
->     }
->   }
-> }
-> ```
->
-> Locate it with `where cortexdb-mcp` in `cmd.exe` or
-> `(Get-Command cortexdb-mcp).Source` in PowerShell.
->
-> Some Windows terminals don't have UTF-8 enabled by default, which can
-> garble emoji in `--help` output (they show as `?`). The server itself
-> isn't affected — only the CLI banner. Run
-> `chcp 65001` once per terminal session to fix.
-
-### 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_status` | `GET /v1/experience/status` | Did a store land? Check by event ID or idempotency key after a timeout — "not found"/"failed" both mean re-storing is safe. |
-| `memory_search` | `POST /v1/recall` | Search memories using natural language. |
-| `memory_forget` | `POST /v1/forget` | Delete memories. With `query`, narrows by subject. Accepts `from_preview_id` from `forget_preview`. |
-| `forget_preview` | `POST /v1/forget/preview` | Non-destructive dry run of a forget: per-layer estimated deletion counts + a `preview_id` for the safe two-phase flow. |
-| `get_context` | `POST /v1/recall` (configured view; holistic by default) | By default, deep context across the requested scope, authorized ancestors, and authorized descendants—never siblings. |
-| `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/forget/preview` | Bulk delete with selector-accurate 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. |
-| `belief_declare` | `POST /v1/beliefs` | Declare a belief directly, with optional evidence refs (`evt_...` / `fact_...`). |
-
-### Bi-temporal Conflicts & Claim History
-
-| Tool | Maps to | Description |
-|------|---------|-------------|
-| `list_conflicts` | `GET /v1/conflicts` | Queue of contradicting values detected for the same claim. |
-| `resolve_conflict` | `POST /v1/conflicts/{id}/resolve` | Resolve: `pick` / `split` / `new_information` / `dismiss`. |
-| `claim_history` | `GET /v1/claims/history` | Full bi-temporal change-log of one claim (+ its conflicts). |
-
-Validity boundaries carry a basis: `stated` boundaries render as "since/until \<date\>"; `observed` boundaries are knowledge bounds and render as "by \<date\>" — never "on \<date\>".
-
-### 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://episodes` | Recent 50 events in the default scope |
-| `cortexdb://insights` | Proactive insights |
-
-## 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-v1.cortexdb.ai` | CortexDB server URL |
-| `CORTEXDB_API_KEY` | (none) | API key for authentication |
-| `CORTEXDB_ACTOR` | (from signup state) | Actor for `X-Cortex-Actor`; must match the token subject |
-| `CORTEXDB_SCOPE` | (from signup state) | Default scope for tool calls |
-| `CORTEXDB_VIEW` | `holistic` | Recall reach: `holistic` = self + authorized ancestors + authorized descendants (no siblings); `descend` = self + authorized descendants; `granular` = exact scope |
-| `CORTEXDB_TENANT_ID` | (none) | Legacy v0 tenant identifier |
-| `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
+# 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
+```
+
+For a coding agent that only needs repository intelligence, select the compact
+read-only surface (four tools: explore, impact, inventory, graph):
+
+```bash
+cortexdb-mcp --tool-profile code
+```
+
+This materially reduces tool-schema context while retaining natural-language
+retrieval, typed traversal, prefix symbol discovery, and directory inventory.
+
+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); the cached `expires_at` is checked at load, and a token the server rejects with 401 is discarded and re-minted automatically, so no hand-deletion of `state.json` is needed. Signup runs against any configured `CORTEXDB_URL`, self-hosted included; a deployment with no minter answers 503 and the server carries on unauthenticated.
+
+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"
+    }
+  }
+}
+```
+
+> **Windows note (audit POL-3):** if Claude Desktop / Cursor / Windsurf
+> can't find `cortexdb-mcp` on PATH, give it the full path to the
+> installed executable:
+>
+> ```json
+> {
+>   "mcpServers": {
+>     "cortexdb": {
+>       "command": "C:\\Python313\\Scripts\\cortexdb-mcp.exe"
+>     }
+>   }
+> }
+> ```
+>
+> Locate it with `where cortexdb-mcp` in `cmd.exe` or
+> `(Get-Command cortexdb-mcp).Source` in PowerShell.
+>
+> Some Windows terminals don't have UTF-8 enabled by default, which can
+> garble emoji in `--help` output (they show as `?`). The server itself
+> isn't affected — only the CLI banner. Run
+> `chcp 65001` once per terminal session to fix.
+
+### 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_status` | `GET /v1/experience/status` | Did a store land? Check by event ID or idempotency key after a timeout — "not found"/"failed" both mean re-storing is safe. |
+| `memory_search` | `POST /v1/recall` | Search memories using natural language. |
+| `memory_forget` | `POST /v1/forget` | Delete memories. With `query`, narrows by subject. Accepts `from_preview_id` from `forget_preview`. |
+| `forget_preview` | `POST /v1/forget/preview` | Non-destructive dry run of a forget: per-layer estimated deletion counts + a `preview_id` for the safe two-phase flow. |
+| `get_context` | `POST /v1/recall` (configured view; holistic by default) | By default, deep context across the requested scope, authorized ancestors, and authorized descendants—never siblings. |
+| `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/forget/preview` | Bulk delete with selector-accurate 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. |
+| `belief_declare` | `POST /v1/beliefs` | Declare a belief directly, with optional evidence refs (`evt_...` / `fact_...`). |
+
+### Bi-temporal Conflicts & Claim History
+
+| Tool | Maps to | Description |
+|------|---------|-------------|
+| `list_conflicts` | `GET /v1/conflicts` | Queue of contradicting values detected for the same claim. |
+| `resolve_conflict` | `POST /v1/conflicts/{id}/resolve` | Resolve: `pick` / `split` / `new_information` / `dismiss`. |
+| `claim_history` | `GET /v1/claims/history` | Full bi-temporal change-log of one claim (+ its conflicts). |
+
+Validity boundaries carry a basis: `stated` boundaries render as "since/until \<date\>"; `observed` boundaries are knowledge bounds and render as "by \<date\>" — never "on \<date\>".
+
+### 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://episodes` | Recent 50 events in the default scope |
+| `cortexdb://insights` | Proactive insights |
+
+## 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-v1.cortexdb.ai` | CortexDB server URL |
+| `CORTEXDB_API_KEY` | (none) | API key for authentication |
+| `CORTEXDB_ACTOR` | (from signup state) | Actor for `X-Cortex-Actor`; must match the token subject |
+| `CORTEXDB_SCOPE` | (from signup state) | Default scope for tool calls |
+| `CORTEXDB_VIEW` | `holistic` | Recall reach: `holistic` = self + authorized ancestors + authorized descendants (no siblings); `descend` = self + authorized descendants; `granular` = exact scope |
+| `CORTEXDB_TENANT_ID` | (none) | Legacy v0 tenant identifier |
+| `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

{cortexdb_mcp-0.7.4 → cortexdb_mcp-0.8.0}/cortexdb_mcp/__main__.py

@@ -1,5 +1,5 @@
-"""Allow ``python -m cortexdb_mcp`` to launch the MCP server."""
-
-from cortexdb_mcp.server import main
-
-main()
+"""Allow ``python -m cortexdb_mcp`` to launch the MCP server."""
+
+from cortexdb_mcp.server import main
+
+main()