Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
git clone --depth 1 https://github.com/kaminari-ad/mcpWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/rules/kaminari-ad/mcp/public-api-contract)<a href="https://agentmods.dev/rules/kaminari-ad/mcp/public-api-contract"><img src="https://agentmods.dev/badge/rules/kaminari-ad/mcp/public-api-contract/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/rules/kaminari-ad/mcp/public-api-contract"><img src="https://agentmods.dev/badge/rules/kaminari-ad/mcp/public-api-contract.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00000 | $0.01063 |
| Opus 5.5 | $0.00000 | $0.00425 |
| Sonnet 5.5 | $0.00000 | $0.00213 |
| Haiku 4.5 | $0.00000 | $0.00106 |
Grade A, and why
public-api-contract scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured today.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 68 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Public API Contract — docs + MCP move with it
The public contract has three surfaces that must change together: the /api/v1
routes (api/src/app/*/presentation/api/), the docs corpus (api/content/docs/,
published at kaminari.ad/docs), and the MCP server (mcp/, @kaminari-ad/mcp).
A v1 change that lands alone rots the other two: kaminari.ad/docs keeps publishing
the old contract, and MCP's generated zod parsers go stale and start rejecting real
responses at the boundary — the mcp CHANGELOG's "parser-drift phase 1" records 8 of
82 tools broken in prod by exactly that drift.
What counts as a public-API change
| Change | Contract change? |
|---|---|
New / removed / renamed /api/v1 route |
Yes |
Field added, removed, or renamed on a v1 *Request / *Response DTO |
Yes |
| New or removed enum value reachable through a v1 DTO | Yes |
New or changed error code (main/_exception_handlers.py::_APP_ERROR_CODE) |
Yes |
Changed auth, required_permission, pagination, or quota behaviour of a v1 route |
Yes |
| Changed semantics of an existing v1 field — units, default, nullability, validation | Yes |
New config key accepted inside a v1 request body (e.g. the combo-rule match_scope) |
Yes |
/api/internal, /api/admin, /api/service, /api/webhooks, /healthz only |
No |
Refactor with byte-identical /openapi.json (renamed private helper, moved use case) |
No |
| Fix that makes a route obey its already-documented contract | No — docs are already right |
In doubt: diff /openapi.json before and after. Non-empty diff = contract change.
Required updates per surface
| Surface | What to update | Ships in |
|---|---|---|
api/ v1 route + DTO |
The code. Docstrings and Field(description=...) generate /openapi.json — keep them true. |
api MR |
api/content/docs/ |
The articles covering the surface: developers/ (REST, webhooks, OAuth, MCP), getting-started/quickstart-api.md, plus platform/ + ui-reference/ when the UI exposes the same concept. Add a dated entry to resources/release-notes.md for anything an integrator must react to. |
same api MR |
mcp/ |
Regenerate src/shared/api/{openapi,zod-schemas}.ts (make gen-api-types). Then the tool input schema + .describe() text, the parser in src/infrastructure/api/parsers/, tool-registry.ts and the ## Tools list in README.md for a new/removed tool, CHANGELOG.md. |
separate mcp MR |
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- today First seen · 68 lines · 0 tokens per session scan A 26285f9f2b83
public-api-contract is a cursor rule published in the GitHub repository kaminari-ad/mcp (0 stars, last pushed yesterday), licensed MIT. It costs nothing until one of its globs matches a file; then it loads 1,063 tokens. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-11-05.
Other cursor rules, from other repositories
instructions
Definitive guidelines for building high-performance, maintainable, and secure web applications with actix-web 4, focusing on modern Rust best practices.
search-routing
Smart Search Routing — always use QMD semantic search when available, never bypass with grep for vault content.
aspnet-abp-cursorrules-prompt-file
Cursor rules for Aspnet Abp.
springboot-jpa-best-practices
A set of Chinese-language rules for structuring Java Spring Boot applications that use JPA, a library for database access.
python-django-general
General coding guidance for Python and Django projects, including naming, formatting, modular apps, built-in tools, and maintainable structure. Python is a programming language, and Django is a Python web framework.
nestjs-core-module-guidelines
A set of NestJS rules for application-wide request and error handling. Global filters handle exceptions, middleware manages requests, guards manage permissions, and interceptors manage request processing.