# rb209-mcp

MCP server exposing the AHDB **RB209 (Nutrient Management Guide) Web API v2** —
94 tools — plus a nutrient-planning skill.

The three `Users` auth endpoints (Login / Logout / Refresh_Token) are deliberately
not exposed: the server manages that token lifecycle itself, so a tool call to
`Logout` could only ever invalidate its own session.

The extension ships its own usage guidance, so installing the `.mcpb` in Claude Desktop is enough — you don't need to load the skill separately. The server exposes an MCP `instructions` brief on connect, and the highest-risk tools (notably the recommendation endpoint) carry the must-know rules in their tool descriptions. `skill/rb209-nutrient-planning/SKILL.md` remains the fuller guide (for Claude Code / claude.ai and as a versioned release asset); the embedded guidance is a condensed subset kept in sync with it by hand.

Tools are a faithful passthrough to the API with one deliberate exception: the
recommendation endpoint has a footgun where a missing `field.grass` (which the
API's validation does not report) makes the call fail with the misleading
`422 "…calculating the crop order"`. For that endpoint only, the server fills
the incidental required-empty sections (`grass`, `grassland`, `organicMaterials`,
`mannerOutputs`) when they are absent — never overwriting supplied data, and with
no effect on the result. See `src/recommendationGuardrail.ts`.

## Requirements

You need your own AHDB RB209 Web API licence (register at
<https://rb209.ahdb.org.uk/Home/RequestAccess>). Each user supplies their own
credentials; they never leave your machine.

## Install (non-technical — Claude Desktop)

1. Download `rb209-mcp.mcpb` from the latest [Release](../../releases).
2. Double-click it; Claude Desktop opens the installer.
3. Enter your RB209 **email** and **password** in the settings form.
4. Done — the RB209 tools appear in your chat tool.

## Install (developers)

```bash
npm install && npm run build
RB209_EMAIL=you@example.com RB209_PASSWORD=secret node dist/index.js
```

Add to an MCP client config with `command: node`, `args: [".../dist/index.js"]`,
and `env: { RB209_EMAIL, RB209_PASSWORD }`.

## Configuration

| Env var | Required | Default | Purpose |
|---------|----------|---------|---------|
| `RB209_EMAIL` | yes | — | Your RB209 licence email |
| `RB209_PASSWORD` | yes | — | Your RB209 licence password |
| `RB209_BASE_URL` | no | `https://rb209api.ahdb.org.uk` | API base URL |
| `RB209_ENABLED_GROUPS` | no | all | Comma-separated tags to expose (e.g. `Recommendation,Soil`) |
| `RB209_SPEC_PATH` | no | vendored spec | Only set when running a manually-extracted bundle standalone (the .mcpb manifest wires it automatically) |

## Development

```bash
npm test          # unit tests (msw-mocked)
npm run test:watch
RB209_EMAIL=... RB209_PASSWORD=... npm test   # also runs the live integration test
```

This server is released under the [MIT Licence](LICENSE). The RB209 data it
returns is licensed API content © AHDB under the Open Government Licence v3.0.