getbased-agent-stack 0.2.0__tar.gz

getbased_agent_stack-0.2.0/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_agent_stack-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: getbased-agent-stack
+Version: 0.2.0
+Summary: One-command install of the full getbased agent stack — getbased-mcp + getbased-rag + getbased-dashboard
+License-Expression: GPL-3.0-only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: getbased-mcp>=0.2.2
+Requires-Dist: getbased-rag>=0.6.1
+Requires-Dist: getbased-dashboard>=0.5.0
+Provides-Extra: full
+Requires-Dist: getbased-rag[full]>=0.6.1; extra == "full"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Requires-Dist: pytest-timeout>=2.3; extra == "test"
+Dynamic: license-file
+
+# getbased-agent-stack
+
+Meta-package bundling the full [getbased](https://getbased.health) agent stack into one install: the MCP adapter, the RAG engine, the browser dashboard, a thin discovery CLI, a hardened systemd unit, and example configs for Claude Code + Hermes.
+
+Part of the [getbased-agents monorepo](https://github.com/elkimek/getbased-agents).
+
+## Install
+
+```bash
+pipx install "getbased-agent-stack[full]"
+```
+
+Pulls:
+
+- [`getbased-mcp`](https://github.com/elkimek/getbased-agents/tree/main/packages/mcp) — stdio MCP server that Claude Code / Hermes / OpenClaw spawn
+- [`getbased-rag`](https://github.com/elkimek/getbased-agents/tree/main/packages/rag) — local RAG knowledge server (FastAPI + Qdrant + MiniLM/BGE)
+- [`getbased-dashboard`](https://github.com/elkimek/getbased-agents/tree/main/packages/dashboard) — web UI for library management, MCP config generation, and agent-activity inspection
+- The `getbased-stack` discovery CLI
+- `[full]` extra: PDF/DOCX parsers + ONNX runtime for hardware-accelerated embeddings
+
+Total install: ~500 MB (the ML deps dominate). Smaller installs available — `pipx install getbased-mcp` (10 MB, agent only), `pipx install "getbased-rag[full]"` (RAG only), `pipx install getbased-dashboard` (UI + MCP; pulls rag if you want the Knowledge tab working).
+
+## Quickstart
+
+```bash
+# 1. Start the RAG server — local Qdrant DB + MiniLM embedder
+lens serve                               # blocks; serves on 127.0.0.1:8322
+lens key                                 # prints the bearer token
+
+# 2. Start the dashboard in another terminal
+getbased-dashboard serve                 # serves on 127.0.0.1:8323
+
+# 3. Open http://127.0.0.1:8323 in your browser, paste the lens key
+#    Create libraries, drag-drop files to ingest (live chunks/sec pill),
+#    run the MCP Test button to verify your agent path
+
+# 4. Wire the MCP into your AI client
+#    The dashboard's MCP tab generates paste-ready config blocks for
+#    Claude Desktop, Claude Code, Cursor, Cline, and Hermes.
+```
+
+Both the RAG server and the getbased PWA talk to the same `lens` instance — point the PWA at `http://127.0.0.1:8322` under **Settings → AI → Knowledge Base → External server** and the same corpus feeds the browser chat, the dashboard, and any MCP-connected agent.
+
+## Running as a systemd service
+
+```bash
+cp systemd/getbased-rag.service ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now getbased-rag
+```
+
+The unit is hardened (`ProtectSystem=strict`, `NoNewPrivileges`, `RestrictAddressFamilies`, etc.); run `systemd-analyze security getbased-rag` to see the score.
+
+## Architecture
+
+```
+Claude Code / Hermes / OpenClaw          Browser
+        │ MCP (stdio)                       │ HTTP
+        ▼                                   ▼
+  getbased-mcp                       getbased-dashboard   (localhost:8323)
+   │        │                          │             │
+   │ HTTP   │ HTTP                     │ proxies     │ spawns stdio for Test
+   ▼        ▼                          ▼             ▼
+sync GW   getbased-rag  ◀──────────────┘       getbased-mcp
+          (localhost:8322)
+```
+
+The MCP holds no persistent state; it's a thin translator between MCP tool calls and two HTTP backends:
+
+- `sync.getbased.health/api/context` — read-only lab summary pushed by your PWA session (via Agent Access token)
+- `localhost:8322` (getbased-rag) — your local research library
+
+The dashboard is likewise stateless — it proxies rag for Knowledge operations, imports `getbased_mcp` to introspect env/config, and spawns the MCP binary on demand to verify it works.
+
+## Version compatibility
+
+| Stack | mcp | rag | dashboard | Protocol |
+|---|---|---|---|---|
+| 0.1.x | ≥0.2.0 | ≥0.1.0 | — | v1 (multi-library) |
+| 0.2.x | ≥0.2.2 | ≥0.6.0 | ≥0.5.0 | v1 (+ streaming ingest, per-library models) |
+
+Bump the meta's major when sibling protocols break; bump siblings freely for normal features.
+
+## Development
+
+This package is the meta — the interesting code lives in sibling packages. See the [monorepo root README](https://github.com/elkimek/getbased-agents#development) for workspace setup.
+
+The integration test (`tests/test_integration.py`) spins up `lens serve` in a subprocess, ingests a fixture, and exercises every MCP tool round-trip. Catches drift between the siblings the way the v1.21 catch-up drift would have been caught if the test existed then. The dashboard has its own test suite (`cd packages/dashboard && uv run pytest`) covering the proxy, modal logic, stdio probe, and activity-log handling.
+
+## Related docs
+
+- [packages/stack/CONTRIBUTING.md](CONTRIBUTING.md) — when to bump the meta vs a sibling
+- [packages/stack/SECURITY.md](SECURITY.md) — threat model, scope, sibling pointers
+
+## Licence
+
+GPL-3.0-only, matching the siblings.

getbased_agent_stack-0.2.0/README.md

@@ -0,0 +1,97 @@
+# getbased-agent-stack
+
+Meta-package bundling the full [getbased](https://getbased.health) agent stack into one install: the MCP adapter, the RAG engine, the browser dashboard, a thin discovery CLI, a hardened systemd unit, and example configs for Claude Code + Hermes.
+
+Part of the [getbased-agents monorepo](https://github.com/elkimek/getbased-agents).
+
+## Install
+
+```bash
+pipx install "getbased-agent-stack[full]"
+```
+
+Pulls:
+
+- [`getbased-mcp`](https://github.com/elkimek/getbased-agents/tree/main/packages/mcp) — stdio MCP server that Claude Code / Hermes / OpenClaw spawn
+- [`getbased-rag`](https://github.com/elkimek/getbased-agents/tree/main/packages/rag) — local RAG knowledge server (FastAPI + Qdrant + MiniLM/BGE)
+- [`getbased-dashboard`](https://github.com/elkimek/getbased-agents/tree/main/packages/dashboard) — web UI for library management, MCP config generation, and agent-activity inspection
+- The `getbased-stack` discovery CLI
+- `[full]` extra: PDF/DOCX parsers + ONNX runtime for hardware-accelerated embeddings
+
+Total install: ~500 MB (the ML deps dominate). Smaller installs available — `pipx install getbased-mcp` (10 MB, agent only), `pipx install "getbased-rag[full]"` (RAG only), `pipx install getbased-dashboard` (UI + MCP; pulls rag if you want the Knowledge tab working).
+
+## Quickstart
+
+```bash
+# 1. Start the RAG server — local Qdrant DB + MiniLM embedder
+lens serve                               # blocks; serves on 127.0.0.1:8322
+lens key                                 # prints the bearer token
+
+# 2. Start the dashboard in another terminal
+getbased-dashboard serve                 # serves on 127.0.0.1:8323
+
+# 3. Open http://127.0.0.1:8323 in your browser, paste the lens key
+#    Create libraries, drag-drop files to ingest (live chunks/sec pill),
+#    run the MCP Test button to verify your agent path
+
+# 4. Wire the MCP into your AI client
+#    The dashboard's MCP tab generates paste-ready config blocks for
+#    Claude Desktop, Claude Code, Cursor, Cline, and Hermes.
+```
+
+Both the RAG server and the getbased PWA talk to the same `lens` instance — point the PWA at `http://127.0.0.1:8322` under **Settings → AI → Knowledge Base → External server** and the same corpus feeds the browser chat, the dashboard, and any MCP-connected agent.
+
+## Running as a systemd service
+
+```bash
+cp systemd/getbased-rag.service ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now getbased-rag
+```
+
+The unit is hardened (`ProtectSystem=strict`, `NoNewPrivileges`, `RestrictAddressFamilies`, etc.); run `systemd-analyze security getbased-rag` to see the score.
+
+## Architecture
+
+```
+Claude Code / Hermes / OpenClaw          Browser
+        │ MCP (stdio)                       │ HTTP
+        ▼                                   ▼
+  getbased-mcp                       getbased-dashboard   (localhost:8323)
+   │        │                          │             │
+   │ HTTP   │ HTTP                     │ proxies     │ spawns stdio for Test
+   ▼        ▼                          ▼             ▼
+sync GW   getbased-rag  ◀──────────────┘       getbased-mcp
+          (localhost:8322)
+```
+
+The MCP holds no persistent state; it's a thin translator between MCP tool calls and two HTTP backends:
+
+- `sync.getbased.health/api/context` — read-only lab summary pushed by your PWA session (via Agent Access token)
+- `localhost:8322` (getbased-rag) — your local research library
+
+The dashboard is likewise stateless — it proxies rag for Knowledge operations, imports `getbased_mcp` to introspect env/config, and spawns the MCP binary on demand to verify it works.
+
+## Version compatibility
+
+| Stack | mcp | rag | dashboard | Protocol |
+|---|---|---|---|---|
+| 0.1.x | ≥0.2.0 | ≥0.1.0 | — | v1 (multi-library) |
+| 0.2.x | ≥0.2.2 | ≥0.6.0 | ≥0.5.0 | v1 (+ streaming ingest, per-library models) |
+
+Bump the meta's major when sibling protocols break; bump siblings freely for normal features.
+
+## Development
+
+This package is the meta — the interesting code lives in sibling packages. See the [monorepo root README](https://github.com/elkimek/getbased-agents#development) for workspace setup.
+
+The integration test (`tests/test_integration.py`) spins up `lens serve` in a subprocess, ingests a fixture, and exercises every MCP tool round-trip. Catches drift between the siblings the way the v1.21 catch-up drift would have been caught if the test existed then. The dashboard has its own test suite (`cd packages/dashboard && uv run pytest`) covering the proxy, modal logic, stdio probe, and activity-log handling.
+
+## Related docs
+
+- [packages/stack/CONTRIBUTING.md](CONTRIBUTING.md) — when to bump the meta vs a sibling
+- [packages/stack/SECURITY.md](SECURITY.md) — threat model, scope, sibling pointers
+
+## Licence
+
+GPL-3.0-only, matching the siblings.

getbased_agent_stack-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "getbased-agent-stack"
+version = "0.2.0"
+description = "One-command install of the full getbased agent stack — getbased-mcp + getbased-rag + getbased-dashboard"
+readme = "README.md"
+license = "GPL-3.0-only"
+requires-python = ">=3.10"
+# Pulls every sibling package. Bump this meta when a sibling protocol
+# bump requires coordinated release.
+dependencies = [
+    "getbased-mcp>=0.2.2",
+    "getbased-rag>=0.6.1",
+    "getbased-dashboard>=0.5.0",
+]
+
+[project.optional-dependencies]
+# With the full parser + ONNX stack on the rag side.
+full = ["getbased-rag[full]>=0.6.1"]
+# For contributors running the integration test harness.
+test = ["pytest>=8.0", "httpx>=0.27", "pytest-timeout>=2.3"]
+
+# In the monorepo (elkimek/getbased-agents), the workspace-root pyproject
+# overrides these with `workspace = true` sources. From PyPI, the
+# normal `dependencies` block above resolves remotely as expected.
+
+[project.scripts]
+# Convenience launcher. Delegates to the real lens CLI so users don't
+# have to remember which package provides which binary.
+getbased-stack = "getbased_agent_stack.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"

getbased_agent_stack-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

getbased_agent_stack-0.2.0/src/getbased_agent_stack/__init__.py

@@ -0,0 +1,8 @@
+"""getbased-agent-stack — meta-package binding getbased-mcp + getbased-rag.
+
+This package contains no tools of its own; it's a convenience installer
+plus a small CLI that proxies to the real binaries. Everything
+interesting lives in the sibling repos.
+"""
+
+__version__ = "0.1.0"

getbased_agent_stack-0.2.0/src/getbased_agent_stack/cli.py

@@ -0,0 +1,72 @@
+"""Thin CLI wrapper that proxies to getbased-rag's `lens` and getbased-mcp's
+runner. Kept minimal so users can still call `lens` / `getbased-mcp`
+directly — this exists only for discoverability ("what commands do I have
+after `pipx install getbased-agent-stack`?")."""
+from __future__ import annotations
+
+import sys
+
+
+HELP = """\
+getbased-stack — thin wrapper over the two binaries installed by this package.
+
+Real commands (use directly, they're also on your PATH):
+  lens                      — getbased-rag CLI (serve, ingest, stats, ...)
+  getbased-mcp              — getbased-mcp stdio server (spawned by agents)
+
+This wrapper only exists for discoverability:
+  getbased-stack serve      → lens serve
+  getbased-stack info       → lens info
+  getbased-stack version    → print the installed package versions
+
+Quick start:
+  1. `getbased-stack serve &`           start the RAG server
+  2. `lens ingest /path/to/papers`      index your docs
+  3. configure your MCP agent (Claude Code, Hermes) — see the README
+"""
+
+
+def main() -> int:
+    import getbased_agent_stack
+
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(HELP)
+        return 0
+
+    cmd, rest = argv[0], argv[1:]
+    if cmd == "version":
+        try:
+            import getbased_mcp  # noqa: F401
+            import lens  # noqa: F401
+            import importlib.metadata as md
+            print(f"getbased-agent-stack {getbased_agent_stack.__version__}")
+            try:
+                print(f"  getbased-mcp {md.version('getbased-mcp')}")
+            except md.PackageNotFoundError:
+                print("  getbased-mcp (not installed)")
+            try:
+                print(f"  getbased-rag {md.version('getbased-rag')}")
+            except md.PackageNotFoundError:
+                print("  getbased-rag (not installed)")
+            return 0
+        except ImportError as e:
+            print(f"Missing dependency: {e}", file=sys.stderr)
+            return 1
+
+    # Delegate to the lens CLI for everything else.
+    try:
+        from lens.cli import app as lens_app
+
+        sys.argv = ["lens"] + argv
+        lens_app()
+        return 0
+    except SystemExit as e:
+        return int(e.code or 0)
+    except ImportError:
+        print("getbased-rag not installed — install with `pipx install getbased-agent-stack[full]`", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

getbased_agent_stack-0.2.0/src/getbased_agent_stack.egg-info/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: getbased-agent-stack
+Version: 0.2.0
+Summary: One-command install of the full getbased agent stack — getbased-mcp + getbased-rag + getbased-dashboard
+License-Expression: GPL-3.0-only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: getbased-mcp>=0.2.2
+Requires-Dist: getbased-rag>=0.6.1
+Requires-Dist: getbased-dashboard>=0.5.0
+Provides-Extra: full
+Requires-Dist: getbased-rag[full]>=0.6.1; extra == "full"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Requires-Dist: pytest-timeout>=2.3; extra == "test"
+Dynamic: license-file
+
+# getbased-agent-stack
+
+Meta-package bundling the full [getbased](https://getbased.health) agent stack into one install: the MCP adapter, the RAG engine, the browser dashboard, a thin discovery CLI, a hardened systemd unit, and example configs for Claude Code + Hermes.
+
+Part of the [getbased-agents monorepo](https://github.com/elkimek/getbased-agents).
+
+## Install
+
+```bash
+pipx install "getbased-agent-stack[full]"
+```
+
+Pulls:
+
+- [`getbased-mcp`](https://github.com/elkimek/getbased-agents/tree/main/packages/mcp) — stdio MCP server that Claude Code / Hermes / OpenClaw spawn
+- [`getbased-rag`](https://github.com/elkimek/getbased-agents/tree/main/packages/rag) — local RAG knowledge server (FastAPI + Qdrant + MiniLM/BGE)
+- [`getbased-dashboard`](https://github.com/elkimek/getbased-agents/tree/main/packages/dashboard) — web UI for library management, MCP config generation, and agent-activity inspection
+- The `getbased-stack` discovery CLI
+- `[full]` extra: PDF/DOCX parsers + ONNX runtime for hardware-accelerated embeddings
+
+Total install: ~500 MB (the ML deps dominate). Smaller installs available — `pipx install getbased-mcp` (10 MB, agent only), `pipx install "getbased-rag[full]"` (RAG only), `pipx install getbased-dashboard` (UI + MCP; pulls rag if you want the Knowledge tab working).
+
+## Quickstart
+
+```bash
+# 1. Start the RAG server — local Qdrant DB + MiniLM embedder
+lens serve                               # blocks; serves on 127.0.0.1:8322
+lens key                                 # prints the bearer token
+
+# 2. Start the dashboard in another terminal
+getbased-dashboard serve                 # serves on 127.0.0.1:8323
+
+# 3. Open http://127.0.0.1:8323 in your browser, paste the lens key
+#    Create libraries, drag-drop files to ingest (live chunks/sec pill),
+#    run the MCP Test button to verify your agent path
+
+# 4. Wire the MCP into your AI client
+#    The dashboard's MCP tab generates paste-ready config blocks for
+#    Claude Desktop, Claude Code, Cursor, Cline, and Hermes.
+```
+
+Both the RAG server and the getbased PWA talk to the same `lens` instance — point the PWA at `http://127.0.0.1:8322` under **Settings → AI → Knowledge Base → External server** and the same corpus feeds the browser chat, the dashboard, and any MCP-connected agent.
+
+## Running as a systemd service
+
+```bash
+cp systemd/getbased-rag.service ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now getbased-rag
+```
+
+The unit is hardened (`ProtectSystem=strict`, `NoNewPrivileges`, `RestrictAddressFamilies`, etc.); run `systemd-analyze security getbased-rag` to see the score.
+
+## Architecture
+
+```
+Claude Code / Hermes / OpenClaw          Browser
+        │ MCP (stdio)                       │ HTTP
+        ▼                                   ▼
+  getbased-mcp                       getbased-dashboard   (localhost:8323)
+   │        │                          │             │
+   │ HTTP   │ HTTP                     │ proxies     │ spawns stdio for Test
+   ▼        ▼                          ▼             ▼
+sync GW   getbased-rag  ◀──────────────┘       getbased-mcp
+          (localhost:8322)
+```
+
+The MCP holds no persistent state; it's a thin translator between MCP tool calls and two HTTP backends:
+
+- `sync.getbased.health/api/context` — read-only lab summary pushed by your PWA session (via Agent Access token)
+- `localhost:8322` (getbased-rag) — your local research library
+
+The dashboard is likewise stateless — it proxies rag for Knowledge operations, imports `getbased_mcp` to introspect env/config, and spawns the MCP binary on demand to verify it works.
+
+## Version compatibility
+
+| Stack | mcp | rag | dashboard | Protocol |
+|---|---|---|---|---|
+| 0.1.x | ≥0.2.0 | ≥0.1.0 | — | v1 (multi-library) |
+| 0.2.x | ≥0.2.2 | ≥0.6.0 | ≥0.5.0 | v1 (+ streaming ingest, per-library models) |
+
+Bump the meta's major when sibling protocols break; bump siblings freely for normal features.
+
+## Development
+
+This package is the meta — the interesting code lives in sibling packages. See the [monorepo root README](https://github.com/elkimek/getbased-agents#development) for workspace setup.
+
+The integration test (`tests/test_integration.py`) spins up `lens serve` in a subprocess, ingests a fixture, and exercises every MCP tool round-trip. Catches drift between the siblings the way the v1.21 catch-up drift would have been caught if the test existed then. The dashboard has its own test suite (`cd packages/dashboard && uv run pytest`) covering the proxy, modal logic, stdio probe, and activity-log handling.
+
+## Related docs
+
+- [packages/stack/CONTRIBUTING.md](CONTRIBUTING.md) — when to bump the meta vs a sibling
+- [packages/stack/SECURITY.md](SECURITY.md) — threat model, scope, sibling pointers
+
+## Licence
+
+GPL-3.0-only, matching the siblings.

getbased_agent_stack-0.2.0/src/getbased_agent_stack.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/getbased_agent_stack/__init__.py
+src/getbased_agent_stack/cli.py
+src/getbased_agent_stack.egg-info/PKG-INFO
+src/getbased_agent_stack.egg-info/SOURCES.txt
+src/getbased_agent_stack.egg-info/dependency_links.txt
+src/getbased_agent_stack.egg-info/entry_points.txt
+src/getbased_agent_stack.egg-info/requires.txt
+src/getbased_agent_stack.egg-info/top_level.txt
+tests/test_integration.py

getbased_agent_stack-0.2.0/src/getbased_agent_stack.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

getbased_agent_stack-0.2.0/src/getbased_agent_stack.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+getbased-stack = getbased_agent_stack.cli:main

getbased_agent_stack-0.2.0/src/getbased_agent_stack.egg-info/requires.txt

@@ -0,0 +1,11 @@
+getbased-mcp>=0.2.2
+getbased-rag>=0.6.1
+getbased-dashboard>=0.5.0
+
+[full]
+getbased-rag[full]>=0.6.1
+
+[test]
+pytest>=8.0
+httpx>=0.27
+pytest-timeout>=2.3

getbased_agent_stack-0.2.0/src/getbased_agent_stack.egg-info/top_level.txt

@@ -0,0 +1 @@
+getbased_agent_stack

getbased_agent_stack-0.2.0/tests/test_integration.py

@@ -0,0 +1,223 @@
+"""End-to-end integration test — real RAG subprocess + real MCP tool calls.
+
+Each sibling repo has its own hermetic unit tests (mocked HTTP or Qdrant in
+tmp dir). This suite exists because neither of those catches protocol drift
+between the two: the MCP tests only verify the MCP side, and the RAG tests
+only verify the RAG side. Here we stand up an actual `lens serve` process,
+read its generated API key, and call every MCP tool against it through the
+normal function entry points.
+
+Runs in CI via `pytest`. Skips cleanly if either package isn't installed
+(keeps the test module importable even in a partial install).
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import socket
+import subprocess
+import time
+from pathlib import Path
+from typing import Iterator
+
+import pytest
+
+
+# ── Availability guards — skip cleanly if the stack isn't installed ──
+
+def _has(module: str) -> bool:
+    try:
+        __import__(module)
+        return True
+    except ImportError:
+        return False
+
+
+pytestmark = pytest.mark.skipif(
+    not (_has("lens") and _has("getbased_mcp")),
+    reason="integration test requires both getbased-rag and getbased-mcp installed",
+)
+
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _wait_http_ready(url: str, timeout: float = 60.0) -> None:
+    """Poll until the server answers, or fail the test. The first call takes
+    a few seconds because the embedder model downloads on cold start."""
+    import urllib.error
+    import urllib.request
+
+    deadline = time.monotonic() + timeout
+    last_err: Exception | None = None
+    while time.monotonic() < deadline:
+        try:
+            with urllib.request.urlopen(url, timeout=2) as resp:
+                if resp.status == 200:
+                    return
+        except (urllib.error.URLError, ConnectionError, TimeoutError) as e:
+            last_err = e
+        time.sleep(0.5)
+    raise RuntimeError(f"server at {url} never came up: {last_err}")
+
+
+# ── Fixtures ─────────────────────────────────────────────────────────
+
+def _seed_via_cli(data_dir: Path) -> Path:
+    """Write a fixture file and run `lens ingest` against it. Must run
+    BEFORE `lens serve` starts — Qdrant local storage is exclusive-locked
+    by whichever process touches it first, so server+ingest can't share
+    a data dir at the same time."""
+    fixture_dir = Path(__file__).parent / "fixtures"
+    fixture_dir.mkdir(parents=True, exist_ok=True)
+    (fixture_dir / "vitamin-d.md").write_text(
+        "Vitamin D is a secosteroid hormone synthesised in skin when UVB "
+        "hits 7-dehydrocholesterol. " + "filler filler filler " * 20
+    )
+    env = {
+        **os.environ,
+        "LENS_DATA_DIR": str(data_dir),
+        "LENS_SIMILARITY_FLOOR": "0.0",
+    }
+    r = subprocess.run(
+        ["lens", "ingest", str(fixture_dir)],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    assert r.returncode == 0, f"ingest failed:\nstdout: {r.stdout}\nstderr: {r.stderr}"
+    return fixture_dir
+
+
+@pytest.fixture(scope="module")
+def seeded_lens(tmp_path_factory) -> Iterator[dict]:
+    """Seed a fresh tmp data dir via `lens ingest`, THEN start `lens serve`
+    against the same dir. The server picks up the already-ingested chunks
+    on first library access. Yields {url, key_file, data_dir}."""
+    data_dir = tmp_path_factory.mktemp("lens-data")
+    _seed_via_cli(data_dir)
+
+    port = _free_port()
+    env = {
+        **os.environ,
+        "LENS_DATA_DIR": str(data_dir),
+        "LENS_HOST": "127.0.0.1",
+        "LENS_PORT": str(port),
+        "LENS_SIMILARITY_FLOOR": "0.0",
+    }
+    proc = subprocess.Popen(
+        ["lens", "serve"],
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    try:
+        _wait_http_ready(f"http://127.0.0.1:{port}/health", timeout=90)
+        yield {
+            "url": f"http://127.0.0.1:{port}",
+            "key_file": data_dir / "api_key",
+            "data_dir": data_dir,
+        }
+    finally:
+        proc.terminate()
+        with contextlib.suppress(subprocess.TimeoutExpired):
+            proc.wait(timeout=5)
+        if proc.returncode is None:
+            proc.kill()
+
+
+@pytest.fixture
+def mcp_env(seeded_lens: dict, monkeypatch: pytest.MonkeyPatch):
+    """Reload getbased_mcp with env vars pointing at the subprocess server.
+    Module-level globals pick up LENS_URL / LENS_API_KEY_FILE at import time,
+    so we need a reload after monkeypatching."""
+    import importlib
+
+    import getbased_mcp
+
+    monkeypatch.setenv("LENS_URL", seeded_lens["url"])
+    monkeypatch.setenv("LENS_API_KEY_FILE", str(seeded_lens["key_file"]))
+    # No gateway token — skip blood-work tools. We're only testing the
+    # knowledge-base end of the protocol here.
+    monkeypatch.setenv("GETBASED_TOKEN", "")
+    importlib.reload(getbased_mcp)
+    return getbased_mcp
+
+
+# ── Tests ────────────────────────────────────────────────────────────
+
+@pytest.mark.timeout(180)
+def test_full_knowledge_tool_chain(mcp_env) -> None:
+    """Run every knowledge-* MCP tool against the real Lens and verify the
+    round-trip produces sensible output. This is the integration test that
+    would have caught the original 'MCP is one version behind RAG' drift."""
+
+    async def run() -> None:
+        # 1. Discover the active library
+        list_out = await mcp_env.knowledge_list_libraries()
+        assert "Libraries:" in list_out
+        assert "(active)" in list_out
+
+        # 2. Inspect its stats — should reflect the ingested document
+        stats_out = await mcp_env.knowledge_stats()
+        assert "Total chunks:" in stats_out
+        assert "vitamin-d.md" in stats_out
+
+        # 3. Search for something the seeded document contains
+        search_out = await mcp_env.knowledge_search(query="vitamin D secosteroid hormone", n_results=3)
+        assert "[1]" in search_out
+        assert "vitamin-d.md" in search_out
+
+        # 4. Config tool returns a paste-ready config
+        config_out = await mcp_env.getbased_lens_config()
+        assert mcp_env.LENS_URL in config_out
+        assert "External server" in config_out
+
+        # 5. Create a second library, activate it, verify switch took effect
+        import httpx
+
+        key = mcp_env._read_lens_key()
+        async with httpx.AsyncClient(timeout=10) as client:
+            r = await client.post(
+                f"{mcp_env.LENS_URL}/libraries",
+                headers={"Authorization": f"Bearer {key}"},
+                json={"name": "Secondary"},
+            )
+            r.raise_for_status()
+            new_id = r.json()["library"]["id"]
+
+        activate_out = await mcp_env.knowledge_activate_library(library_id=new_id)
+        assert "Active library is now" in activate_out
+        assert "Secondary" in activate_out
+
+        # Stats on the new library: empty
+        new_stats = await mcp_env.knowledge_stats()
+        assert "Active library is empty" in new_stats
+
+    asyncio.run(run())
+
+
+@pytest.mark.timeout(30)
+def test_error_surfacing_when_lens_unreachable(mcp_env, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Point MCP at a port nothing is listening on; tools should surface a
+    friendly 'not reachable' message, not raise."""
+    import importlib
+
+    import getbased_mcp
+
+    monkeypatch.setenv("LENS_URL", "http://127.0.0.1:1")  # port 1 is privileged + closed
+    importlib.reload(getbased_mcp)
+
+    async def run() -> None:
+        out = await getbased_mcp.knowledge_search(query="anything")
+        assert "Knowledge search error" in out
+        assert "not reachable" in out
+
+    asyncio.run(run())