# mcp-digible-metrics

**One MCP server that owns every marketing metric for a multifamily portfolio,
with exactly one canonical definition per metric — and the losing definition
still reachable by name, because some of them deserved to survive.**

This is the worked solution to Part 09 of the [MCP training
series](https://github.com/Overclock-Accelerator). Eight LangChain agents each
carried their own copy of the same business logic, and the copies had drifted:
five definitions of "qualified lead" 7.3x apart, two of "lease opportunity rate"
2.5x apart, three of "occupancy", and one date-range bug that had been
under-reporting spend since the day it shipped. All of it now lives here.

All data is synthetic. The vocabulary, fee structures and metric definitions are
modelled on the real business of [Digible](https://digible.com), a multifamily
marketing agency; no real client, revenue figure or case-study number appears
anywhere in this repository.

## The endpoint

```
https://mcp-digible-metrics.fastmcp.app/mcp
```

Public and unauthenticated on purpose, so anyone can point an agent or Claude
Desktop at it without an account. Speaks MCP over Streamable HTTP.

## What is in here

| File | |
|---|---|
| `metrics.py` | **The definitions.** Every metric, once. Read `DECISIONS` at the top first — it is the actual deliverable. |
| `server.py` | The seam. 22 tools, each a docstring and one delegation into `metrics.py`. Horizon entrypoint is `server.py:mcp`. |
| `digible.db` | 14 properties, 6 months, ~110k rows. Committed, read-only, deterministic (seed `20260831`). |
| `.python-version` | `3.12`. Horizon does not support 3.10. |
| `requirements.txt` | `fastmcp`, plus `psycopg` for the optional audit trail. |

## Run it locally

```bash
pip install -r requirements.txt
python server.py                 # http://127.0.0.1:8020/mcp
python server.py --stdio         # what a desktop client would spawn
fastmcp inspect server.py:mcp    # 22 tools, same check Horizon runs at build time
```

## The one tool to call first

```
metric_definitions(agent_name="you")
```

It returns the canonical definition of every metric, the reasoning behind it,
what else is reachable, and what has been retired. That tool is the whole point:
a shared server is not a code-reuse trick, it is where an organisation's business
definitions stop being folklore.

## Configuration

| Variable | Required | |
|---|---|---|
| `DATABASE_URL` | no | Postgres connection string. When set, every tool call writes a row to `mcp_training.metric_invocations`. When absent the server logs to stderr only and serves every tool normally. |

No secret is committed here and none ever will be. The runtime filesystem on
Horizon is ephemeral — committed files ship in the build artifact and are
readable, runtime writes do not survive — which is exactly why `digible.db` is in
git and the audit trail is not.

## Licence

MIT. Copyright (c) 2026 Overclock Accelerator.