getbased-mcp 0.2.2__py3-none-any.whl

getbased_mcp-0.2.2.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: getbased-mcp
+Version: 0.2.2
+Summary: MCP server for querying blood work data and knowledge base from getbased
+License-Expression: GPL-3.0-only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: respx>=0.21; extra == "test"
+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.).
+
+> **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.
+
+## How it works
+
+```
+getbased (browser)
+  ├── your data, your mnemonic
+  ├── generates a read-only token
+  └── pushes lab context to sync gateway on every save
+
+Sync Gateway (sync.getbased.health/api/context)
+  └── stores context text behind token auth
+
+RAG 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)
+  └── exposes everything as tools to any MCP client
+```
+
+Your mnemonic never leaves your browser. The MCP server receives the same lab context text the getbased AI chat uses — not raw data.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `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_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 |
+| `getbased_lens_config` | Show RAG endpoint config for getbased's Knowledge Base (External server) |
+
+### getbased_section
+
+Query-aware context: pull just the section you need instead of the full dump. Saves tokens and allows deeper analysis of specific areas.
+
+```
+# No args — returns section index with names, updated dates, and line counts
+getbased_section()
+
+# With section name — returns just that section's content
+getbased_section(section="hormones")
+
+# With profile — query a specific profile
+getbased_section(section="hormones", profile="mne8m9hf")
+```
+
+Section names are matched by prefix, so `hormones` matches `hormones updated:2026-03-13`.
+
+### knowledge_search
+
+**What is RAG?** Retrieval-Augmented Generation (RAG) is a technique where an AI assistant's responses are grounded in a specific knowledge base. Instead of relying solely on training data, the assistant first searches a curated collection of documents for relevant passages, then uses those passages to inform its answer. This makes the AI's output more accurate, more specific, and traceable to real sources.
+
+The `knowledge_search` tool searches your knowledge base using semantic similarity — meaning it finds passages that match the *meaning* of your query, not just keywords. Results include the passage text and source attribution.
+
+```
+# Basic search
+knowledge_search(query="blue light DHA mitochondrial damage")
+
+# With result count (1–10, default 5)
+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.
+
+### Multi-library (v0.2+)
+
+The Lens server (0.2+ of `getbased-rag`) supports multiple libraries — keep research papers, clinical guides, and personal notes in separate collections and switch between them. `knowledge_search` always targets the currently active library.
+
+```
+# See what's available and which is active
+knowledge_list_libraries()
+
+# Switch. Subsequent knowledge_search calls hit this library until switched again
+knowledge_activate_library(library_id="<id-from-list>")
+
+# Confirm what's indexed in the active library
+knowledge_stats()
+```
+
+## Multi-profile
+
+The gateway stores context per profile ID. To work with multiple profiles:
+
+- Use `getbased_list_profiles` to see available profiles and their IDs
+- Pass `profile="id"` to any tool to query a specific profile
+- Omit the `profile` param to use the default profile
+- Each profile's context is pushed automatically when data is saved or the profile is switched in getbased
+
+## Setup
+
+### 1. Enable messenger access in getbased
+
+Go to **Settings > Data > Messenger Access** and toggle it on. Copy the read-only token.
+
+### 2. Set up a RAG server (optional — for knowledge_search)
+
+The knowledge base runs as a separate service. 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.
+
+**RAG server contract:**
+
+| Field | Required | Description |
+|---|---|---|
+| `POST /query` | Yes | Accepts JSON body with `version` (int), `query` (string), `top_k` (int) |
+| `Authorization` | Recommended | Bearer token auth |
+| `GET /health` | Optional | Returns `{"status": "ok", "rag_ready": bool, "chunks": int}` |
+| Response | Yes | `{"chunks": [{"text": "...", "source": "..."}]}` |
+
+### 3. Configure your MCP client
+
+#### Claude Code / Claude Desktop
+
+Add to your MCP config (`~/.claude/claude_desktop_config.json` or similar):
+
+```json
+{
+  "mcpServers": {
+    "getbased": {
+      "command": "python3",
+      "args": ["/path/to/getbased_mcp.py"],
+      "env": {
+        "GETBASED_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+#### Hermes Agent
+
+```bash
+hermes mcp add getbased \
+  --command python3 \
+  --args /path/to/getbased_mcp.py
+```
+
+Then set `GETBASED_TOKEN` in `~/.hermes/.env` or in the MCP server's `env` config in `config.yaml`:
+
+```yaml
+mcp_servers:
+  getbased:
+    command: python3
+    args: [/path/to/getbased_mcp.py]
+    env:
+      GETBASED_TOKEN: your-token-here
+```
+
+### 4. Use it
+
+Ask about your labs in any connected conversation:
+
+> "How's my vitamin D?"
+> "What markers are out of range?"
+> "Summarize my latest blood work"
+> "What does the knowledge base say about blue light and DHA?"
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GETBASED_TOKEN` | Yes | Read-only token from getbased Settings > Data > Messenger Access |
+| `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_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:
+
+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**
+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.
+
+## Troubleshooting
+
+### `knowledge_search` returns "Lens server not reachable"
+
+The RAG server isn't running. Start it and verify with:
+
+```bash
+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.
+
+### `knowledge_list_libraries` / `knowledge_stats` return "this lens server doesn't expose library management"
+
+The lens server you're pointed at is older than `getbased-rag` 0.1.0 and doesn't implement the `/libraries` or `/stats` endpoints. `knowledge_search` still works against older lens servers since `/query` is protocol-stable. To get library management, either upgrade the lens, or set `LENS_URL` to a library-capable endpoint.
+
+### 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.
+
+## Security
+
+- **Read-only**: the token grants access to lab context text only — no raw data, no write access
+- **Self-hosted**: the MCP server runs on your own machine
+- **Revocable**: regenerate the token in getbased to revoke access instantly
+- **No mnemonic exposure**: the token is independent of your sync mnemonic
+- **No models in-process**: RAG queries go through the external server — no embedding models loaded in the MCP process
+
+## 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/docs/guide/interpretive-lens.md#for-developers-endpoint-contract) is shared — one server backs both the app and this MCP.
+
+## License
+
+GPL-3.0

getbased_mcp-0.2.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+getbased_mcp.py,sha256=f9U-ccIL3luCFaiSrvptXvbbw4mFHNCqeEqJ_TdcWhc,20383
+getbased_mcp-0.2.2.dist-info/licenses/LICENSE,sha256=K-IjLWkez1gJQMrlqA5zgyw8vh19mDzk4hKM9Dslmts,1024
+getbased_mcp-0.2.2.dist-info/METADATA,sha256=JvIeETshnXJ02Jk8KT2avWcXu3L3PkqjcWvQR0SEwGI,11548
+getbased_mcp-0.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+getbased_mcp-0.2.2.dist-info/entry_points.txt,sha256=2zDMmXMwt19of7uTcNc7QcAN_UEXNm_8WjmTY4S4XnE,54
+getbased_mcp-0.2.2.dist-info/top_level.txt,sha256=DWlf4BxLap2aHz8j89KiHN08NKowHuSssssqKxIgZ9Y,13
+getbased_mcp-0.2.2.dist-info/RECORD,,

getbased_mcp-0.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

getbased_mcp-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+getbased-mcp = getbased_mcp:mcp.run

getbased_mcp-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  For the full license text, see <https://www.gnu.org/licenses/gpl-3.0.txt>

getbased_mcp-0.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+getbased_mcp

getbased_mcp.py

@@ -0,0 +1,488 @@
+#!/usr/bin/env python3
+"""getbased MCP server — exposes blood work data and knowledge base search as tools.
+
+Architecture:
+  getbased (browser) → sync gateway → this MCP → your AI client
+                                          ↕
+                                    Lens RAG server (Qdrant + BGE-M3)
+
+Blood work data is fetched from the getbased sync gateway.
+Knowledge base queries go through the Lens RAG server (separate process).
+No models are loaded in this process — everything is HTTP.
+"""
+
+import functools
+import json
+import logging
+import os
+import re
+import time
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+log = logging.getLogger("getbased_mcp")
+
+mcp = FastMCP("getbased")
+
+# ── Config ───────────────────────────────────────────────────────────
+TOKEN = os.environ.get("GETBASED_TOKEN", "")
+GATEWAY = os.environ.get("GETBASED_GATEWAY", "https://sync.getbased.health")
+
+LENS_URL = os.environ.get("LENS_URL", f"http://localhost:{os.environ.get('LENS_PORT', '8322')}")
+
+
+def _resolve_default_key_file() -> str:
+    """Default Lens API key path. Prefer the XDG location used by getbased-rag;
+    fall back to the legacy ~/.hermes/rag/lens_api_key so upgrades from the
+    standalone getbased-mcp ≤ 0.1.0 don't silently break on boxes that still
+    have the old key there (e.g. Hermes VMs)."""
+    xdg = os.environ.get("XDG_DATA_HOME", os.path.expanduser("~/.local/share"))
+    new_default = os.path.join(xdg, "getbased", "lens", "api_key")
+    legacy = os.path.expanduser("~/.hermes/rag/lens_api_key")
+    if not os.path.exists(new_default) and os.path.exists(legacy):
+        return legacy
+    return new_default
+
+
+LENS_API_KEY_FILE = os.environ.get("LENS_API_KEY_FILE", _resolve_default_key_file())
+
+# Friendly message surfaced when a tool hits a route the lens server doesn't
+# expose (old lens, pre-libraries). See _lens_call's 404 handling.
+_UNSUPPORTED_LENS_HINT = (
+    "this lens server doesn't expose library management. "
+    "Upgrade to getbased-rag ≥ 0.2.0, or point LENS_URL at a library-capable lens."
+)
+
+# Cap on how much of an upstream error body we echo back to the AI client.
+# Rag's exception_handler emits its own {error: ...} payload — safe in a
+# self-hosted trust model, but that error often ends up in a cloud LLM's
+# context window where the full response text (stack traces, file paths)
+# would be sensitive. Truncate to a short hint.
+_UPSTREAM_ERROR_PREVIEW = 200
+
+
+# ── Activity logging ────────────────────────────────────────────────
+# Every tool call writes one JSONL record: tool name, wall-clock ts,
+# duration in ms, success flag, and error-class on failure. **Args are
+# never logged** — queries can contain sensitive health info, so we
+# record the shape of usage, not its content. The dashboard tails this
+# file for the Activity tab; with no dashboard installed the file is
+# just a rotating-by-hand log the user can inspect.
+#
+# Default path is $XDG_STATE_HOME/getbased/mcp/activity.jsonl
+# (~/.local/state/getbased/mcp/activity.jsonl on Linux). Override with
+# LENS_MCP_ACTIVITY_LOG. Set LENS_MCP_ACTIVITY_LOG=off to disable.
+
+def _activity_log_path() -> str:
+    """Resolve where activity records get appended. Env override wins;
+    otherwise XDG_STATE_HOME. Returns "" when logging is disabled."""
+    override = os.environ.get("LENS_MCP_ACTIVITY_LOG")
+    if override is not None:
+        return "" if override.lower() in ("off", "false", "0", "") else override
+    state = os.environ.get("XDG_STATE_HOME", os.path.expanduser("~/.local/state"))
+    return os.path.join(state, "getbased", "mcp", "activity.jsonl")
+
+
+def _append_activity(tool: str, duration_ms: int, ok: bool, error: str) -> None:
+    """Best-effort JSONL append. Any I/O failure is swallowed — telemetry
+    must never break a tool call. Directory is created on first write."""
+    path = _activity_log_path()
+    if not path:
+        return
+    record = {
+        "ts": time.time(),
+        "tool": tool,
+        "duration_ms": duration_ms,
+        "ok": ok,
+    }
+    if error:
+        record["error"] = error
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record) + "\n")
+    except OSError as e:
+        # Don't spam stderr in stdio MCP (it'd confuse the MCP client).
+        # Debug-level is fine; the user can inspect via Python logging.
+        log.debug("activity log append failed: %s", e)
+
+
+def _instrumented(label: str):
+    """Wrap an async tool implementation with success/failure + duration
+    logging. Applied below each `@mcp.tool()` so the registered callable
+    is the instrumented one. Preserves the function's signature and
+    docstring via functools.wraps — FastMCP's tool registration reads
+    those to build the tool schema."""
+
+    def deco(fn):
+        @functools.wraps(fn)
+        async def wrapper(*args, **kwargs):
+            t0 = time.monotonic()
+            error_name = ""
+            ok = True
+            try:
+                return await fn(*args, **kwargs)
+            except Exception as e:
+                ok = False
+                error_name = type(e).__name__
+                raise
+            finally:
+                _append_activity(
+                    label,
+                    int((time.monotonic() - t0) * 1000),
+                    ok,
+                    error_name,
+                )
+
+        return wrapper
+
+    return deco
+
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+async def _fetch_context(profile: str = "") -> dict:
+    """Fetch formatted lab context from the getbased sync gateway."""
+    if not TOKEN:
+        return {"error": "GETBASED_TOKEN not set"}
+    try:
+        params = {"profile": profile} if profile else {}
+        async with httpx.AsyncClient(timeout=15) as client:
+            r = await client.get(
+                f"{GATEWAY}/api/context",
+                headers={"Authorization": f"Bearer {TOKEN}"},
+                params=params,
+            )
+            r.raise_for_status()
+            return r.json()
+    except httpx.HTTPStatusError as e:
+        return {"error": f"getbased gateway returned {e.response.status_code}"}
+    except httpx.RequestError as e:
+        return {"error": f"Failed to reach getbased gateway: {e}"}
+
+
+def _parse_sections(context: str) -> dict[str, str]:
+    """Parse [section:name ...]...[/section:name] blocks → {full_name: content}."""
+    sections = {}
+    for m in re.finditer(
+        r"\[section:(\S+)([^\]]*)\]([\s\S]*?)\[/section:\1\]", context
+    ):
+        base = m.group(1)
+        meta = m.group(2).strip()
+        full_name = f"{base} {meta}" if meta else base
+        sections[full_name] = m.group(3).strip()
+    return sections
+
+
+def _read_lens_key() -> str:
+    """Read the Lens API key from file (generated by lens_server.py)."""
+    try:
+        with open(LENS_API_KEY_FILE) as f:
+            key = f.read().strip()
+        return key if key else ""
+    except OSError:
+        return ""
+
+
+async def _lens_request(query: str, top_k: int = 5) -> dict:
+    """Send a query to the Lens RAG server. Returns parsed JSON or error dict."""
+    key = _read_lens_key()
+    if not key:
+        return {"error": "Lens API key not found. Start lens_server.py first."}
+    try:
+        async with httpx.AsyncClient(timeout=60) as client:
+            r = await client.post(
+                f"{LENS_URL}/query",
+                headers={"Authorization": f"Bearer {key}"},
+                json={"version": 1, "query": query, "top_k": top_k},
+            )
+            r.raise_for_status()
+            if len(r.content) > 32 * 1024:
+                return {"error": "Lens response exceeds 32 KB — possible server issue"}
+            return r.json()
+    except httpx.ConnectError:
+        return {"error": f"Lens server not reachable at {LENS_URL}. Is it running?"}
+    except httpx.HTTPStatusError as e:
+        # The error surfaces into an AI client (typically cloud-hosted),
+        # so don't forward the raw response text — it may contain internal
+        # paths or stack traces. Truncate to a short preview; if an
+        # operator needs more detail they have the lens logs.
+        preview = (e.response.text or "")[:_UPSTREAM_ERROR_PREVIEW]
+        return {"error": f"Lens returned {e.response.status_code}: {preview}"}
+    except httpx.RequestError as e:
+        return {"error": f"Lens request failed: {e}"}
+    except (json.JSONDecodeError, ValueError) as e:
+        return {"error": f"Lens returned invalid JSON: {e}"}
+
+
+async def _lens_call(method: str, path: str, json_body: dict | None = None) -> dict:
+    """Generic authenticated call to the Lens server. Same error contract as
+    _lens_request — every failure mode returns {"error": "..."} so tool
+    callsites can uniformly forward errors to the MCP client without trying
+    to catch exceptions themselves."""
+    key = _read_lens_key()
+    if not key:
+        return {"error": "Lens API key not found. Start lens_server.py first."}
+    try:
+        async with httpx.AsyncClient(timeout=30) as client:
+            r = await client.request(
+                method,
+                f"{LENS_URL}{path}",
+                headers={"Authorization": f"Bearer {key}"},
+                json=json_body,
+            )
+            r.raise_for_status()
+            return r.json() if r.content else {}
+    except httpx.ConnectError:
+        return {"error": f"Lens server not reachable at {LENS_URL}. Is it running?"}
+    except httpx.HTTPStatusError as e:
+        # Distinguish "this route doesn't exist on the server" (old lens, no
+        # /libraries or /stats endpoint) from a genuine 404 like "library id
+        # not found". FastAPI's default 404 body is `{"detail": "Not Found"}`;
+        # the new lens returns a structured error for real misses.
+        if e.response.status_code == 404:
+            try:
+                body = e.response.json()
+                if body.get("detail") == "Not Found":
+                    return {"error": "unsupported_endpoint"}
+            except (json.JSONDecodeError, ValueError):
+                pass
+        # 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]
+        return {"error": f"Lens returned {e.response.status_code}: {preview}"}
+    except httpx.RequestError as e:
+        return {"error": f"Lens request failed: {e}"}
+    except (json.JSONDecodeError, ValueError) as e:
+        return {"error": f"Lens returned invalid JSON: {e}"}
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# TOOLS — Blood work data
+# ═══════════════════════════════════════════════════════════════════════
+
+@mcp.tool()
+@_instrumented("getbased_lab_context")
+async def getbased_lab_context(profile: str = "") -> str:
+    """Get a full summary of the user's blood work data, health context,
+    supplements, and goals from getbased. Use when the user asks broad
+    questions about their labs, biomarkers, or health trends.
+    Pass a profile ID to query a specific profile, or omit for the default."""
+    data = await _fetch_context(profile)
+    if "error" in data:
+        return f"Error: {data['error']}"
+    parts = []
+    if data.get("profileId"):
+        parts.append(f"Profile: {data['profileId']}")
+    if data.get("updatedAt"):
+        parts.append(f"Updated: {data['updatedAt']}")
+    parts.append(data.get("context", "No context available"))
+    return "\n\n".join(parts)
+
+
+@mcp.tool()
+@_instrumented("getbased_section")
+async def getbased_section(section: str = "", profile: str = "") -> str:
+    """Get a specific section of health data, or list all available sections.
+    Call with no section name to get the index (section names + line counts).
+    Call with a section name to get just that section's content.
+    Sections include: biometrics, hormones, lipids, hematology, biochemistry,
+    supplements, goals, genetics, context cards, etc.
+    Section names are matched by prefix.
+    Pass a profile ID to query a specific profile, or omit for the default."""
+    data = await _fetch_context(profile)
+    if "error" in data:
+        return f"Error: {data['error']}"
+    context = data.get("context", "")
+    if not context:
+        return "No context available"
+
+    sections = _parse_sections(context)
+
+    if not section:
+        lines = []
+        for name, content in sections.items():
+            count = len([l for l in content.split("\n") if l.strip()])
+            lines.append(f"  {name}  ({count} lines)")
+        return "Available sections:\n\n" + "\n".join(lines)
+
+    query = section.lower().strip()
+    match_key = None
+    for k in sections:
+        if k.lower() == query:
+            match_key = k
+            break
+    if not match_key:
+        for k in sections:
+            if k.lower().startswith(query):
+                match_key = k
+                break
+    if not match_key:
+        available = [k.split(" ")[0] for k in sections]
+        return f'Section "{section}" not found\nAvailable: {", ".join(available)}'
+
+    return f"[{match_key}]\n\n{sections[match_key]}"
+
+
+@mcp.tool()
+@_instrumented("getbased_list_profiles")
+async def getbased_list_profiles() -> str:
+    """List all available profiles in getbased."""
+    data = await _fetch_context()
+    if "error" in data:
+        return f"Error: {data['error']}"
+    profiles = data.get("profiles") or []
+    if not profiles:
+        return "No profiles found"
+    return "\n".join(
+        f"{p.get('id', '?')}  {p.get('name', 'unnamed')}" for p in profiles
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# TOOLS — Knowledge base (RAG via Lens server)
+# ═══════════════════════════════════════════════════════════════════════
+
+@mcp.tool()
+@_instrumented("knowledge_search")
+async def knowledge_search(
+    query: str,
+    n_results: int = 5,
+) -> str:
+    """Search the knowledge base for relevant passages using semantic similarity.
+
+    Searches the **currently active library** on the Lens server. If the user
+    has multiple libraries (research papers, clinical guides, personal notes),
+    list them with `knowledge_list_libraries` and switch with
+    `knowledge_activate_library` before searching.
+
+    Returns the top-K passages ranked by relevance, with source
+    attribution. Use this when the user asks about mechanisms, causal
+    relationships, or prescriptive guidance related to health topics.
+
+    Args:
+        query: Natural language search query (e.g. "folic acid MTHFR methylation")
+        n_results: Number of results to return (default 5, max 10)
+    """
+    n_results = max(1, min(10, n_results))
+    data = await _lens_request(query, top_k=n_results)
+
+    if "error" in data:
+        return f"Knowledge search error: {data['error']}"
+
+    chunks = data.get("chunks", [])[:10]  # mirror web-app MAX_CHUNKS
+    if not chunks:
+        return "No results found for that query."
+
+    output_lines = []
+    for i, chunk in enumerate(chunks):
+        text = (chunk.get("text") or "")[:4000]
+        source = (chunk.get("source") or "")[:200]
+        output_lines.append(f"[{i + 1}] {source}")
+        output_lines.append(text)
+        output_lines.append("")
+
+    return "\n".join(output_lines)
+
+
+@mcp.tool()
+@_instrumented("getbased_lens_config")
+async def getbased_lens_config() -> str:
+    """Get the Lens RAG endpoint configuration for getbased's Knowledge Base.
+    Returns the URL, API key, and recommended top_k to paste into
+    Settings → AI → Knowledge Base → External server in getbased.
+
+    Note: Treat the response as sensitive — it contains the API key in plaintext."""
+    key = _read_lens_key()
+    if not key:
+        return (
+            "Lens API key not found. Start lens_server.py first to generate one.\n"
+            f"Expected key file: {LENS_API_KEY_FILE}"
+        )
+    return (
+        f"Endpoint URL: {LENS_URL}/query\n"
+        f"API key (Bearer token): {key}\n"
+        f"Recommended top_k: 5\n\n"
+        "Paste these into getbased: Settings → AI → Knowledge Base → External server.\n"
+        "For production (non-localhost), use HTTPS via a reverse proxy."
+    )
+
+
+@mcp.tool()
+@_instrumented("knowledge_list_libraries")
+async def knowledge_list_libraries() -> str:
+    """List all knowledge base libraries on the Lens server, showing which is
+    active. Use this to discover what collections the user has (research
+    papers, clinical guides, personal notes, etc.) before searching or
+    switching between them."""
+    data = await _lens_call("GET", "/libraries")
+    if data.get("error") == "unsupported_endpoint":
+        return f"Knowledge libraries: {_UNSUPPORTED_LENS_HINT}"
+    if "error" in data:
+        return f"Knowledge libraries error: {data['error']}"
+    libs = data.get("libraries") or []
+    active = data.get("activeId", "")
+    if not libs:
+        return "No libraries found. Ingest at least one document to create the default library."
+    lines = ["Libraries:"]
+    for lib in libs:
+        lib_id = lib.get("id", "")
+        name = lib.get("name", "unnamed")
+        marker = "  (active)" if lib_id == active else ""
+        lines.append(f"  {lib_id}  {name}{marker}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+@_instrumented("knowledge_activate_library")
+async def knowledge_activate_library(library_id: str) -> str:
+    """Switch the Lens server's active library. All subsequent
+    `knowledge_search` and `knowledge_stats` calls will target this library
+    until switched again. Use `knowledge_list_libraries` first to find the ID.
+
+    Args:
+        library_id: The library's ID (not its display name). Obtained from
+            knowledge_list_libraries.
+    """
+    if not library_id:
+        return "Error: library_id is required. Call knowledge_list_libraries to find one."
+    data = await _lens_call("POST", f"/libraries/{library_id}/activate")
+    if data.get("error") == "unsupported_endpoint":
+        return f"Activate library: {_UNSUPPORTED_LENS_HINT}"
+    if "error" in data:
+        return f"Activate library error: {data['error']}"
+    libs = data.get("libraries") or []
+    active = data.get("activeId", "")
+    for lib in libs:
+        if lib.get("id") == active:
+            return f"Active library is now: {lib.get('name', active)} ({active})"
+    return f"Active library is now: {active}"
+
+
+@mcp.tool()
+@_instrumented("knowledge_stats")
+async def knowledge_stats() -> str:
+    """Get per-source chunk counts for the active knowledge base library.
+    Tells you which documents are indexed and how many excerpts each
+    contributes. Useful when diagnosing "I can't find X" — either the source
+    isn't indexed, or the relevant passages didn't score high enough."""
+    data = await _lens_call("GET", "/stats")
+    if data.get("error") == "unsupported_endpoint":
+        return f"Knowledge stats: {_UNSUPPORTED_LENS_HINT}"
+    if "error" in data:
+        return f"Knowledge stats error: {data['error']}"
+    total = data.get("total_chunks", 0)
+    docs = data.get("documents") or []
+    if not docs:
+        return f"Active library is empty (total chunks: {total})."
+    lines = [f"Total chunks: {total}", "", "Sources:"]
+    for doc in docs:
+        src = doc.get("source", "unknown")
+        chunks = doc.get("chunks", 0)
+        lines.append(f"  {chunks:>6}  {src}")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    mcp.run()