GroundedSeek

Portfolio case study: execute42 / GroundedSeek

GroundedSeek is a local-first, evidence-backed web research service. It has a FastAPI interface, a browser workbench, and a local stdio MCP server for coding Harnesses such as Codex and Claude Code.

Current release: v1.1.0. It adds versioned Research Artifacts, local Projects and history, JSON/Markdown exports, and a local-only MCP interface.

The MCP server only talks to the local API on 127.0.0.1:8000; it does not read a Harness workspace, execute shell commands, expose secrets, or create a second research queue.

Start locally

Create local configuration from backend/.env.example before starting. All entrypoints load backend/.env regardless of the directory from which they are invoked. If a trusted local proxy resolves public hosts to fake IPs, set TRUSTED_PROXY_FAKE_IP_CIDR there.

Windows PowerShell:

.\scripts\windows\bootstrap.ps1
.\backend\.venv\Scripts\python.exe -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000

Ubuntu / Debian:

bash scripts/linux/bootstrap.sh
./backend/.venv/bin/python -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000

Check the API at http://127.0.0.1:8000/health.

Use through MCP

Keep the API process running, then register the stdio server. The available tools are research_capabilities, research_start, research_status, research_result, and research_cancel. Starting research requires an explicit use_web: true argument.

Codex

Add this to ~/.codex/config.toml, substituting the absolute paths for your machine:

[mcp_servers.grounded-seek]
command = "D:\\path\\to\\GroundedSeek\\backend\\.venv\\Scripts\\python.exe"
args = ["-m", "app.mcp_server"]
cwd = "D:\\path\\to\\GroundedSeek\\backend"

On Linux, use backend/.venv/bin/python and the repository's backend directory instead. Restart Codex after updating its configuration.

Claude Code

Windows:

claude mcp add --transport stdio --scope local grounded-seek D:\path\to\GroundedSeek\scripts\windows\run_mcp_server.cmd

Linux:

claude mcp add --transport stdio --scope local grounded-seek -- /path/to/GroundedSeek/scripts/linux/run_mcp_server.sh

Run claude mcp get grounded-seek or /mcp in Claude Code to inspect the connection. The local scope keeps this registration private to your current project.

Verify MCP transport

Windows:

.\scripts\windows\mcp_smoke.ps1

Linux:

./scripts/linux/mcp_smoke.sh

Development

From backend/:

python -m pip install -e ".[test]"
python -m ruff check .
python -m pytest

Offline quality evaluation

The project-local Eval42 validation runs 15 candidate cases through the existing Run and Research Artifact API with frozen search, page, and Ollama fixtures:

cd backend
python -m evals.groundedseek --config evals/config/groundedseek.fixture.json

See backend/evals/README.md for metrics, live mode, fixture governance, and the pending owner review boundary.

Upgrade and rollback

The SQLite migration runner upgrades an existing database in place when the API starts. It preserves existing Runs, Sources, DocumentVersions, and Evidence; v1.1 adds nullable Project association only. Back up the SQLite database before an upgrade if you need to roll back the application binary. A rollback to the previous binary leaves the added Project table and nullable column unused, but does not remove research data.