AGENTS.md — mcp/ (DataPulse MY MCP server)

Working agreement for AI agents editing or extending the read-only FastMCP server in this directory.

What this is

server.py exposes a read-only FastMCP server over the published DataPulse MY manifest (datapulse.json) and health snapshot (health/latest.json). 19 tools (canonical count in mcp.json, generated from server.py AST — never hardcode in docs). No writes to the DataPulse MY data layer.

The M8ven tool trust score (currently D, 41/100) audits this server. Tool annotation completeness, test coverage, and handler isolation are tracked findings — changes here directly affect that score.

Hard rules

1. Read-only by design. No new tool may write, mutate, or delete upstream state. If a request requires writing, return an error explaining the read-only contract.
2. Tool annotations are mandatory. Every new tool (and every existing tool touched) MUST declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. OpenAI's directory rejects tools missing any of the four hints; M8ven scoring deducts heavily for the same.
3. Handler isolation via FastMCP decorators. Use @mcp.tool(name=..., description=..., annotations={...}) — do NOT use the lower-level setRequestHandler pattern. The lower-level pattern skips handler-content checks and reduces M8ven's handler-isolation coverage.
4. Pydantic or Annotated input schemas. All tool inputs must declare a typed schema. dict[str, Any] inputs are forbidden — they fail M8ven's "Tool inputs are validated" check.
5. Tests live in mcp/tests/. Every new tool needs at least one integration test using FastMCP's in-memory client. Run uv run --with fastmcp,httpx pytest mcp/tests/ -v before pushing.
6. Secrets never flow to network. Do not add code that reads env vars and exfiltrates them, even for "debug logging." M8ven's secret-flow analysis is positive for this server today; preserve it.

7. Commit and push atomically — never leave an unpushed commit on main. scripts/datapulse-pipeline.sh (assert_managed_commits, ~line 121) walks every commit above origin/main and fails the run unless each one has a pipeline-managed subject and touches only artifact paths (health/*, badges/*, docs/*, deltas/*, data/passports/*, catalog-*.json, attestations/latest/scores.json, and a few more). mcp/* is not on that allowlist, so a code commit left unpushed here fails the health pipeline on its next run (~10 minute cadence) with control-plane degraded: local-only commit is not pipeline-managed. Commit and push as one operation. If the push fails, revert the commit (git reset --soft HEAD~1) rather than leaving it local — an uncommitted working tree is safe, an unpushed commit is not.

   A push may cost one deferred publish — it is timing-dependent, not guaranteed. Health cycles fire every ~5 minutes and commonly take ~8 or more (they probe all 447 datasets), and the deploy stage runs after the publish stage (run_mcp_sync at ~line 737, push_head at ~713/732). If a push moves origin/main inside a cycle's probe-to-publish window, that cycle logs publish deferred: origin/main moved during probe, exits 1, and never reaches the deploy, so the change waits one more cycle. Measured on three pushes: two deferred one cycle each, the third landed outside the window and cost nothing. It is self-healing either way — the pipeline re-probes on its next cycle, health publishing does not regress, and nothing is lost. Do not wait for an idle gap: an 11-minute hand-checked wait found the pipeline busy throughout, so blocking on a gap can stall indefinitely. Commit and push together, and accept a possible one-cycle delay; what is mandatory is never leaving an unpushed commit, because that is the thing that actually breaks the pipeline.

Style conventions

• Tool registration: @mcp.tool(name="search_datasets", description="...", annotations=ToolAnnotations(readOnlyHint=True, ...))
• Return type: always a dict (FastMCP serialises). Use explicit keys, not naked lists.
• Errors: raise ToolError or return a structured error dict. Do not return string error messages to clients.
• Logging: stdlib logging with module-level logger. No print statements.
• Imports: absolute imports preferred (matches Honcho convention). from mcp.server import ..., not from .server import ....
• Type hints: required on all public functions. mypy --strict clean for new code.

What is NOT in this directory

• Public deployment config — docs/mcp-deploy.md, ~/datapulse-my/.github/workflows/mcp-*.yml
• Tool catalogue & schemas — mcp.json at repo root (generated, do not hand-edit)
• Telemetry sinks — record-evidence/ and the per-caller JSONL sinks at repo root
• Deployment attestations — .attestations/chain_head.json (generated by gen_attestation_chain.py in scripts/)

Out of scope

• Anything that writes to data.gov.my, BNM, DOSM, or any upstream — that's outside our threat model
• New tools that require per-user authentication or rate-limit keys — the public endpoint is intentionally no-auth; per-user enforcement belongs to the caller's own deployment, not this public server
• New dependencies beyond FastMCP, httpx, pydantic — keep the dep tree small; M8ven scores CVE surface

Verification before push

# 1. Run the test suite
uv run --isolated --prerelease=allow --with-requirements mcp/requirements.txt --with pytest python -m pytest mcp/tests/ -v

# 2. Re-render the discovery artefacts (writes BOTH /mcp.json and /agent.json at repo root)
#    Without injection, the generator uses the same newest-mcp-revision derivation
#    as scripts/verify_mcp_deployment.py, derived only from mcp/server.py and
#    its two imported scripts/gen_per_dataset_receipt.py and
#    scripts/verify_per_dataset_receipt.py. Tests and documentation do not count.
#    Deployment may inject a source identity
#    explicitly; that injection wins. The literals in mcp/server.py are only runtime
#    fallbacks and are not a generation authority.
python3 scripts/gen_mcp_reference.py
# Expected diffs on regeneration:
#   mcp.json   - unicode escaping only (the committed file escapes em-dashes as \u2014,
#                the generator emits them literally). Any other change is content.
#   agent.json - its commit_sha must equal the deployed MCP code revision. A single-line
#                change here is real provenance movement, not formatting.
# Revert any artefact you did not intend to change rather than leaving it dirty.

# 3. Confirm the live tool count matches mcp.json (or update intentionally)
jq '.tools | length' mcp.json

# 4. Check annotations are present on every tool
jq '.tools[] | select(.annotations == null) | .name' mcp.json
# should return empty

Then commit and push in the same operation (see hard rule 7). A commit that sits above origin/main fails the next health-pipeline run, because assert_managed_commits rejects any commit whose paths are outside the artifact allowlist.

Pre-flight checklist (for dispatch briefs)

When writing a codex brief that touches mcp/server.py:

• What tool(s) change? name + line range
• What annotations are added? copy the 4-hint block into the brief
• What test is added? test name + fixture
• Why is this read-only? brief must explicitly state why no write happens
• Workdir: absolute path to this repo (most common cross-repo bug — see dotfiles AGENTS.md rule 7)