Metadata-Version: 2.4
Name: custos-mcp
Version: 0.1.0
Summary: Runtime governance, policy enforcement, and cryptographic audit ledger for MCP tool calls
Project-URL: Homepage, https://github.com/sanjaynandanj/custos
Project-URL: Documentation, https://github.com/sanjaynandanj/custos
Project-URL: Repository, https://github.com/sanjaynandanj/custos
Author: Custos contributors
License: Apache-2.0
Keywords: ai-agents,audit,ed25519,governance,ledger,mcp,policy
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=41.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: cedarpy>=4.0; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: opentelemetry-api>=1.24; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.24; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
Requires-Dist: pytest>=8; extra == 'all'
Requires-Dist: ruff>=0.5; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
Provides-Extra: cedar
Requires-Dist: cedarpy>=4.0; extra == 'cedar'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.24; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otel'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: jinja2>=3.1; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'web'
Description-Content-Type: text/markdown

# custos-mcp

[![PyPI version](https://img.shields.io/pypi/v/custos-mcp.svg)](https://pypi.org/project/custos-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/custos-mcp.svg)](https://pypi.org/project/custos-mcp/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/sanjaynandanj/custos/blob/main/LICENSE)

Runtime governance, policy enforcement, and cryptographic audit for MCP tool calls.

Every `tools/call` from an AI agent is evaluated against a policy, allowed or denied, timed, and appended to an Ed25519-signed hash-chained ledger. The ledger format is wire-compatible with the [Node package](https://www.npmjs.com/package/custos-mcp) — audit anywhere.

```bash
pip install custos-mcp[web]
```

## Quickstart

```python
from custos import Gate, Ledger, Actor, Server, generate_keypair, load_policy

kp = generate_keypair()
kp.save(".custos")
ledger = Ledger(".custos/ledger.jsonl", kp)
policy = load_policy("policy.yaml")

gate = Gate(policy, ledger, Actor("agent-1"), Server("fs"))

result = gate.call("read_file", {"path": "/workspace/x"}, fn=open_file)
if result.allowed:
    print(result.result)
```

## CLI

```bash
custos keygen                            # write .custos/ledger.key + ledger.pub
custos proxy --policy policy.yaml -- python -m my_mcp_server
custos verify --ledger .custos/ledger.jsonl
custos bundle out.tar.gz                 # export portable evidence
custos verify-bundle out.tar.gz
custos serve                             # dashboard on :8787
```

## Policy DSL

```yaml
version: 1
id: default
default: deny
rules:
  - id: allow-read
    when:
      tool: read_file
      args.path: {prefix: "/workspace/"}
    decision: allow
    reason: workspace-only reads
```

See `spec/POLICY.md` for the full grammar.
