openapi-specs

MCP-ready OpenAPI specs for APIs that do not publish one, or publish one that MCP tooling cannot load cleanly.

Vendor specs usually describe their API correctly and their tools badly. Claude and other MCP clients reject operationIds, parameter names and body properties that fall outside a narrow character set, and an MCP bridge turns every operation into a tool. This repository publishes the fixed specs, the converters that produce them, and a linter that keeps them honest.

Each entry is unofficial, is labelled with its source, and records every change and its test status in specs/<api>/source.md.

APIs

API	Source	Operations	Read-only	Test status	Last checked
DMARC Report	Apipie Swagger 2.0	50 (34 read, 16 write)	Yes	Loads in MCPHub; first call returned 401 (auth unconfirmed); deepObject untested	2026-11-10

Load a spec into MCPHub

Use the raw spec URL, not the GitHub HTML page:

https://raw.githubusercontent.com/managingwp/openapi-specs/main/specs/dmarcreport/openapi.json

Dashboard

1. Open MCPHub and choose Add Server.
2. Set the type to OpenAPI.
3. Paste the raw URL above.
4. Add the API token as a header: name Authorization, value Token token=<your-token>.
5. Save, then check that the tools list appears before calling one.

mcp_settings.json

Copy specs/dmarcreport/mcphub.json into the mcpServers object and replace the placeholder:

{
  "mcpServers": {
    "dmarcreport": {
      "type": "openapi",
      "openapi": {
        "url": "https://raw.githubusercontent.com/managingwp/openapi-specs/main/specs/dmarcreport/openapi.json",
        "version": "3.0.3",
        "security": {
          "type": "apiKey",
          "apiKey": {
            "name": "Authorization",
            "in": "header",
            "value": "Token token=YOUR_DMARC_REPORT_API_TOKEN"
          }
        }
      },
      "enabled": true
    }
  }
}

Security note

Use a read-only token and the read-only variant for reporting agents. Every entry also ships openapi.readonly.json, which contains only GET, HEAD and OPTIONS operations:

https://raw.githubusercontent.com/managingwp/openapi-specs/main/specs/dmarcreport/openapi.readonly.json

The read-only file is generated by tools/make_readonly.py; never edit it by hand. A read-only spec is a guard rail, not a substitute for a token that is actually scoped read-only.

Validate locally

Requires Python 3.11+.

pip install -r requirements.txt
python tools/convert_dmarcreport.py
python tools/make_readonly.py
python tools/lint_mcp.py
python tools/make_readonly.py --check

The linter fails on missing or duplicate operationIds, names MCP clients reject, localhost servers, a missing security scheme, and secret-shaped values. It prints the operation count and read/write split for every spec.

Add an API

Read CONTRIBUTING.md. In short: add a converter on top of tools/lib/, generate the four files under specs/<api>/, record provenance and test status in source.md, and let CI validate the result.

Licence

The code, tooling and documentation are MIT licensed. Each spec follows its vendor's terms; see the licence section of CONTRIBUTING.md and the source.md for the API. No entry is affiliated with or endorsed by its vendor.