capcard

capcard is the open-source CLI for generating, validating, and publishing Capability Cards.

A Capability Card is a machine-readable JSON document published at /.well-known/capability-card.json so APIs and MCP servers can be discovered by agents.

Public repo: https://github.com/Capability-Index/capcard

What You Can Do With It

• generate a Capability Card from an OpenAPI spec or MCP manifest
• use Anthropic, OpenAI, Gemini, or deterministic no-key generation
• validate the card against the public schema
• publish it into a deployable /.well-known/ path
• host it on GitHub Pages, Vercel, Netlify, Cloudflare Pages, or any static server

Install

pip install capcard

capcard requires Python 3.11+.

If pip is not on your shell PATH, use:

python3.11 -m pip install capcard

60-Second Quickstart

Fewest clicks

capcard init https://example.com/openapi.yaml --provider auto
capcard validate capability-card.json
capcard publish capability-card.json --target github-pages --site-dir .

That gives you:

• capability-card.json
• ./.well-known/capability-card.json
• ./.nojekyll
• ./index.html if one does not already exist

Generation Modes

1. Automatic provider selection

If one of these keys is present, capcard will use it automatically:

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• GEMINI_API_KEY

export OPENAI_API_KEY=your_key_here
capcard enrich https://example.com/openapi.yaml --provider auto --output capability-card.json

2. Explicit provider selection

capcard enrich https://example.com/openapi.yaml --provider anthropic --output capability-card.json
capcard enrich https://example.com/openapi.yaml --provider openai --output capability-card.json
capcard enrich https://example.com/openapi.yaml --provider gemini --output capability-card.json

3. Deterministic no-key mode

If you do not want to use an LLM provider, or do not have an API key yet:

capcard enrich https://example.com/openapi.yaml --provider deterministic --output capability-card.json

This produces a valid starter Capability Card from the spec metadata alone.

Commands

capcard init

Create a starter capability-card.json and optionally publish it.

capcard init https://example.com/openapi.yaml
capcard init https://example.com/openapi.yaml --provider deterministic
capcard init https://example.com/openapi.yaml --publish-target vercel --site-dir ./public

capcard enrich

Generate a Capability Card without publishing it.

capcard enrich ./openapi.yaml --provider auto --output capability-card.json
capcard enrich ./mcp-manifest.json --provider deterministic --pretty

capcard validate

Validate a local Capability Card JSON file.

capcard validate capability-card.json

capcard publish

Copy a validated card into a deployable /.well-known/ path.

capcard publish capability-card.json --target static-dir --site-dir ./public
capcard publish capability-card.json --target github-pages --site-dir .
capcard publish capability-card.json --target vercel --site-dir ./public
capcard publish capability-card.json --target netlify --site-dir ./dist
capcard publish capability-card.json --target cloudflare-pages --site-dir ./dist

Hosting Guides

• docs/QUICKSTART.md
• docs/PUBLISH_GITHUB_PAGES.md
• docs/PUBLISH_VERCEL.md
• docs/PUBLISH_NETLIFY.md
• docs/PUBLISH_CLOUDFLARE_PAGES.md
• docs/SCHEMA.md
• docs/COMPATIBILITY.md

Public Repo Publishing Model

The canonical public repo is:

• https://github.com/Capability-Index/capcard

Source of truth currently lives in the private capindex repo and is exported into this public repo. Public-safe files are prepared under oss/capcard/ and synced outward.

Scope Boundary

Open source:

• Capability Card schema
• capcard CLI
• public docs and examples

Not open source:

• CapIndex hosted index
• crawler infrastructure
• ranking logic
• private enrichment workflows

License

MIT