# 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>:
[![CI](https://github.com/<owner>/<repo>/actions/workflows/ci.yml/badge.svg)](https://github.com/<owner>/<repo>/actions/workflows/ci.yml)
-->

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

```bash
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

```bash
.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

```bash
.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.