expert-answer-mcp

<!-- This repo has no GitHub remote configured yet. Once it does, replace this comment with the real badge, filling in <owner>/<repo>: -->

An MCP server exposing one tool, get_expert_verified_answer — ask it "what is LangChain?" or "what is Mosaic?" and it answers as an expert verifier, backed by Gemini.

Live demo: add the Render URL here once deployed (see docs/CONVENTIONS.md §8.2 — the free-tier service will be asleep on first click; give it ~50s to wake up). Screenshot/GIF: add one of the web page or an MCP client call here before treating this README as finished — a reviewer should see the thing work before reading further.

Why it's interesting

• One tool, three clients. The same tool is reachable from Claude Desktop (MCP stdio), any MCP SDK client (streamable HTTP — see clients/mcp_client_demo.py), and a plain browser form. Proving client-agnosticism, not building a tool catalogue, is the point.
• Honest scope trade-offs. No Postgres, no audit log, no rate limiting, no circuit breaker — see docs/adr/0001-minimal-scope.md for why, stated as a decision rather than left to look like an omission.
• Deterministic, quota-safe repeats. A content-addressed in-memory cache means asking the same question twice doesn't call Gemini twice (docs/adr/0003-in-memory-cache.md).

Architecture

See docs/ARCHITECTURE.md for the diagram, ADR index, and constraint table.

Quickstart

git clone <this-repo>
cd expert-answer-mcp
cp .env.example .env   # fill in a real GEMINI_API_KEY
docker compose up

Then open http://127.0.0.1:8000/ to ask a question in the browser.

Connecting Claude Desktop

Copy clients/claude_desktop_config.json into Claude Desktop's MCP config, fixing the command/cwd absolute paths and GEMINI_API_KEY for your machine.

Running the standalone MCP client demo

.venv/bin/uvicorn app.main:app --port 8000 &
.venv/bin/python clients/mcp_client_demo.py

The server's client-facing MCP endpoint is /mcp (e.g. http://127.0.0.1:8000/mcp).

Testing

.venv/bin/pytest

Unit tests cover the domain logic with no I/O; integration tests cover the MCP tool registration, the web routes, and a real MCP client talking to a real running server — no test calls the live Gemini API (see docs/CONVENTIONS.md).

Limitations

• Cache is in-memory only — cleared on restart (a deliberate trade-off, not a bug).
• "Expert-verified" is a prompt-framing decision (one Gemini call), not a second verification pass.
• No rate limiting or multi-tenancy — this is a single-key portfolio demo.