Metadata-Version: 2.4
Name: capcard
Version: 0.2.0
Summary: Generate Capability Cards for /.well-known/capability-card.json from OpenAPI or MCP metadata.
Author: Capability Index
License-Expression: MIT
Project-URL: Homepage, https://github.com/Capability-Index/capcard
Project-URL: Repository, https://github.com/Capability-Index/capcard
Project-URL: Issues, https://github.com/Capability-Index/capcard/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: anthropic
Provides-Extra: openai
Provides-Extra: gemini
Dynamic: license-file

# 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

```bash
pip install git+https://github.com/Capability-Index/capcard.git
```

Once the first PyPI release is published, this will also work:

```bash
pip install capcard
```

## 60-Second Quickstart

### Fewest clicks

```bash
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`

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

### 2. Explicit provider selection

```bash
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:

```bash
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.

```bash
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.

```bash
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.

```bash
capcard validate capability-card.json
```

### `capcard publish`

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

```bash
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/QUICKSTART.md)
- [docs/PUBLISH_GITHUB_PAGES.md](docs/PUBLISH_GITHUB_PAGES.md)
- [docs/PUBLISH_VERCEL.md](docs/PUBLISH_VERCEL.md)
- [docs/PUBLISH_NETLIFY.md](docs/PUBLISH_NETLIFY.md)
- [docs/PUBLISH_CLOUDFLARE_PAGES.md](docs/PUBLISH_CLOUDFLARE_PAGES.md)
- [docs/SCHEMA.md](docs/SCHEMA.md)
- [docs/COMPATIBILITY.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
