# mcp-server-and-agent

> **Status: work in progress.** Scaffolded, not yet implemented. This README
> will carry generated numbers once the first results land.

A hand-written MCP server at the protocol level plus a LangGraph agent over it, with four topologies run against the same task set and their failure modes measured.

**This repo answers one question:**

> What is each agent topology's failure rate, and does supervisor actually beat single-agent?

Everything here serves answering that. Features that do not help answer it are
out of scope — deliberately.

## Why this exists

<!-- 2-4 sentences: what was hard, what this establishes. Written last. -->

## Quickstart

```bash
uv sync --extra dev
uv run pytest -q
uv run python scripts/generate_results.py
```

## Results

<!-- Generated by scripts/generate_results.py into results/. Every number
     carries: date, hardware, model snapshot, seed, reproduce command, and
     the raw artifact path. No number is typed by hand. -->

_No results yet._

## Design decisions

<!-- The judgement artifact for this repo:
     docs/failure-taxonomy.md: six failure modes with reproduction seeds and rate per topology. Supervisor costs 3x the tokens for no accuracy gain.
-->

## Limitations

<!-- At least one thing this repo does NOT establish. Written honestly. -->

## Concepts covered

- 2C hand-written MCP server plus LangGraph agent (DO-8)
- 2C ReAct, plan-and-execute, reflection
- 2C topologies and their failure modes
- 2C tool design: schema clarity, granularity, errors as model feedback, idempotency, confirmation gates
- 2C MCP as a protocol: transports, discovery, resources, prompts, sampling, OAuth scope
- 2C state and memory, checkpointing, durable execution
- …and 4 more (see `docs/inventory-coverage.md`)

## License

MIT