FishingReportAgentAI & MCP
An MCP server ships in this repository. Point an agent at it and it can fetch a stored fishing report — the verdict, the wave ladder, the conditions and the disclosure block — without burning a data call to do it.
mcp.fishingreportagent.com/mcp — POST a JSON-RPC body, authenticated per request with
your own API key. A GET returns a JSON-RPC error by design; the endpoint is stateless. The account
and key endpoints on the developer docs page are live; the rest are still
shapes. This page marks every part of the surface live or planned, and nothing here is a
commitment to a schema.
How it works
Reports are generated once and stored as standalone HTML artifacts. The MCP server reads those artifacts. It does not re-fetch weather, and it does not re-render anything to answer a tool call.
That single design choice is why an agent can ask for the same report a thousand times for nothing, and why an upstream outage degrades new reports without breaking the ones already generated.
Tools
The full report from the artifact store. Accepts a slug, or a
lat/lng pair with an optional local date.
- format
json(default) returns the structured report;textreturns a readable summary.- Never regenerates
- If no artifact matches, the tool refuses and names the command that would generate one. It does not quietly go and fetch the weather.
Lists the runs in the artifact store, newest first, with an optional free-text
query and limit. Read-only.
Just the conditions block — wind, gusts, air temperature, pressure, cloud and the hourly series — plus the wave ladder, from a stored report.
The caller's remaining daily allowance and this server's auth mode.
The ranked affiliate shortlist with rates, cookie windows and approval terms. Planning data for operators — not for end users.
Deliberately absent. Generation costs upstream calls and, on one free tier, real quota. It stays an explicit act, not something an agent falls into. If this ever ships it will be keyed, quota-checked and rate-limited from the first line.
Auth & quota
Bearer key, per account
Hooks liveHosted auth plannedThe interface carries auth and quota from day one: a bearer key, and an allowance counted per account rather than per key so a second tool cannot double your limit. The free allowance is 10 calls a day per account.
- Auth is enforced only when it is configured. With no keys present the server runs in demo mode and every single result says so — a demo that silently looks authenticated is the same lie as fake data.
- An
internalplan bypasses the allowance and still records usage. - A refused call records the attempt and returns the reason, not an empty result.
Attribution & disclosure — mandatory on every result
This is a marine-safety product, so the attribution and the disclaimer are attached to every tool result — success, refusal or error. Not a header, not a docs page: the payload.
- Upstream attribution is propagated verbatim from The Weather Agent, not paraphrased.
- Our own blocks (tides via NOAA CO-OPS, astronomy via USNO, locally computed solunar windows) are attributed separately, including the note that the solunar windows are an approximation rather than a licensed table.
- Agent-facing copy asks clients to pass the disclaimer through unchanged. A model summarising a safety notice into silence is the failure mode we are guarding against.
Live vs planned
| Part | Status | Notes |
|---|---|---|
| Report generation (verdict + artifact) | Live | Runs from this repository against live upstreams; publishes to /report.html and /reports/<slug>.html. |
| MCP server, stdio | Live | Five tools, JSON-RPC 2.0 over stdio. |
| MCP server, HTTP | Live | Hosted at mcp.fishingreportagent.com/mcp. Stateless; POST a JSON-RPC body, authenticated per request with your own API key. |
| Hosted REST API | Live | Account, key and usage endpoints under /v1/* on the same host. See API & docs. |
| Accounts, keys, usage meter | Partial | Accounts, sessions, API keys and the usage meter are live, with server-side logout. Self-service sign-in is closed (internal_only) until the rate limiter moves to a store that can actually enforce it — until then sign-in links are issued by the operator. |
| Wave ladder | Partial | Works where a wave-capable buoy is in range. Gulf routes often have a station reporting wind and water temperature but no wave sensor — the ladder then reports the gap rather than estimating it. |
| Tides & solunar | Live | NOAA CO-OPS and USNO, both public domain. |
| Inland mode (USGS flow, reservoirs) | Partial | USGS adapter built and verified against live gauges (nearest gauge, flow, gauge height, water temperature) — public domain, no key. Not yet wired into the report render path, so reports do not show it. |
| Reefs, ramps, MPAs | Planned | Designed, not built. |
| Affiliate links in reports | Planned | No program approved yet, so no report contains a link and none is monetised. The disclosure mechanism is built and travels with the link when enabled. |
Three rules this surface obeys
Never fabricate a reading
A missing value is reported as missing, with the reason. There is no mock-data fallback anywhere in the pipeline, and no neutral filler in the verdict.
Never overclaim a source
One source is used per block and is named. Single-source data is never described as multi-source, correlated or cross-validated — the count comes from what actually contributed.
Never clear a run we cannot read
If the sea state cannot be read, the report refuses to clear the open-water run and says so. An optimistic verdict on a safety product is a liability, not a feature.