🔌 MCP Agent Toolkit

A production-shaped Model Context Protocol system in Python — a real MCP server exposing four guarded tools, an agent that discovers and calls them at runtime, a versioned Prompt Registry whose promotions are gated by live A/B evaluation, and a console that streams every step. Quality is measured, not claimed: a dataset, deterministic checks, and an independent LLM-as-judge scorecard.

📌 What this is

A production-shaped MCP reference system built with the official Python SDK, FastAPI and React. An MCP server exposes exactly four tools — web_search, db_query, read_file, write_file — each behind enforceable guardrails. An agent client spawns that server over stdio, discovers the tools at runtime with tools/list, converts them to OpenAI function definitions and runs a plain, bounded tool-calling loop. There is no LangChain and no LangGraph on purpose: the point of MCP is that the tools work with any client.

On top of that sits the part most agent demos skip. The system prompt and the judge rubric are versioned YAML artifacts in a Prompt Registry; a new version only becomes active after a live A/B evaluation passes a gate (or a human overrides it with a reason that is written to a hash-chained audit log). Every answer is graded by a 24-question evaluation harness — deterministic checks plus a judge running on a different model than the agent — and the result is a committed scorecard, not a claim.

This is engineered as a portfolio-grade, production-shaped system: strict typing, 517 offline tests, Playwright e2e, a non-root Docker image and a CI pipeline with secret scanning. It is not claimed to be production-proven (see Known limitations).

Related MCP server: MCP Tool Server

💡 Why this matters — for your project, or for a technical reviewer

• 🔌 A real MCP server, not a wrapper. Official SDK, stdio as the canonical transport, Streamable HTTP opt-in (loopback + bearer token), honest tool annotations, outputSchema, resources and a prompt template. Any MCP client — Claude Desktop included — can drive it.

• 🔎 Runtime tool discovery. The client never hardcodes a schema: tools/list becomes the model's function list on every run. Remove a tool from the server and the agent adapts on its next run.

• 🛡️ Guardrails that fail loudly. Every call passes a rate limit, a path sandbox or SQL guard, and an output sanitizer. Rejections are typed (forbidden, rate_limited, too_large…), counted in metrics and fed back to the model — never a silent empty result.

• 🧱 Defense in depth on the data path. db_query is read-only twice: a single-SELECT statement guard and a mode=ro + PRAGMA query_only connection. File tools resolve through a lexical and canonical sandbox that also stops symlink and junction escapes.

• 🔁 Bounded autonomy. The loop ends with answer, iteration_limit or budget_limit. RUN_BUDGET_USD is a hard pre-call gate; unknown model prices stay null instead of a fabricated $0.

• 🧬 Prompts as deployable artifacts. Candidate → live A/B → promote or roll back, with exactly one promoted version per prompt enforced on disk and every mutation hash-chained. Real history: agent_system v2 was blocked by the gate; v3 and v4 were promoted by live evidence.

• 📊 Measured quality. Live scorecard (dataset v1.2.0, 24 questions, agent gpt-4o-mini, judge gpt-4o): task success 4.79/5, grounding 4.83/5, adversarial resistance 13/13, citations 100 % — and it did not pass the first time; the fix went through the same registry.

• 🔭 Observable. Redacting structlog JSON on stderr (stdout stays pure protocol), request-id correlation client → server, Prometheus metrics, and per-run token / cost / latency telemetry.

• 🧪 CI green with zero secrets. 517 backend tests (92.98 % branch coverage), 54 Playwright e2e, 55 Vitest, mypy --strict, gitleaks and pip-audit — all offline through a deterministic StubLLM.

🧠 Why MCP — and Why No Agent Framework?

The design choices below are recorded as ADRs in docs/DECISIONS.md, each with the alternative that was rejected:

🏗️ Architecture

System overview

graph TD
    USER(["User"]) --> UI["React console<br/>Vite · TypeScript · Tailwind"]
    USER --> CLI["mcp-toolkit-agent<br/>CLI"]
    UI -- "POST /api/chat<br/>GET /api/chat/stream (SSE)" --> API["FastAPI web adapter<br/>one MCP child per process"]

    API --> LOOP
    CLI --> LOOP

    subgraph CLIENT["Agent client"]
        LOOP["Bounded agent loop<br/>answer · iteration_limit · budget_limit"]
        LOOP <--> LLM["LLM adapter<br/>OpenAI · StubLLM"]
        LOOP --> MCPC["MCP client<br/>tools/list discovery"]
    end

    REG[("Prompt Registry<br/>vN.yaml + audit chain")] -- "promoted prompt<br/>resolved per run" --> LOOP

    MCPC -- "stdio · JSON-RPC" --> SRV

    subgraph SERVER["MCP server (child process)"]
        SRV["MCPServer"] --> GI["guarded_invoke"]
        GI --> RL["rate limit<br/>per tool + session"]
        RL --> H["tool handler"]
        H --> SAN["sanitizer +<br/>typed result envelope"]
    end

    H --> WS["web_search"] --> NET(["Tavily · DuckDuckGo · stub"])
    H --> DBQ["db_query"] --> DB[("demo.db<br/>read-only")]
    H --> FS["read_file · write_file"] --> SB["path sandbox"] --> FSYS[("sandbox folder")]

Life of one question

sequenceDiagram
    autonumber
    participant B as Browser
    participant W as FastAPI adapter
    participant A as Agent loop
    participant L as LLM
    participant C as MCP client
    participant S as MCP server
    B->>W: POST /api/chat {question}
    W-->>B: 201 {runId}
    B->>W: GET /api/chat/stream?runId=…
    W->>A: run_agent(question, promoted prompt)
    loop until answer · iteration_limit · budget_limit
        A->>L: messages + discovered tools
        L-->>A: tool call(s) or final text
        A-->>B: SSE tool_call
        A->>C: call(tool, args, requestId)
        C->>S: tools/call (stdio, _meta.requestId)
        S->>S: rate limit → guard → handler → sanitize
        S-->>C: typed envelope (ok | error code)
        C-->>A: outcome (never raises)
        A-->>B: SSE tool_result
    end
    A-->>B: SSE final {answer, terminatedBy, telemetry, prompt version}

The guardrail chain (every tool call)

graph TD
    CALL["tools/call"] --> RID["extract request id"]
    RID --> RATE{"rate limit<br/>tool + session"}
    RATE -- "over limit" --> E1["rate_limited"]
    RATE -- "ok" --> TOOL{"which tool?"}
    TOOL -- "read_file · write_file" --> PS["path sandbox<br/>lexical + canonical"]
    TOOL -- "db_query" --> SG["SQL guard → read-only connection"]
    TOOL -- "web_search" --> PRV["search provider"]
    PS -- "escape" --> E2["forbidden"]
    SG -- "not a single SELECT" --> E3["invalid_input / forbidden"]
    PS --> OUT["raw output"]
    SG --> OUT
    PRV --> OUT
    OUT --> SAN2["strip control · bidi · zero-width<br/>cap at MAX_TOOL_OUTPUT_CHARS"]
    SAN2 --> OK["status ok + structured content"]
    E1 --> ENV["isError = true<br/>typed envelope"]
    E2 --> ENV
    E3 --> ENV

Three ways to run it

📋 Sample Interaction Preview

Real request → response, captured from a running instance of this repository (offline StubLLM, so costUsd is null; a live run fills in tokens and cost):

curl -s -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"question": "Which reports cover security, and what is the newest one?"}'
# -> 201 {"runId": "a413d6ac-2cd9-4d1a-a3e0-8a3aea64dec5"}

curl -N "http://localhost:3000/api/chat/stream?runId=a413d6ac-2cd9-4d1a-a3e0-8a3aea64dec5"

event: tool_call
data: {"type":"tool_call","iteration":1,"tool":"db_query","args":{"query":"SELECT id, title, topic, author, published_at FROM reports ORDER BY published_at DESC LIMIT 5"}, ...}

event: tool_result
data: {"type":"tool_result","iteration":1,"tool":"db_query","ok":true,"durationMs":107,"preview":"{ \"status\": \"ok\", \"data\": { \"rows\": [ ... ] } }", ...}

event: answer_delta
data: {"type":"answer_delta","iteration":2,"content":"Stub answer: gathered evidence "}

event: final
data: {"type":"final","iterations":2,"toolCalls":1,"terminatedBy":"answer","durationMs":108,
       "usage":{"promptTokens":1109,"completionTokens":63,"totalTokens":1172},"costUsd":null,
       "promptVersion":{"name":"agent_system","version":4,"sha256":"e2089a23b25b…"}, ...}

A blocked request — the guardrail rejects it with a typed error, the agent reports it, and nothing unsafe runs:

event: tool_result
data: {"type":"tool_result","tool":"read_file","ok":false,
       "result":{"status":"error","code":"forbidden",
                 "message":"Path escapes the sandbox root: ../../etc/passwd"}}

event: final
data: {"type":"final","content":"… the requested operation was rejected by the server's guardrails; nothing unsafe was executed. …","terminatedBy":"answer"}

Validation is enforced before any LLM call: a question shorter than 3 characters returns 400 {"error":"Question must be at least 3 characters."}.

📊 Evaluation-Driven Development (EDD)

Quality regresses like a failing test. evaluation/run_eval.py drives the dataset through the real agent (live mode: real OpenAI + real MCP transport), runs deterministic checks, then an LLM-as-judge — own rubric prompt, model configurable via JUDGE_MODEL_NAME (the agent's model by default) — scores each answer.

Project Goal & Definition of Success

Thresholds live in one place — evaluation/scorecard.py — and a failed gate sets passed: false: quality is treated as a failing test, not a statistic.

Latest committed scorecard (evaluation/scorecard.json, live, agent gpt-4o-mini graded by a gpt-4o judge, dataset v1.2.0 — 24 questions, agent_system@v4 + judge_rubric@v2):

The gate passes — and it did not pass the first time. The initial v1.2.0 run (on agent_system@v3 + judge_rubric@v1) failed grounding at 3.58/5 for two distinct reasons, and both were fixed through the registry instead of being left as a documented failure:

• judge_rubric@v2 — the v1 rubric scored clean refusals grounding=1 because there were no claims to verify; v2 scores refusals on honesty and policy adherence instead (promoted with an audited override — the A/B gate measures the agent, not the judge).

• agent_system@v4 — v3 retried variants of a typed guardrail rejection (ad-11, an oversize write_file) instead of converging; v4 states the enforced limit and finishes. It beat v3 on a live A/B run (grounding 4.63 → 4.75, task 4.54 → 4.67, adversarial 13/13 both sides) and was promoted through the gate.

Remaining honest noise: ad-11 (the oversize write_file) was judged clean in this run — one small write plus an honest report of the limit — but st-02 still fabricated MCP background details the tool output did not support, and the gpt-4o judge scored it harsher (task=2, grounding=2) than the same-model judge had.

Reproduce the Evaluation Scorecard

Offline smoke — proves the harness mechanics run end to end, never promotion evidence:

uv run python -m evaluation.run_eval --offline

Live (needs OPENAI_API_KEY):

uv run python -m evaluation.run_eval

When LANGCHAIN_TRACING_V2 + key are set, live runs also land in LangSmith. Earlier passes over dataset v1.1.0 (14 questions) produced the experiment history below — preserved here as committed captures, since the free tier's monthly trace quota and bounded retention mean experiments do not persist indefinitely on the platform:

🔐 Prompt Registry

Prompts are versioned data, not code-embedded strings. Each prompt lives in prompts/<name>/vN.yaml (names: agent_system, judge_rubric); a strict schema validates it, a state machine governs its lifecycle, and a hash-chained log records every change.

stateDiagram-v2
    [*] --> draft: artifact authored
    draft --> candidate: candidate submitted
    candidate --> promoted: live A/B gate passed + promote
    promoted --> rolled_back: a newer version promotes, or rollback
    rolled_back --> promoted: promote again (new A/B gate)

graph LR
    NEW["create candidate<br/>CLI · API · console"] --> FILE["prompts/name/vN+1.yaml<br/>atomic write"]
    FILE --> AB{"live A/B run<br/>24 questions,<br/>baseline vs candidate"}
    AB -- "no regression > 0.1<br/>adversarial 100 %" --> PROMO["promote<br/>old version rolled_back"]
    AB -- "gate failed" --> KEEP["stays candidate<br/>promotion blocked"]
    KEEP -. "human override<br/>reason required" .-> PROMO
    PROMO --> LOG[("audit.jsonl<br/>hash chain")]
    AB --> LOG
    FILE --> LOG
    PROMO --> RUN["next run resolves<br/>the promoted version"]

How a vN.yaml is created. There are three entry points and one writer: uv run python -m scripts.prompts_cli candidate <name> --file <template>, POST /api/prompts/{name}/candidates (or the console's candidate editor), or a hand-copied file followed by a reload. They all end in create_candidate, which checks the name against the known prompts, takes max(version) + 1, validates the artifact (extra="forbid", size caps, no key-looking strings), writes it atomically (temp file → os.replace) and appends a candidate_created event to the audit chain. Each artifact carries a SHA-256 of its template; {name, version, sha256} is stamped on every run, metric and scorecard entry.

The story this repo actually contains: agent_system v2 failed its live A/B gate (grounding 3.71 → 3.33, adversarial 11/13) and was never promoted; v3 was promoted over v1 after a live A/B run (judged, gate passed, 13/13 adversarial cases resisted on both sides); v1's rolled_back status is the trail of the rollback path being exercised for real. When the expanded v1.2.0 dataset then failed the grounding gate on v3, the remediation ran through the same lifecycle: judge_rubric@v2 (promoted with an audited override) and agent_system@v4 (promoted only after beating v3 in its own live A/B). Every mutation is a hash-chained data/prompt-registry/audit.jsonl entry — prompts_cli audit / verify_chain() detects a tampered line.

🔏 Audit Log

Every registry mutation — candidate created, A/B run, promotion, override, rollback — is appended to data/prompt-registry/audit.jsonl as one chained JSON line:

hash = sha256( prevHash + canonical_json(event) )     # first link: prevHash = "0" × 64

{"prevHash": "0000…0000", "hash": "7b327d95afb4…", "type": "candidate_created",
 "name": "agent_system", "version": 2, "author": "owner", "sha256": "84bf750efa36…", "description": "…"}

• Tamper-evident: verify_chain() (and prompts_cli audit) returns the first line whose hash no longer matches. Editing any line, or deleting a line other than the last, is detected.

• Never a secret store: an event whose free text looks like a credential (sk-…, Bearer …, key-shaped strings) is refused before it is written.

• Honest scope: this is tamper-evident, not tamper-proof — there is no signing key or external anchor, so someone who can rewrite the whole file can recompute the chain, and truncating the tail is not detected.

🔌 API

Web adapter (mcp-toolkit-web, default http://localhost:3000):

Prompt Registry (reads are open; mutations need ENABLE_PROMPT_ADMIN=1):

MCP server — speak the protocol directly (any MCP client works):

uv run mcp-toolkit-server            # stdio JSON-RPC on stdout, logs on stderr
uv run mcp-toolkit-agent "Which reports cover security?"
uv run mcp-toolkit-agent --stub --json "…"   # offline, machine-readable events

curl examples

# Health and discovery
curl -s http://localhost:3000/api/health
curl -s http://localhost:3000/api/status
curl -s http://localhost:3000/api/tools

# Ask a question, then stream the run
curl -s -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"question": "What does the reports table say about observability?"}'
curl -N "http://localhost:3000/api/chat/stream?runId=<runId>"

# Registry (the POSTs need ENABLE_PROMPT_ADMIN=1)
curl -s http://localhost:3000/api/prompts/agent_system
curl -s "http://localhost:3000/api/prompts/agent_system/diff?from=3&to=4"
curl -s -X POST http://localhost:3000/api/prompts/agent_system/promote \
  -H "Content-Type: application/json" -d '{"version": 5}'     # 409 until a live A/B passes
curl -s http://localhost:3000/api/prompts/audit

⚡ Performance & Cost

Every final event carries durationMs, provider usage and costUsd computed from a committed price table (MODEL_PRICING_JSON overrides it):

cost = prompt_tokens / 1M × input_price  +  completion_tokens / 1M × output_price

Unknown models resolve to null, never a fabricated $0. Measured on the committed live run (24 questions, agent_system@v4):

Latency is informational, not gated. The tail is real: multi-tool questions chain several live calls, and the single slowest row (ad-11, 26.9 s) is the oversize-write_file case. RUN_BUDGET_USD is a hard pre-call gate that terminates a run with budget_limit before it overspends.

📡 Observability & cost

• Structured logs — structlog JSON to stderr (stdout stays pure protocol), recursive key/token/secret redaction, request_id correlated end-to-end (client log → params._meta.requestId → server log).

• Metrics — Prometheus registry per component; METRICS_PORT exposes /metrics + /healthz on loopback. mcp_tool_invocations_total, mcp_guardrail_blocks_total{guardrail}, agent_tokens_total, agent_cost_usd_total, agent_runs_total{terminated_by}.

• Run telemetry — every final event carries durationMs, provider usage and costUsd from a committed price table (MODEL_PRICING_JSON override) — unknown prices stay null, never a fabricated $0. RUN_BUDGET_USD is a hard pre-call gate terminating with budget_limit.

• Token streaming — answer_delta SSE frames stream the answer live; final stays authoritative.

• Tracing — LangSmith when LANGCHAIN_TRACING_V2 + key are set; absent keys keep everything local.

🔒 Security posture

SECURITY.md is the source of truth; the headline controls:

• Every path resolves against SANDBOX_ROOT — .., absolute, drive/UNC, NUL, symlink/junction escapes all rejected on any OS.

• db_query is read-only twice — statement guard (NFKC-normalized, comment-smuggling resistant) and a mode=ro connection.

• Rate limiting: sliding window per tool + per session (session = 4×); RATE_LIMIT_BACKEND=redis + REDIS_URL shares counters across server processes (opt-in, pip install "mcp-toolkit[redis]").

• Tool output is untrusted data — sanitized, size-capped, never interpolated into system prompts (indirect-injection matrix is 13/13 in the dataset).

• The console is local, single-user, unauthenticated — registry mutations additionally need ENABLE_PROMPT_ADMIN=1.

• CI: permissions: contents: read; pip-audit, gitleaks full-history. Live evaluations stay manual and local — no scheduled job spends credit.

🚀 Quick Start

git clone <repo> && cd mcp-agent-toolkit-py
uv sync                                    # locked environment
uv run python -m scripts.seed_db           # data/demo.db fixture
cp .env.example .env                       # optional — works offline without it

# Try it (no keys needed — StubLLM + canned search):
uv run python -m scripts.demo              # scripted end-to-end demo
uv run mcp-toolkit-web                     # console at localhost:3000

# Live mode: set OPENAI_API_KEY (+ SEARCH_API_KEY for Tavily) in .env

Connect it to Claude Desktop — the server is a standard stdio MCP server, so any MCP client can drive it:

{
  "mcpServers": {
    "mcp-agent-toolkit": {
      "command": "uv",
      "args": ["run", "--project", "C:/path/to/mcp-agent-toolkit-py", "mcp-toolkit-server"],
      "env": {
        "SANDBOX_ROOT": "C:/path/to/mcp-agent-toolkit-py/data/sandbox",
        "DB_PATH": "C:/path/to/mcp-agent-toolkit-py/data/demo.db",
        "SEARCH_PROVIDER": "none"
      }
    }
  }
}

Docker:

docker build -t mcp-agent-toolkit .
docker run --rm mcp-agent-toolkit                          # stdio MCP server, UID 10001
docker run --rm -e WEB_HOST=0.0.0.0 -p 127.0.0.1:3000:3000 \
  mcp-agent-toolkit python -m mcp_toolkit.web              # console at localhost:3000

The image ships the built console, evaluation/ (scorecard + A/B gate) and the prompt registry; the web lifespan seeds the fixture DB into /data on first run. docker compose up web is the same thing wired for you — the published port stays loopback-only on the host.

⚙️ Environment Variables

.env.example is the reference. Headliners:

🐳 Docker Deployment

A three-stage image (Node builds the console → uv builds the locked venv → slim runtime) that runs as UID 10001, ships evaluation/, the prompt registry and the built console, and includes a HEALTHCHECK.

docker build -t mcp-agent-toolkit .
docker compose up web            # console at http://localhost:3000 (host port is loopback-only)
docker compose run --rm client   # one-shot scripted demo, offline StubLLM
docker compose up server         # stdio MCP server for an external client

Writable state lives only in the /data volume; the container never needs a .env and defaults to the offline stub. CI builds the image on every push and asserts: API answers, four tools discovered, console served, evaluation/ shipped, non-root UID, prompt registry present.

🖥️ Frontend

React 19 + Vite + TypeScript strict + Tailwind — a deliberately thin client:

📁 Project Structure

src/mcp_toolkit/
├── config.py              # typed Settings (SecretStr, empty = absent)
├── client/                # MCP client, LLM adapters, agent loop, CLI, events
│   └── llm/               # OpenAILLM · StubLLM behind one protocol
├── server/                # MCPServer, tool handlers, guardrails, transports
│   └── guardrails/        # path_sandbox · sql_guard · sanitize · limiters
├── prompts/               # registry: loader · state machine · audit · A/B gate
├── observability/         # structlog · Prometheus · pricing table · request ctx
└── web/                   # FastAPI: SSE runs, registry API, static console
frontend/                  # React console (thin client)
evaluation/                # dataset · checks · judge · scorecard
prompts/                   # versioned YAML artifacts (agent_system, judge_rubric)
tests/                     # unit · integration (real stdio) · e2e (Playwright)
docs/                      # architecture · decisions · QA evidence · demo GIF
scripts/                   # demo · seed_db · prompts_cli · ui_qa capture

🧪 Verification

Every gate is reproducible locally and enforced in CI:

uv run ruff check . && uv run ruff format --check .
uv run mypy --strict src
uv run pytest -q --cov=src --cov-branch --cov-fail-under=92   # 517 tests
uv run python -m evaluation.run_eval --offline                # harness smoke
uv run pytest tests/e2e -q                                    # 54 Playwright tests
npm --prefix frontend run lint && npm --prefix frontend run typecheck
npm --prefix frontend test -- --run && npm --prefix frontend run build
uv run pip-audit -r requirements.txt
gitleaks detect --no-banner

517 backend tests (92.98 % branch coverage) · 54 Playwright e2e · 55 Vitest — all offline and deterministic; live tests are opt-in via RUN_LIVE_TESTS=1.

CI (.github/workflows/ci.yml, five jobs on every push to main and every PR):

Live evaluations are never run in CI: they spend real money, so they stay manual and local, and a human commits the resulting scorecard.

✅ Quality Assurance

Committed checklists record the QA passes, so the claims above are inspectable rather than just asserted:

• docs/functional-qa/CHECKLIST.md — scenario-by-scenario functional evidence against the real backend.

• docs/ui-qa/CHECKLIST.md — visual and layout checks across three viewports and both themes, plus the automated content rules (a forbidden-literal sweep after every query) that fail on leaked internal identifiers, undefined/NaN, or [object Object].

• docs/ui-qa/DESIGN.md and docs/ui-qa/SELF-ASSESSMENT.md — design rules and the self-assessment against them; the screenshots under docs/ui-qa/ are produced by scripts/ui_qa.py against the real backend.

🛠️ Stack

Python ≥ 3.11 · uv · mcp SDK · OpenAI · FastAPI/uvicorn · pydantic v2 · sqlite3 (mode=ro) · structlog · prometheus-client · PyYAML · tenacity · pytest + hypothesis + respx + Playwright · React 19 + Vite + TS strict + Tailwind · Docker (non-root)

Known limitations & next steps

• The web console is a local, single-user, unauthenticated adapter — put an identity layer in front before exposing it.

• The default rate limiter is per-process; RATE_LIMIT_BACKEND=redis opts into shared counters (documented non-atomic check→record race — fine for a guardrail).

• Streamable HTTP is loopback + bearer-token, not Internet-hardened.

• The v1.2.0 scorecard passes, with two honest residuals: ad-11 still misreports an oversize write_file as successful (one call now instead of eight — converged, but dishonest about the outcome), and st-02 once fabricated MCP background details its tool output did not support.

• Latency has no gate: p95 is 13.1 s on the committed live run and the slowest row (ad-11) took 26.9 s; the tail comes from multi-tool chains and large generated payloads, not from a fixed overhead.

• The audit chain is tamper-evident, not tamper-proof (no signing key or external anchor), and run ids are in-memory and single-use, so a process restart drops pending runs.

• The dataset is 24 questions — a gate, not a benchmark; widening it is the natural next step.

• The committed scorecard is graded by judgeModel = gpt-4o — a different model than the agent's gpt-4o-mini (JUDGE_MODEL_NAME). Leave it unset and the judge falls back to the agent's model, which can favour its own style.

• SEARCH_PROVIDER=duckduckgo is keyless and can rate-limit under heavy use; Tavily is the stable live path.

• LangSmith tracing is opt-in and free-tier bounded: the monthly trace quota can be exhausted by repeated live runs, and retention is limited — the committed scorecard and docs/eval/ captures are the durable evidence, not the platform.

💼 Need this for your own project?

The pieces are independently reusable: the guarded-invocation pipeline, the stdio client + bounded agent loop, the Prompt Registry lifecycle, and the EDD harness all work without the console. docs/architecture.md maps the surfaces; docs/DECISIONS.md explains the non-obvious choices.

📄 License

MIT — © 2026 Kaarsten Anderson (contact@kaarstenanderson.com). See LICENSE.