<p align="center"><img src="assets/mcp-pill-logo.png" alt="MCP Pill logo: peeled banana and antique 1800 one-cent coin" width="220"></p>

<h1 align="center">MCP Pill — Governed Catalog</h1>

<p align="center">A small, open foundation for safer MCP production.</p>

> **Build faster. Spend less. Keep control.** MCP Pill gives MCP creators a
> portable preflight layer before tools, models, clouds, or money can cause a
> side effect.

**Mission:** make MCP useful in production without surrendering control of
permissions, data, cost, or provider choice. Read the [mission, vision, and
values](MISSION.md) and bring us the hardest MCP failure you can reproduce.

MCP Pill is a dependency-free, local-first MCP server for compact plugin discovery, fail-closed policy preflight, operational message validation, offline budget estimates, contribution previews, and payload-free audit receipts.

It does **not** proxy, install, import, or execute cataloged plugins. This narrow boundary is deliberate: operators can review capability metadata before granting credentials, network access, money, or side effects.

## Problems addressed

- Tool-schema bloat: clients see nine small governance tools and search compact plugin briefs on demand.
- Unsafe defaults: unknown and disabled plugins are denied.
- Ambiguous origin: catalog metadata is explicitly returned as `UNTRUSTED`.
- Missing approvals: preflight separates approval state from model intent.
- Audit leakage: receipts contain target and decision metadata, never tool arguments or secrets.
- Supply-chain surprise: the runtime has no third-party Python dependency and cataloging never imports plugin code.
- Cost and community opacity: dry-run budget estimates and a 25/75 contribution preview expose assumptions without processing payments.

This project is a governance preflight, not an execution sandbox, authentication provider, or complete MCP gateway. See [Threat model](docs/THREAT_MODEL.md).

## Why contributors join

- **A practical first contribution:** add a failure fixture, improve one
  denial reason, or translate one guide.
- **A useful result:** every accepted change ships with a reproducible test,
  evidence, and rollback notes.
- **A fair boundary:** the local core stays free; optional services cannot
  disable it; community allocation is transparent and preview-only.
- **A portable skill:** the same contracts work on a laptop, server, or
  air-gapped host before a provider is chosen.

## Tools

| Tool | Purpose |
|---|---|
| `gateway.health` | Report local process state |
| `catalog.search` | Return bounded plugin briefs |
| `catalog.inspect` | Inspect one declarative record |
| `policy.evaluate` | Produce a fail-closed, non-executing decision |
| `messages.validate` | Validate traceable operational envelopes |
| `audit.tail` | Read bounded payload-free receipts |
| `audit.verify` | Verify a receipt hash chain |
| `budget.preview` | Estimate provider reference and local upper-bound cost without execution |
| `community.preview` | Preview contributor allocation; never processes payment |

All tools declare read-only, non-destructive annotations. No network transport is shipped in v0.1.0; stdio keeps the trust boundary local and explicit.

## Run

Zero-configuration first run (no API key, provider, or network):

```bash
PYTHONPATH=src python -m mcp_governed_catalog.server
```

Operator shortcuts (still offline and non-destructive):

```bash
PYTHONPATH=src python -m mcp_governed_catalog.cli doctor
PYTHONPATH=src python -m mcp_governed_catalog.cli budget \
  --duration-seconds 30 --variants 3 \
  --commercial-rate-cents-per-second 30 --gpu-rate-cents-per-hour 76 \
  --fixed-cost-cents 25 --retry-limit 0
PYTHONPATH=src python -m mcp_governed_catalog.cli community \
  --gross-revenue-cents 10000 \
  --contributions '[{"collaborator_id":"a","production_hours":2}]'
```

To enable a catalog record for preflight only, after human review:

```bash
PYTHONPATH=src python -m mcp_governed_catalog.cli activate \
  example.local-reader --approval-ref human-ticket-001 \
  --cost-ceiling-cents 0 --confirm
```

This does not execute a plugin, use credentials, open a listener, or call a
provider. Remove the local activation with `deactivate <plugin_id>`.

For a human-readable starting point, copy
`mcp-pill.config.example.json`. It is a declarative checklist for an operator;
v0.1 does not silently activate plugins or paid resources from a config file.

Example request:

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"policy.evaluate","arguments":{"plugin_id":"example.local-reader","approval_present":false}}}
```

The example plugin is disabled, so the result is `DENY` and nothing executes.

## Test

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
python -m compileall -q src
docker build --network=none -t mcp-governed-catalog:0.1.0 .
```

## Hardened container

The image runs as UID/GID `10001`, has no package-manager install step, and is intended for `--network none`, read-only root filesystem, dropped capabilities, and no-new-privileges:

```bash
docker run --rm -i --network none --read-only \
  --cap-drop ALL --security-opt no-new-privileges \
  mcp-governed-catalog:0.1.0
```

## Add a plugin record

Edit `src/mcp_governed_catalog/data/plugins.json`. Keep new records disabled until an independent review covers source, license, identity, secrets, network, cost, permissions, tests, and rollback. The catalog is declarative; it is not an installer.

## Project status

`0.1.0` is a tested security baseline. It intentionally omits remote transport and plugin dispatch. See [research](docs/RESEARCH.md), [security policy](SECURITY.md), and [contributing](CONTRIBUTING.md).

Project name: **MCP Pill** · GitHub slug: `mcp-pill` · License: MIT.

### Five-minute contributor path

```bash
git clone <your-fork-url> mcp-pill
cd mcp-pill
PYTHONPATH=src python3 -m mcp_governed_catalog.cli doctor
PYTHONPATH=src python3 -m unittest discover -s tests -v
```

Then choose one small improvement from [ROADMAP.md](ROADMAP.md) and open an
issue describing the failure, expected behavior, test, and rollback.

## Why this exists

MCP made it easy to connect models to tools. Production teams then met the
same hard questions: which tools are trustworthy, how much context should be
advertised, who approved a side effect, where did a credential leak, and how
can a decision be reconstructed? MCP Pill is a deliberately small answer:
discover, preflight, record, and stop before execution.

## Join the community

We welcome maintainers, security reviewers, MCP server authors, local-model
builders, documentation translators, and production operators. Start with a
[good first issue](ROADMAP.md), propose a measurable failure mode, or improve
the bilingual docs. Please read [Contributing](CONTRIBUTING.md) and
[Security](SECURITY.md) first.

English and Portuguese community guide: [docs/COMMUNITY.md](docs/COMMUNITY.md)

Project history and decisions: [MEMORIAL.md](MEMORIAL.md)

Mission, vision, and values: [MISSION.md](MISSION.md)

Beginner guide with ready-to-use AI prompts: [docs/START-HERE.md](docs/START-HERE.md)

Security is the first gate: [SECURITY.md](SECURITY.md) · [threat model](docs/THREAT_MODEL.md)

Release-readiness review: [legal, security, and value review](docs/LEGAL-SECURITY-REVIEW.md)

Want to help explain MCP to more people? Use the ready-to-publish [YouTube
launch kit](docs/YOUTUBE-KIT.md).

Channel promotion link: [YouTube](https://youtu.be/MZCOrUveY-s?si=L8_3ThuvcJYIHGtA)

Additional promotional video: [watch on YouTube](https://www.youtube.com/watch?v=a6HWdK3Bkns) · [embed instructions](docs/YOUTUBE-KIT.md)

Innovation direction: [docs/INNOVATION-CHARTER.md](docs/INNOVATION-CHARTER.md)

License note: MCP Pill is MIT/open source, so the license cannot prohibit a
field of use such as commercial use. A private deployment may add a stricter
operational policy gate; see [licensing](docs/LICENSING.md).