getbased-mcp 0.2.6__tar.gz → 0.2.7__tar.gz

{getbased_mcp-0.2.6 → getbased_mcp-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getbased-mcp
-Version: 0.2.6
+Version: 0.2.7
 Summary: MCP server for querying blood work data and knowledge base from getbased
 License-Expression: AGPL-3.0-or-later
 Requires-Python: >=3.10
@@ -8,7 +8,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: httpx>=0.27
-Requires-Dist: cryptography>=42.0
+Requires-Dist: cryptography>=48.0.1
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23; extra == "test"
@@ -17,9 +17,9 @@ Dynamic: license-file
 
 # getbased MCP Server
 
-An [MCP](https://modelcontextprotocol.io) server that exposes blood work data and an optional RAG knowledge base from [getbased](https://getbased.health) as tools. Works with any MCP-compatible client (Claude Code, Hermes, Claude Desktop, etc.).
+An [MCP](https://modelcontextprotocol.io) server that exposes getbased health context and an optional local knowledge base as tools. Works with MCP-compatible clients such as Claude Code, Claude Desktop, Cursor, Cline, Codex CLI, Hermes, and OpenClaw.
 
-> **Installing for the first time?** The [getbased-agent-stack](https://github.com/elkimek/getbased-agents/tree/main/packages/stack) meta-package bundles this MCP with the RAG engine it talks to, plus example configs for Claude Code and Hermes. One command and you're up.
+> **Installing for the first time?** Use the private setup command from **getbased → Settings → Agent Access**. It installs or updates [getbased-agent-stack](https://github.com/elkimek/getbased-agents/tree/main/packages/stack), stores the token/key locally, and configures the selected client.
 
 ## How it works
 
@@ -31,21 +31,21 @@ getbased (browser)
   ├── encrypts the rendered agent context with that context key
   └── pushes ciphertext to sync gateway on every save
 
-Sync Gateway (sync.getbased.health/api/context)
+Context gateway (sync.getbased.health/api/context)
   └── stores encrypted context behind token auth; it cannot read the plaintext
 
-RAG Server (localhost, optional)
+Local knowledge server (localhost, optional)
   ├── Vector database with embedded chunks
   ├── Embedding model for semantic search
   └── Your curated health knowledge base
 
 This MCP Server (on your machine)
-  ├── fetches blood work context from sync gateway
-  ├── queries RAG server for knowledge base searches (optional)
+  ├── fetches health context from the context gateway
+  ├── queries the local knowledge server for knowledge-base searches (optional)
   └── exposes everything as tools to any MCP client
 ```
 
-Your mnemonic never leaves your browser. The sync gateway receives only an end-to-end encrypted agent-context envelope; this MCP decrypts it locally with `GETBASED_AGENT_CONTEXT_KEY` and then exposes the same lab context text the getbased AI chat uses — not raw data. `GETBASED_TOKEN` is only the relay bearer token.
+Your mnemonic never leaves your browser. The gateway receives only an encrypted agent-context envelope; this MCP decrypts it locally with `GETBASED_AGENT_CONTEXT_KEY` and exposes the same summary text the getbased AI chat uses. `GETBASED_TOKEN` is only the relay bearer token.
 
 ## Tools
 
@@ -54,7 +54,7 @@ Your mnemonic never leaves your browser. The sync gateway receives only an end-t
 | `getbased_lab_context` | Full lab summary with biomarkers, context cards, supplements, goals. Pass `profile` to target a specific profile. |
 | `getbased_section` | Get a specific section (e.g. hormones, lipids) or list all available sections |
 | `getbased_list_profiles` | List available profiles |
-| `knowledge_search` | Semantic search across the active library on your knowledge base (requires RAG server). Returns relevant passages with source attribution. |
+| `knowledge_search` | Semantic search across the active library on your knowledge base (requires the local knowledge server). Returns relevant passages with source attribution. |
 | `knowledge_list_libraries` | List all knowledge base libraries and show which is active |
 | `knowledge_activate_library` | Switch the active library — subsequent searches target the new one until switched again |
 | `knowledge_stats` | Per-source chunk counts for the active library — useful for diagnosing missing results |
@@ -91,7 +91,7 @@ knowledge_search(query="blue light DHA mitochondrial damage")
 knowledge_search(query="MTHFR methylation folate", n_results=5)
 ```
 
-**Note:** This tool requires the RAG server to be running. Without it, all blood work tools still work — the MCP degrades gracefully.
+**Note:** This tool requires the local knowledge server to be running. If it is not running, knowledge search will fail, but the lab-context tools still work.
 
 ### Multi-library (v0.2+)
 
@@ -119,24 +119,34 @@ The gateway stores context per profile ID. To work with multiple profiles:
 
 ## Setup
 
-### 1. Enable Agent Access in getbased
+### Recommended: copy the private setup command
 
-Go to **Settings > Data > Agent Access** and toggle it on. Copy both values:
+In getbased, open **Settings → Agent Access**, choose your target client, and copy the setup command. It looks like this:
+
+```bash
+curl -fsSL https://getbased.health/install.sh | bash -s -- connect <target> --setup 'gbsetup_v1_...'
+```
+
+The setup payload is private. Paste it only into a terminal you control.
+
+### Manual setup
+
+If you are not using `getbased-stack connect`, open **Settings → Agent Access** and copy both values:
 
 - **Read-only token** → `GETBASED_TOKEN` for relay authorization
 - **Context encryption key** → `GETBASED_AGENT_CONTEXT_KEY` for local decryption
 
-### 2. Set up a RAG server (optional — for knowledge_search)
+### Set up a local knowledge server (optional, for `knowledge_search`)
 
-The knowledge base runs as a separate service. You need:
+The knowledge base runs as a separate service. The easiest path is `getbased-agent-stack[full]`, which installs `getbased-rag` and the browser dashboard. If you are wiring your own server, you need:
 
 - A vector database (e.g. [Qdrant](https://qdrant.tech/), [ChromaDB](https://www.trychroma.com/)) loaded with your document chunks and embeddings
 - A FastAPI (or similar) server that accepts `POST /query` with `{version: 1, query: "...", top_k: N}` and returns `{chunks: [{text: "...", source: "..."}]}`
 - An embedding model (e.g. [BGE-M3](https://huggingface.co/BAAI/bge-m3)) for semantic search
 
-The RAG server handles embedding, similarity search, and filtering. This MCP just sends HTTP queries to it — no models loaded here.
+The local knowledge server handles embedding, similarity search, and filtering. This MCP just sends HTTP queries to it; no models are loaded inside the MCP process.
 
-**RAG server contract:**
+**Knowledge server contract:**
 
 | Field | Required | Description |
 |---|---|---|
@@ -145,7 +155,7 @@ The RAG server handles embedding, similarity search, and filtering. This MCP jus
 | `GET /health` | Optional | Returns `{"status": "ok", "rag_ready": bool, "chunks": int}` |
 | Response | Yes | `{"chunks": [{"text": "...", "source": "..."}]}` |
 
-### 3. Configure your MCP client
+### Configure your MCP client manually
 
 #### Claude Code / Claude Desktop
 
@@ -174,7 +184,7 @@ hermes mcp add getbased \
   --args /path/to/getbased_mcp.py
 ```
 
-Then set `GETBASED_TOKEN` and `GETBASED_AGENT_CONTEXT_KEY` in `~/.hermes/.env` or in the MCP server's `env` config in `config.yaml`:
+Then set `GETBASED_TOKEN` and `GETBASED_AGENT_CONTEXT_KEY` in the MCP server's `env` config in `config.yaml`:
 
 ```yaml
 mcp_servers:
@@ -199,30 +209,30 @@ Ask about your labs in any connected conversation:
 
 | Variable | Required | Description |
 |---|---|---|
-| `GETBASED_TOKEN` | Yes | Read-only bearer token from getbased Settings > Data > Agent Access; authorizes fetches from the context gateway |
-| `GETBASED_AGENT_CONTEXT_KEY` | Yes for encrypted Agent Access payloads | Context encryption key from getbased Settings > Data > Agent Access; decrypts the relay payload locally in this MCP |
+| `GETBASED_TOKEN` | Yes | Read-only bearer token from getbased Settings → Agent Access; authorizes fetches from the context gateway |
+| `GETBASED_AGENT_CONTEXT_KEY` | Yes for encrypted Agent Access payloads | Context encryption key from getbased Settings → Agent Access; decrypts the relay payload locally in this MCP |
 | `GETBASED_GATEWAY` | No | Context gateway URL (default: `https://sync.getbased.health`) |
-| `LENS_URL` | No | RAG server URL (default: `http://localhost:8322`). Overrides `LENS_PORT` |
-| `LENS_PORT` | No | RAG server port, only used to build default `LENS_URL` (default: `8322`) |
-| `LENS_API_KEY_FILE` | No | Path to RAG API key file. Default: `$XDG_DATA_HOME/getbased/lens/api_key` (getbased-rag's canonical location). If that file doesn't exist but the legacy `~/.hermes/rag/lens_api_key` does, the legacy path is used instead — upgrades from standalone `getbased-mcp` ≤ 0.1.0 keep working without config changes. |
+| `LENS_URL` | No | Local knowledge server URL (default: `http://localhost:8322`). Overrides `LENS_PORT` |
+| `LENS_PORT` | No | Local knowledge server port, only used to build default `LENS_URL` (default: `8322`) |
+| `LENS_API_KEY_FILE` | No | Path to the knowledge server API key file. Default: `$XDG_DATA_HOME/getbased/lens/api_key` (getbased-rag's canonical location). If that file doesn't exist but the legacy `~/.hermes/rag/lens_api_key` does, the legacy path is used instead; upgrades from standalone `getbased-mcp` ≤ 0.1.0 keep working without config changes. |
 | `LENS_MCP_ACTIVITY_LOG` | No | JSONL path where tool-call activity is appended. Default: `$XDG_STATE_HOME/getbased/mcp/activity.jsonl`. Each record: `{ts, tool, duration_ms, ok, error?}` — arguments are never logged (queries may contain sensitive health info). Set to `off` / `false` / `0` to disable. The [getbased-dashboard](https://github.com/elkimek/getbased-agents/tree/main/packages/dashboard) Activity tab tails this file. |
 
 ## Custom Knowledge Source (getbased app)
 
-The same RAG server that powers `knowledge_search` for your AI client can also back the in-app AI chat. To connect them:
+The same local knowledge server that powers `knowledge_search` for your AI client can also back the in-app AI chat. To connect them:
 
 1. Run `getbased_lens_config` — it returns the endpoint URL, API key, and recommended `top_k`
-2. In getbased, go to **Settings → AI → Custom Knowledge Source**
+2. In getbased, open **Knowledge Base** and choose **External server**
 3. Paste the endpoint URL, API key, and set `top_k` to 5
 4. Enable it — the chat-header Lens badge will light up green when active
 
-Every chat question and focus card will now be enriched with RAG-retrieved passages from your knowledge base.
+Every chat question and Current Focus refresh can now include passages from your knowledge base.
 
 ## Troubleshooting
 
 ### `knowledge_search` returns "Lens server not reachable"
 
-The RAG server isn't running. Start it and verify with:
+The local knowledge server is not running. Start it and verify with:
 
 ```bash
 curl http://localhost:8322/health
@@ -230,7 +240,7 @@ curl http://localhost:8322/health
 
 ### `knowledge_search` returns "Lens API key not found"
 
-getbased-rag generates its API key on first start and writes it to `$XDG_DATA_HOME/getbased/lens/api_key` (e.g. `~/.local/share/getbased/lens/api_key` on Linux). If you're upgrading from the standalone `getbased-mcp` ≤ 0.1.0 and your key is at `~/.hermes/rag/lens_api_key`, that legacy path is still auto-detected — no config change needed. If the file is missing entirely, restart the RAG server and it will create a new one.
+getbased-rag generates its API key on first start and writes it to `$XDG_DATA_HOME/getbased/lens/api_key` (e.g. `~/.local/share/getbased/lens/api_key` on Linux). If you're upgrading from the standalone `getbased-mcp` ≤ 0.1.0 and your key is at `~/.hermes/rag/lens_api_key`, that legacy path is still auto-detected; no config change needed. If the file is missing entirely, restart the knowledge server and it will create a new one.
 
 ### `knowledge_list_libraries` / `knowledge_stats` return "this lens server doesn't expose library management"
 
@@ -238,7 +248,7 @@ The lens server you're pointed at is older than `getbased-rag` 0.1.0 and doesn't
 
 ### Blood work tools work but knowledge_search doesn't
 
-That's expected — they're independent. Blood work tools talk to the sync gateway; knowledge_search talks to the RAG server. The MCP degrades gracefully: if the RAG server is down, all blood work tools continue to work normally.
+That's expected. Blood work tools talk to the context gateway; `knowledge_search` talks to the local knowledge server. If the knowledge server is down, knowledge search will fail, but the lab-context tools continue to work normally.
 
 ## Security
 
@@ -250,7 +260,7 @@ That's expected — they're independent. Blood work tools talk to the sync gatew
 
 ## Related projects
 
-- **[getbased](https://github.com/elkimek/get-based)** — the health dashboard. This MCP reads the same lab context the in-app AI chat uses, and queries the same Knowledge Source endpoint configured in Settings → AI → Custom Knowledge Source. The [endpoint contract](https://github.com/elkimek/get-based/blob/main/dev-docs/lens-endpoint-contract.md) is shared — one server backs both the app and this MCP.
+- **[getbased](https://github.com/elkimek/get-based)** — the health dashboard. This MCP reads the same context the in-app AI chat uses, and can query the same external Knowledge Base server configured in the app. The endpoint contract is shared: one server can back both the app and this MCP.
 
 ## License
 

{getbased_mcp-0.2.6 → getbased_mcp-0.2.7}/README.md

@@ -1,8 +1,8 @@
 # getbased MCP Server
 
-An [MCP](https://modelcontextprotocol.io) server that exposes blood work data and an optional RAG knowledge base from [getbased](https://getbased.health) as tools. Works with any MCP-compatible client (Claude Code, Hermes, Claude Desktop, etc.).
+An [MCP](https://modelcontextprotocol.io) server that exposes getbased health context and an optional local knowledge base as tools. Works with MCP-compatible clients such as Claude Code, Claude Desktop, Cursor, Cline, Codex CLI, Hermes, and OpenClaw.
 
-> **Installing for the first time?** The [getbased-agent-stack](https://github.com/elkimek/getbased-agents/tree/main/packages/stack) meta-package bundles this MCP with the RAG engine it talks to, plus example configs for Claude Code and Hermes. One command and you're up.
+> **Installing for the first time?** Use the private setup command from **getbased → Settings → Agent Access**. It installs or updates [getbased-agent-stack](https://github.com/elkimek/getbased-agents/tree/main/packages/stack), stores the token/key locally, and configures the selected client.
 
 ## How it works
 
@@ -14,21 +14,21 @@ getbased (browser)
   ├── encrypts the rendered agent context with that context key
   └── pushes ciphertext to sync gateway on every save
 
-Sync Gateway (sync.getbased.health/api/context)
+Context gateway (sync.getbased.health/api/context)
   └── stores encrypted context behind token auth; it cannot read the plaintext
 
-RAG Server (localhost, optional)
+Local knowledge server (localhost, optional)
   ├── Vector database with embedded chunks
   ├── Embedding model for semantic search
   └── Your curated health knowledge base
 
 This MCP Server (on your machine)
-  ├── fetches blood work context from sync gateway
-  ├── queries RAG server for knowledge base searches (optional)
+  ├── fetches health context from the context gateway
+  ├── queries the local knowledge server for knowledge-base searches (optional)
   └── exposes everything as tools to any MCP client
 ```
 
-Your mnemonic never leaves your browser. The sync gateway receives only an end-to-end encrypted agent-context envelope; this MCP decrypts it locally with `GETBASED_AGENT_CONTEXT_KEY` and then exposes the same lab context text the getbased AI chat uses — not raw data. `GETBASED_TOKEN` is only the relay bearer token.
+Your mnemonic never leaves your browser. The gateway receives only an encrypted agent-context envelope; this MCP decrypts it locally with `GETBASED_AGENT_CONTEXT_KEY` and exposes the same summary text the getbased AI chat uses. `GETBASED_TOKEN` is only the relay bearer token.
 
 ## Tools
 
@@ -37,7 +37,7 @@ Your mnemonic never leaves your browser. The sync gateway receives only an end-t
 | `getbased_lab_context` | Full lab summary with biomarkers, context cards, supplements, goals. Pass `profile` to target a specific profile. |
 | `getbased_section` | Get a specific section (e.g. hormones, lipids) or list all available sections |
 | `getbased_list_profiles` | List available profiles |
-| `knowledge_search` | Semantic search across the active library on your knowledge base (requires RAG server). Returns relevant passages with source attribution. |
+| `knowledge_search` | Semantic search across the active library on your knowledge base (requires the local knowledge server). Returns relevant passages with source attribution. |
 | `knowledge_list_libraries` | List all knowledge base libraries and show which is active |
 | `knowledge_activate_library` | Switch the active library — subsequent searches target the new one until switched again |
 | `knowledge_stats` | Per-source chunk counts for the active library — useful for diagnosing missing results |
@@ -74,7 +74,7 @@ knowledge_search(query="blue light DHA mitochondrial damage")
 knowledge_search(query="MTHFR methylation folate", n_results=5)
 ```
 
-**Note:** This tool requires the RAG server to be running. Without it, all blood work tools still work — the MCP degrades gracefully.
+**Note:** This tool requires the local knowledge server to be running. If it is not running, knowledge search will fail, but the lab-context tools still work.
 
 ### Multi-library (v0.2+)
 
@@ -102,24 +102,34 @@ The gateway stores context per profile ID. To work with multiple profiles:
 
 ## Setup
 
-### 1. Enable Agent Access in getbased
+### Recommended: copy the private setup command
 
-Go to **Settings > Data > Agent Access** and toggle it on. Copy both values:
+In getbased, open **Settings → Agent Access**, choose your target client, and copy the setup command. It looks like this:
+
+```bash
+curl -fsSL https://getbased.health/install.sh | bash -s -- connect <target> --setup 'gbsetup_v1_...'
+```
+
+The setup payload is private. Paste it only into a terminal you control.
+
+### Manual setup
+
+If you are not using `getbased-stack connect`, open **Settings → Agent Access** and copy both values:
 
 - **Read-only token** → `GETBASED_TOKEN` for relay authorization
 - **Context encryption key** → `GETBASED_AGENT_CONTEXT_KEY` for local decryption
 
-### 2. Set up a RAG server (optional — for knowledge_search)
+### Set up a local knowledge server (optional, for `knowledge_search`)
 
-The knowledge base runs as a separate service. You need:
+The knowledge base runs as a separate service. The easiest path is `getbased-agent-stack[full]`, which installs `getbased-rag` and the browser dashboard. If you are wiring your own server, you need:
 
 - A vector database (e.g. [Qdrant](https://qdrant.tech/), [ChromaDB](https://www.trychroma.com/)) loaded with your document chunks and embeddings
 - A FastAPI (or similar) server that accepts `POST /query` with `{version: 1, query: "...", top_k: N}` and returns `{chunks: [{text: "...", source: "..."}]}`
 - An embedding model (e.g. [BGE-M3](https://huggingface.co/BAAI/bge-m3)) for semantic search
 
-The RAG server handles embedding, similarity search, and filtering. This MCP just sends HTTP queries to it — no models loaded here.
+The local knowledge server handles embedding, similarity search, and filtering. This MCP just sends HTTP queries to it; no models are loaded inside the MCP process.
 
-**RAG server contract:**
+**Knowledge server contract:**
 
 | Field | Required | Description |
 |---|---|---|
@@ -128,7 +138,7 @@ The RAG server handles embedding, similarity search, and filtering. This MCP jus
 | `GET /health` | Optional | Returns `{"status": "ok", "rag_ready": bool, "chunks": int}` |
 | Response | Yes | `{"chunks": [{"text": "...", "source": "..."}]}` |
 
-### 3. Configure your MCP client
+### Configure your MCP client manually
 
 #### Claude Code / Claude Desktop
 
@@ -157,7 +167,7 @@ hermes mcp add getbased \
   --args /path/to/getbased_mcp.py
 ```
 
-Then set `GETBASED_TOKEN` and `GETBASED_AGENT_CONTEXT_KEY` in `~/.hermes/.env` or in the MCP server's `env` config in `config.yaml`:
+Then set `GETBASED_TOKEN` and `GETBASED_AGENT_CONTEXT_KEY` in the MCP server's `env` config in `config.yaml`:
 
 ```yaml
 mcp_servers:
@@ -182,30 +192,30 @@ Ask about your labs in any connected conversation:
 
 | Variable | Required | Description |
 |---|---|---|
-| `GETBASED_TOKEN` | Yes | Read-only bearer token from getbased Settings > Data > Agent Access; authorizes fetches from the context gateway |
-| `GETBASED_AGENT_CONTEXT_KEY` | Yes for encrypted Agent Access payloads | Context encryption key from getbased Settings > Data > Agent Access; decrypts the relay payload locally in this MCP |
+| `GETBASED_TOKEN` | Yes | Read-only bearer token from getbased Settings → Agent Access; authorizes fetches from the context gateway |
+| `GETBASED_AGENT_CONTEXT_KEY` | Yes for encrypted Agent Access payloads | Context encryption key from getbased Settings → Agent Access; decrypts the relay payload locally in this MCP |
 | `GETBASED_GATEWAY` | No | Context gateway URL (default: `https://sync.getbased.health`) |
-| `LENS_URL` | No | RAG server URL (default: `http://localhost:8322`). Overrides `LENS_PORT` |
-| `LENS_PORT` | No | RAG server port, only used to build default `LENS_URL` (default: `8322`) |
-| `LENS_API_KEY_FILE` | No | Path to RAG API key file. Default: `$XDG_DATA_HOME/getbased/lens/api_key` (getbased-rag's canonical location). If that file doesn't exist but the legacy `~/.hermes/rag/lens_api_key` does, the legacy path is used instead — upgrades from standalone `getbased-mcp` ≤ 0.1.0 keep working without config changes. |
+| `LENS_URL` | No | Local knowledge server URL (default: `http://localhost:8322`). Overrides `LENS_PORT` |
+| `LENS_PORT` | No | Local knowledge server port, only used to build default `LENS_URL` (default: `8322`) |
+| `LENS_API_KEY_FILE` | No | Path to the knowledge server API key file. Default: `$XDG_DATA_HOME/getbased/lens/api_key` (getbased-rag's canonical location). If that file doesn't exist but the legacy `~/.hermes/rag/lens_api_key` does, the legacy path is used instead; upgrades from standalone `getbased-mcp` ≤ 0.1.0 keep working without config changes. |
 | `LENS_MCP_ACTIVITY_LOG` | No | JSONL path where tool-call activity is appended. Default: `$XDG_STATE_HOME/getbased/mcp/activity.jsonl`. Each record: `{ts, tool, duration_ms, ok, error?}` — arguments are never logged (queries may contain sensitive health info). Set to `off` / `false` / `0` to disable. The [getbased-dashboard](https://github.com/elkimek/getbased-agents/tree/main/packages/dashboard) Activity tab tails this file. |
 
 ## Custom Knowledge Source (getbased app)
 
-The same RAG server that powers `knowledge_search` for your AI client can also back the in-app AI chat. To connect them:
+The same local knowledge server that powers `knowledge_search` for your AI client can also back the in-app AI chat. To connect them:
 
 1. Run `getbased_lens_config` — it returns the endpoint URL, API key, and recommended `top_k`
-2. In getbased, go to **Settings → AI → Custom Knowledge Source**
+2. In getbased, open **Knowledge Base** and choose **External server**
 3. Paste the endpoint URL, API key, and set `top_k` to 5
 4. Enable it — the chat-header Lens badge will light up green when active
 
-Every chat question and focus card will now be enriched with RAG-retrieved passages from your knowledge base.
+Every chat question and Current Focus refresh can now include passages from your knowledge base.
 
 ## Troubleshooting
 
 ### `knowledge_search` returns "Lens server not reachable"
 
-The RAG server isn't running. Start it and verify with:
+The local knowledge server is not running. Start it and verify with:
 
 ```bash
 curl http://localhost:8322/health
@@ -213,7 +223,7 @@ curl http://localhost:8322/health
 
 ### `knowledge_search` returns "Lens API key not found"
 
-getbased-rag generates its API key on first start and writes it to `$XDG_DATA_HOME/getbased/lens/api_key` (e.g. `~/.local/share/getbased/lens/api_key` on Linux). If you're upgrading from the standalone `getbased-mcp` ≤ 0.1.0 and your key is at `~/.hermes/rag/lens_api_key`, that legacy path is still auto-detected — no config change needed. If the file is missing entirely, restart the RAG server and it will create a new one.
+getbased-rag generates its API key on first start and writes it to `$XDG_DATA_HOME/getbased/lens/api_key` (e.g. `~/.local/share/getbased/lens/api_key` on Linux). If you're upgrading from the standalone `getbased-mcp` ≤ 0.1.0 and your key is at `~/.hermes/rag/lens_api_key`, that legacy path is still auto-detected; no config change needed. If the file is missing entirely, restart the knowledge server and it will create a new one.
 
 ### `knowledge_list_libraries` / `knowledge_stats` return "this lens server doesn't expose library management"
 
@@ -221,7 +231,7 @@ The lens server you're pointed at is older than `getbased-rag` 0.1.0 and doesn't
 
 ### Blood work tools work but knowledge_search doesn't
 
-That's expected — they're independent. Blood work tools talk to the sync gateway; knowledge_search talks to the RAG server. The MCP degrades gracefully: if the RAG server is down, all blood work tools continue to work normally.
+That's expected. Blood work tools talk to the context gateway; `knowledge_search` talks to the local knowledge server. If the knowledge server is down, knowledge search will fail, but the lab-context tools continue to work normally.
 
 ## Security
 
@@ -233,7 +243,7 @@ That's expected — they're independent. Blood work tools talk to the sync gatew
 
 ## Related projects
 
-- **[getbased](https://github.com/elkimek/get-based)** — the health dashboard. This MCP reads the same lab context the in-app AI chat uses, and queries the same Knowledge Source endpoint configured in Settings → AI → Custom Knowledge Source. The [endpoint contract](https://github.com/elkimek/get-based/blob/main/dev-docs/lens-endpoint-contract.md) is shared — one server backs both the app and this MCP.
+- **[getbased](https://github.com/elkimek/get-based)** — the health dashboard. This MCP reads the same context the in-app AI chat uses, and can query the same external Knowledge Base server configured in the app. The endpoint contract is shared: one server can back both the app and this MCP.
 
 ## License
 

{getbased_mcp-0.2.6 → getbased_mcp-0.2.7}/getbased_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getbased-mcp
-Version: 0.2.6
+Version: 0.2.7
 Summary: MCP server for querying blood work data and knowledge base from getbased
 License-Expression: AGPL-3.0-or-later
 Requires-Python: >=3.10
@@ -8,7 +8,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: httpx>=0.27
-Requires-Dist: cryptography>=42.0
+Requires-Dist: cryptography>=48.0.1
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23; extra == "test"
@@ -17,9 +17,9 @@ Dynamic: license-file
 
 # getbased MCP Server
 
-An [MCP](https://modelcontextprotocol.io) server that exposes blood work data and an optional RAG knowledge base from [getbased](https://getbased.health) as tools. Works with any MCP-compatible client (Claude Code, Hermes, Claude Desktop, etc.).
+An [MCP](https://modelcontextprotocol.io) server that exposes getbased health context and an optional local knowledge base as tools. Works with MCP-compatible clients such as Claude Code, Claude Desktop, Cursor, Cline, Codex CLI, Hermes, and OpenClaw.
 
-> **Installing for the first time?** The [getbased-agent-stack](https://github.com/elkimek/getbased-agents/tree/main/packages/stack) meta-package bundles this MCP with the RAG engine it talks to, plus example configs for Claude Code and Hermes. One command and you're up.
+> **Installing for the first time?** Use the private setup command from **getbased → Settings → Agent Access**. It installs or updates [getbased-agent-stack](https://github.com/elkimek/getbased-agents/tree/main/packages/stack), stores the token/key locally, and configures the selected client.
 
 ## How it works
 
@@ -31,21 +31,21 @@ getbased (browser)
   ├── encrypts the rendered agent context with that context key
   └── pushes ciphertext to sync gateway on every save
 
-Sync Gateway (sync.getbased.health/api/context)
+Context gateway (sync.getbased.health/api/context)
   └── stores encrypted context behind token auth; it cannot read the plaintext
 
-RAG Server (localhost, optional)
+Local knowledge server (localhost, optional)
   ├── Vector database with embedded chunks
   ├── Embedding model for semantic search
   └── Your curated health knowledge base
 
 This MCP Server (on your machine)
-  ├── fetches blood work context from sync gateway
-  ├── queries RAG server for knowledge base searches (optional)
+  ├── fetches health context from the context gateway
+  ├── queries the local knowledge server for knowledge-base searches (optional)
   └── exposes everything as tools to any MCP client
 ```
 
-Your mnemonic never leaves your browser. The sync gateway receives only an end-to-end encrypted agent-context envelope; this MCP decrypts it locally with `GETBASED_AGENT_CONTEXT_KEY` and then exposes the same lab context text the getbased AI chat uses — not raw data. `GETBASED_TOKEN` is only the relay bearer token.
+Your mnemonic never leaves your browser. The gateway receives only an encrypted agent-context envelope; this MCP decrypts it locally with `GETBASED_AGENT_CONTEXT_KEY` and exposes the same summary text the getbased AI chat uses. `GETBASED_TOKEN` is only the relay bearer token.
 
 ## Tools
 
@@ -54,7 +54,7 @@ Your mnemonic never leaves your browser. The sync gateway receives only an end-t
 | `getbased_lab_context` | Full lab summary with biomarkers, context cards, supplements, goals. Pass `profile` to target a specific profile. |
 | `getbased_section` | Get a specific section (e.g. hormones, lipids) or list all available sections |
 | `getbased_list_profiles` | List available profiles |
-| `knowledge_search` | Semantic search across the active library on your knowledge base (requires RAG server). Returns relevant passages with source attribution. |
+| `knowledge_search` | Semantic search across the active library on your knowledge base (requires the local knowledge server). Returns relevant passages with source attribution. |
 | `knowledge_list_libraries` | List all knowledge base libraries and show which is active |
 | `knowledge_activate_library` | Switch the active library — subsequent searches target the new one until switched again |
 | `knowledge_stats` | Per-source chunk counts for the active library — useful for diagnosing missing results |
@@ -91,7 +91,7 @@ knowledge_search(query="blue light DHA mitochondrial damage")
 knowledge_search(query="MTHFR methylation folate", n_results=5)
 ```
 
-**Note:** This tool requires the RAG server to be running. Without it, all blood work tools still work — the MCP degrades gracefully.
+**Note:** This tool requires the local knowledge server to be running. If it is not running, knowledge search will fail, but the lab-context tools still work.
 
 ### Multi-library (v0.2+)
 
@@ -119,24 +119,34 @@ The gateway stores context per profile ID. To work with multiple profiles:
 
 ## Setup
 
-### 1. Enable Agent Access in getbased
+### Recommended: copy the private setup command
 
-Go to **Settings > Data > Agent Access** and toggle it on. Copy both values:
+In getbased, open **Settings → Agent Access**, choose your target client, and copy the setup command. It looks like this:
+
+```bash
+curl -fsSL https://getbased.health/install.sh | bash -s -- connect <target> --setup 'gbsetup_v1_...'
+```
+
+The setup payload is private. Paste it only into a terminal you control.
+
+### Manual setup
+
+If you are not using `getbased-stack connect`, open **Settings → Agent Access** and copy both values:
 
 - **Read-only token** → `GETBASED_TOKEN` for relay authorization
 - **Context encryption key** → `GETBASED_AGENT_CONTEXT_KEY` for local decryption
 
-### 2. Set up a RAG server (optional — for knowledge_search)
+### Set up a local knowledge server (optional, for `knowledge_search`)
 
-The knowledge base runs as a separate service. You need:
+The knowledge base runs as a separate service. The easiest path is `getbased-agent-stack[full]`, which installs `getbased-rag` and the browser dashboard. If you are wiring your own server, you need:
 
 - A vector database (e.g. [Qdrant](https://qdrant.tech/), [ChromaDB](https://www.trychroma.com/)) loaded with your document chunks and embeddings
 - A FastAPI (or similar) server that accepts `POST /query` with `{version: 1, query: "...", top_k: N}` and returns `{chunks: [{text: "...", source: "..."}]}`
 - An embedding model (e.g. [BGE-M3](https://huggingface.co/BAAI/bge-m3)) for semantic search
 
-The RAG server handles embedding, similarity search, and filtering. This MCP just sends HTTP queries to it — no models loaded here.
+The local knowledge server handles embedding, similarity search, and filtering. This MCP just sends HTTP queries to it; no models are loaded inside the MCP process.
 
-**RAG server contract:**
+**Knowledge server contract:**
 
 | Field | Required | Description |
 |---|---|---|
@@ -145,7 +155,7 @@ The RAG server handles embedding, similarity search, and filtering. This MCP jus
 | `GET /health` | Optional | Returns `{"status": "ok", "rag_ready": bool, "chunks": int}` |
 | Response | Yes | `{"chunks": [{"text": "...", "source": "..."}]}` |
 
-### 3. Configure your MCP client
+### Configure your MCP client manually
 
 #### Claude Code / Claude Desktop
 
@@ -174,7 +184,7 @@ hermes mcp add getbased \
   --args /path/to/getbased_mcp.py
 ```
 
-Then set `GETBASED_TOKEN` and `GETBASED_AGENT_CONTEXT_KEY` in `~/.hermes/.env` or in the MCP server's `env` config in `config.yaml`:
+Then set `GETBASED_TOKEN` and `GETBASED_AGENT_CONTEXT_KEY` in the MCP server's `env` config in `config.yaml`:
 
 ```yaml
 mcp_servers:
@@ -199,30 +209,30 @@ Ask about your labs in any connected conversation:
 
 | Variable | Required | Description |
 |---|---|---|
-| `GETBASED_TOKEN` | Yes | Read-only bearer token from getbased Settings > Data > Agent Access; authorizes fetches from the context gateway |
-| `GETBASED_AGENT_CONTEXT_KEY` | Yes for encrypted Agent Access payloads | Context encryption key from getbased Settings > Data > Agent Access; decrypts the relay payload locally in this MCP |
+| `GETBASED_TOKEN` | Yes | Read-only bearer token from getbased Settings → Agent Access; authorizes fetches from the context gateway |
+| `GETBASED_AGENT_CONTEXT_KEY` | Yes for encrypted Agent Access payloads | Context encryption key from getbased Settings → Agent Access; decrypts the relay payload locally in this MCP |
 | `GETBASED_GATEWAY` | No | Context gateway URL (default: `https://sync.getbased.health`) |
-| `LENS_URL` | No | RAG server URL (default: `http://localhost:8322`). Overrides `LENS_PORT` |
-| `LENS_PORT` | No | RAG server port, only used to build default `LENS_URL` (default: `8322`) |
-| `LENS_API_KEY_FILE` | No | Path to RAG API key file. Default: `$XDG_DATA_HOME/getbased/lens/api_key` (getbased-rag's canonical location). If that file doesn't exist but the legacy `~/.hermes/rag/lens_api_key` does, the legacy path is used instead — upgrades from standalone `getbased-mcp` ≤ 0.1.0 keep working without config changes. |
+| `LENS_URL` | No | Local knowledge server URL (default: `http://localhost:8322`). Overrides `LENS_PORT` |
+| `LENS_PORT` | No | Local knowledge server port, only used to build default `LENS_URL` (default: `8322`) |
+| `LENS_API_KEY_FILE` | No | Path to the knowledge server API key file. Default: `$XDG_DATA_HOME/getbased/lens/api_key` (getbased-rag's canonical location). If that file doesn't exist but the legacy `~/.hermes/rag/lens_api_key` does, the legacy path is used instead; upgrades from standalone `getbased-mcp` ≤ 0.1.0 keep working without config changes. |
 | `LENS_MCP_ACTIVITY_LOG` | No | JSONL path where tool-call activity is appended. Default: `$XDG_STATE_HOME/getbased/mcp/activity.jsonl`. Each record: `{ts, tool, duration_ms, ok, error?}` — arguments are never logged (queries may contain sensitive health info). Set to `off` / `false` / `0` to disable. The [getbased-dashboard](https://github.com/elkimek/getbased-agents/tree/main/packages/dashboard) Activity tab tails this file. |
 
 ## Custom Knowledge Source (getbased app)
 
-The same RAG server that powers `knowledge_search` for your AI client can also back the in-app AI chat. To connect them:
+The same local knowledge server that powers `knowledge_search` for your AI client can also back the in-app AI chat. To connect them:
 
 1. Run `getbased_lens_config` — it returns the endpoint URL, API key, and recommended `top_k`
-2. In getbased, go to **Settings → AI → Custom Knowledge Source**
+2. In getbased, open **Knowledge Base** and choose **External server**
 3. Paste the endpoint URL, API key, and set `top_k` to 5
 4. Enable it — the chat-header Lens badge will light up green when active
 
-Every chat question and focus card will now be enriched with RAG-retrieved passages from your knowledge base.
+Every chat question and Current Focus refresh can now include passages from your knowledge base.
 
 ## Troubleshooting
 
 ### `knowledge_search` returns "Lens server not reachable"
 
-The RAG server isn't running. Start it and verify with:
+The local knowledge server is not running. Start it and verify with:
 
 ```bash
 curl http://localhost:8322/health
@@ -230,7 +240,7 @@ curl http://localhost:8322/health
 
 ### `knowledge_search` returns "Lens API key not found"
 
-getbased-rag generates its API key on first start and writes it to `$XDG_DATA_HOME/getbased/lens/api_key` (e.g. `~/.local/share/getbased/lens/api_key` on Linux). If you're upgrading from the standalone `getbased-mcp` ≤ 0.1.0 and your key is at `~/.hermes/rag/lens_api_key`, that legacy path is still auto-detected — no config change needed. If the file is missing entirely, restart the RAG server and it will create a new one.
+getbased-rag generates its API key on first start and writes it to `$XDG_DATA_HOME/getbased/lens/api_key` (e.g. `~/.local/share/getbased/lens/api_key` on Linux). If you're upgrading from the standalone `getbased-mcp` ≤ 0.1.0 and your key is at `~/.hermes/rag/lens_api_key`, that legacy path is still auto-detected; no config change needed. If the file is missing entirely, restart the knowledge server and it will create a new one.
 
 ### `knowledge_list_libraries` / `knowledge_stats` return "this lens server doesn't expose library management"
 
@@ -238,7 +248,7 @@ The lens server you're pointed at is older than `getbased-rag` 0.1.0 and doesn't
 
 ### Blood work tools work but knowledge_search doesn't
 
-That's expected — they're independent. Blood work tools talk to the sync gateway; knowledge_search talks to the RAG server. The MCP degrades gracefully: if the RAG server is down, all blood work tools continue to work normally.
+That's expected. Blood work tools talk to the context gateway; `knowledge_search` talks to the local knowledge server. If the knowledge server is down, knowledge search will fail, but the lab-context tools continue to work normally.
 
 ## Security
 
@@ -250,7 +260,7 @@ That's expected — they're independent. Blood work tools talk to the sync gatew
 
 ## Related projects
 
-- **[getbased](https://github.com/elkimek/get-based)** — the health dashboard. This MCP reads the same lab context the in-app AI chat uses, and queries the same Knowledge Source endpoint configured in Settings → AI → Custom Knowledge Source. The [endpoint contract](https://github.com/elkimek/get-based/blob/main/dev-docs/lens-endpoint-contract.md) is shared — one server backs both the app and this MCP.
+- **[getbased](https://github.com/elkimek/get-based)** — the health dashboard. This MCP reads the same context the in-app AI chat uses, and can query the same external Knowledge Base server configured in the app. The endpoint contract is shared: one server can back both the app and this MCP.
 
 ## License
 

{getbased_mcp-0.2.6 → getbased_mcp-0.2.7}/getbased_mcp.egg-info/requires.txt

@@ -1,6 +1,6 @@
 mcp>=1.0.0
 httpx>=0.27
-cryptography>=42.0
+cryptography>=48.0.1
 
 [test]
 pytest>=8.0

{getbased_mcp-0.2.6 → getbased_mcp-0.2.7}/getbased_mcp.py

@@ -419,8 +419,8 @@ async def _lens_call(method: str, path: str, json_body: dict | None = None) -> d
                 body = e.response.json()
                 if body.get("detail") == "Not Found":
                     return {"error": "unsupported_endpoint"}
-            except (json.JSONDecodeError, ValueError):
-                pass
+            except (json.JSONDecodeError, ValueError) as parse_error:
+                log.debug("Unable to parse Lens 404 response body: %s", parse_error)
         # Same rationale as _lens_request: truncate the body preview so
         # internal details don't end up in a cloud AI client's context.
         preview = (e.response.text or "")[:_UPSTREAM_ERROR_PREVIEW]

{getbased_mcp-0.2.6 → getbased_mcp-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "getbased-mcp"
-version = "0.2.6"
+version = "0.2.7"
 description = "MCP server for querying blood work data and knowledge base from getbased"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -12,7 +12,7 @@ requires-python = ">=3.10"
 dependencies = [
     "mcp>=1.0.0",
     "httpx>=0.27",
-    "cryptography>=42.0",
+    "cryptography>=48.0.1",
 ]
 
 [project.optional-dependencies]

{getbased_mcp-0.2.6 → getbased_mcp-0.2.7}/tests/test_tools.py

@@ -268,7 +268,6 @@ async def test_knowledge_search_happy(gm) -> None:
     assert route.called
     req = route.calls[0].request
     assert req.headers["Authorization"] == "Bearer test-lens-key"
-    import json
     body = json.loads(req.content)
     assert body == {"version": 1, "query": "vitamin D", "top_k": 2}
     # Response rendered
@@ -283,7 +282,6 @@ async def test_knowledge_search_clamps_n_results(gm) -> None:
     route = respx.post(f"{LENS_URL_PREFIX}/query").mock(return_value=Response(200, json={"chunks": []}))
     # n_results=99 → clamped to 10
     await gm.knowledge_search(query="x", n_results=99)
-    import json
     body = json.loads(route.calls[0].request.content)
     assert body["top_k"] == 10
     # n_results=0 → clamped to 1