Metadata-Version: 2.4
Name: caskmcp
Version: 0.2.0b6
Summary: Action surface compiler: turn observed web traffic into safe, versioned, agent-ready tools
Project-URL: Homepage, https://github.com/caskmcp/CaskMCP
Project-URL: Repository, https://github.com/caskmcp/CaskMCP.git
Project-URL: Documentation, https://github.com/caskmcp/CaskMCP#readme
Author: Tom Allicino
License-Expression: MIT
License-File: LICENSE
Keywords: agents,api,compiler,drift,har,mcp,openapi,policy,tools,traffic
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: cryptography>=43.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Provides-Extra: all
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: playwright>=1.40.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mcp>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: playwright>=1.40.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: packaging-test
Requires-Dist: build>=1.2.0; extra == 'packaging-test'
Requires-Dist: hatchling>=1.25.0; extra == 'packaging-test'
Provides-Extra: playwright
Requires-Dist: playwright>=1.40.0; extra == 'playwright'
Provides-Extra: prove
Description-Content-Type: text/markdown

# CaskMCP

<!-- mcp-name: io.github.caskmcp/caskmcp -->

CaskMCP is a governed MCP capability supply chain with replayable proof.

Core contract:
- `caskmcp wow` proves governance enforcement, replayability, and parity in one run.
- `caskmcp govern ...` is the governance surface (approvals, lockfiles, drift gates, runtime policy).
- `caskmcp prove ...` is the proof surface (prove-twice and smoke matrix).

## Install

```bash
pip install caskmcp
```

For local development:

```bash
git clone https://github.com/caskmcp/CaskMCP.git
cd CaskMCP/cask
pip install -e .
```

## Zero-Friction Wow

Default wow path is offline and browser-free:

```bash
caskmcp wow
```

Artifacts emitted on every run:
- `prove_twice_report.md`
- `prove_twice_diff.json`
- `prove_summary.json`

`caskmcp wow` exits `0` only when all are true:
1. Governance was enforced in fail-closed mode.
2. Run A and Run B replay deterministically from the same governed inputs.
3. Parity passed.

### Optional Live Browser Path

```bash
pip install "caskmcp[playwright]"
python -m playwright install chromium
caskmcp wow --live
```

## Traffic Capture, Without Friction

CaskMCP supports three practical capture paths so teams can start where they already are.

| You already have | Command | Best for |
| --- | --- | --- |
| Nothing yet (just want to see it work) | `caskmcp wow` | Fastest first run, no credentials, no browser deps |
| A first-party web flow | `caskmcp govern mint https://app.example.com -a api.example.com` | Capturing real authorized behavior |
| Existing artifacts (HAR, OTEL, OpenAPI) | `caskmcp capture import ...` / `caskmcp openapi ...` | Adopting CaskMCP without recapturing traffic |

All three paths converge to the same governed runtime and proof loop (`diff`, `gate`, `run`, `drift`, `verify`, `prove`, `wow`).

1. Offline fixture (no credentials, no browser install):
```bash
caskmcp wow
```
2. Live browser capture (first-party authorized flows):
```bash
caskmcp govern mint https://app.example.com -a api.example.com
```
3. Existing telemetry/spec imports:
```bash
caskmcp capture import traffic.har -a api.example.com
caskmcp capture import traces.json --input-format otel -a api.example.com
caskmcp openapi openapi.json -a api.example.com
```

## Primary CLI Shape

```bash
caskmcp wow
caskmcp govern --help
caskmcp prove --help
```

Examples:

```bash
# Governed capture -> compile
caskmcp govern mint https://app.example.com -a api.example.com

# Review and approve pending lockfile
caskmcp govern diff --toolpack .caskmcp/toolpacks/<id>/toolpack.yaml --format github-md
caskmcp govern gate allow --all --lockfile .caskmcp/toolpacks/<id>/lockfile/caskmcp.lock.pending.yaml

# Enforced runtime + drift checks
caskmcp govern run --toolpack .caskmcp/toolpacks/<id>/toolpack.yaml
caskmcp govern drift --baseline .caskmcp/toolpacks/<id>/artifact/baseline.json --capture-id <capture-id>

# Prove matrix
caskmcp prove smoke
```

`cask` remains an alias for compatibility, but docs/defaults use `caskmcp`.

## Why This Exists

MCP adoption is accelerating, while official guidance highlights tool-injection and trust risks in third-party MCP servers.

- OpenAI MCP risk framing and safety guidance: [OpenAI MCP docs](https://platform.openai.com/docs/mcp)
- Remote MCP allowlist pressure: [xAI remote MCP tools](https://docs.x.ai/docs/guides/tools/remote-mcp-tools)
- Registry moderation is intentionally permissive: [MCP moderation policy](https://modelcontextprotocol.io/registry/moderation-policy)
- Real incident context: [Asana MCP data exposure write-up](https://www.upguard.com/blog/asana-discloses-data-exposure-bug-in-mcp-server)

CaskMCP focuses on local governance and evidence, not bypass tooling.

## Packaging

- Distribution: `caskmcp`
- Base install: supports offline `wow`
- Extra: `playwright` (live/browser capture)
- Extra: `mcp` (MCP SDK integration)
- Extra: `all` (convenience install for `mcp` + `playwright`)

## Development

```bash
pip install -e ".[dev,packaging-test]"
pytest tests/ -v
ruff check caskmcp tests
mypy caskmcp --ignore-missing-imports
```

## Docs

- [Architecture](ARCHITECTURE.md)
- [User Guide](docs/user-guide.md)
- [Known Limitations](docs/known-limitations.md)
- [Publishing](docs/publishing.md)
