# The Pool MCP Server

The official EPI protocol surface over the planetary pool of free resources & events
(Sweden + Netherlands, ~454k live resources, growing). **The Pool retrieves; EPI recommends.**

Full design + rationale: [`../docs/mcp-server-design.md`](../docs/mcp-server-design.md).

## Tools (live)

| Tool | What it does |
|------|--------------|
| `search_resources(query, category?, country?, city?, near_lat?, near_lng?, radius_km?, max_value_eur?, limit?)` | Hybrid FTS5 + structured + geo + freshness search. Returns ranked, live resources. |
| `get_resource(id)` | Full record for one resource. |
| `pool_overview(country?, city?, category?)` | Coverage stats + honest "thin coverage" notes (anti-hallucination). |
| `trust_score(seed_did, target_did?)` | Subjective MeritRank trust over the signed `gift_events` graph — pair score (seed = giver at claim time) or the seed's ranked trust view. Sybil-bounded by design; validated in `test_meritrank.py`. |
| `get_contribution_spec()` | The Open Pool Protocol schema (HSDS/Schema.org-aligned) so any agent can self-onboard. |

Write/ingest tools (`register_source`, `contribute_resources`, …) are specified in the design
(§19) and land after the validated MVP wedge. The trust engine (`meritrank.py`, design §20.9)
is live read-only; its graph fills when Phase-3 signed gifting opens.

## Run

```bash
# stdio (local / co-located with EPI)
mcp/.venv/bin/python mcp/pool_mcp.py

# streamable-HTTP (remote EPI) — binds 127.0.0.1:8000, endpoint /mcp
POOL_MCP_TRANSPORT=streamable-http mcp/.venv/bin/python mcp/pool_mcp.py
```

Dependencies live in `mcp/.venv` (only the `mcp` SDK; FTS5 + R-tree are built into SQLite).
The server opens `db/pool.db` **read-only** (WAL ⇒ never blocks the scrapers).

## Connect from an MCP client (e.g. EPI / Claude)

stdio:
```json
{
  "mcpServers": {
    "pool": {
      "command": "/home/ubuntu/organs/pool/mcp/.venv/bin/python",
      "args": ["/home/ubuntu/organs/pool/mcp/pool_mcp.py"]
    }
  }
}
```
HTTP: point the client at `http://<host>:8000/mcp` (add an auth token + TLS before exposing publicly).

## Demand loop

Every search appends to `logs/mcp_queries.ndjson` — `(ts, tool, params, result_count)`.
Queries that return few/zero results are the signal for what to scrape next (design §14.C).

## Files

- `pool_mcp.py` — the server.
- `contribution_spec.json` — the Open Pool Protocol (v0.1).
- `test_tools.py` — direct tool smoke test.
- `test_mcp_client.py` — full MCP stdio-handshake test.
- `../db/migrate_mcp.py` — idempotent schema migration (FTS5, geo, liveness, provenance).