Metadata-Version: 2.4
Name: toolwright
Version: 1.0.0a3
Summary: Trusted MCP supply chain for AI tools with signed approvals, fail-closed runtime, drift detection, verification, and bounded auto-repair.
Project-URL: Homepage, https://github.com/toolwright/Toolwright
Project-URL: Repository, https://github.com/toolwright/Toolwright.git
Project-URL: Documentation, https://github.com/toolwright/Toolwright#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: jsonschema>=4.0.0
Requires-Dist: prompt-toolkit>=3.0.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'
Requires-Dist: textual>=0.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: tui
Requires-Dist: textual>=0.40.0; extra == 'tui'
Description-Content-Type: text/markdown

# Toolwright

**The immune system for AI tools.**

Capture any API — or wrap an existing MCP server — and get a governed tool supply chain: credentials isolated from model context, signed approvals, fail-closed runtime, drift detection, and bounded self-healing.

[![PyPI version](https://img.shields.io/pypi/v/toolwright.svg)](https://pypi.org/project/toolwright/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776ab.svg)](https://www.python.org/downloads/)

---

<table>
<tr>
<td width="50%">

**Without governance**

```
# Token hardcoded in tool config
{"auth": "Bearer ghp_s3cr3t..."}

# Model sees the token in context
# No approval before tool runs
# API changes → silent agent failure
# No audit trail
```

</td>
<td width="50%">

**With Toolwright**

```bash
toolwright create github
export TOOLWRIGHT_AUTH_API_GITHUB_COM="Bearer ..."
toolwright serve

# Token injected at runtime, never in context
# Signed lockfile gates every change
# Drift detected before agents break
# Every decision audited
```

</td>
</tr>
</table>

---

## Why this matters

Every AI agent needs tools. But the way tools connect to APIs today is broken:

- **Credentials leak into model context** — API keys land in tool definitions, logs, and prompts where the model can see and misuse them
- **Tool changes happen silently** — new capabilities and changed schemas go live with no human review
- **APIs drift and agents break** — upstream changes cause silent failures with no alerting or recovery

Generation is the on-ramp. **Governance is the moat.**

| Concern | Typical MCP server | Toolwright |
|---|---|---|
| Credentials | In config, visible to model | Injected at runtime, never in context |
| New tools | Available immediately | Gated behind signed lockfile |
| API changes | Silent breakage | Drift detected, repair proposed |
| Failures | Retry or crash | Circuit breakers, quarantine, rollback |
| Audit trail | None | Every decision logged with reason codes |
| Recovery | Manual rebuild | Bounded self-healing with snapshots |

## Install

```bash
pip install "toolwright[all]"
```

`tw` works as shorthand. For [selective installs](#install-options) see below.

## Get started in 60 seconds

```bash
# Create governed tools from GitHub's API
toolwright create github

# Set your token (never enters model context)
export TOOLWRIGHT_AUTH_API_GITHUB_COM="Bearer ghp_yourToken"

# Get the config snippet for Claude Desktop
toolwright config

# Paste into Claude Desktop config → restart → done.
```

That's it. GitHub tools — risk-classified, with behavioral rules applied. Your agent can now list repos, create issues, and manage pull requests, all under governance.

> **Too many tools?** Serve a subset: `toolwright serve --scope repos,issues`

## Works with anything you have

| Starting point | Command |
|---|---|
| A known API | `toolwright create github` |
| A web app | `toolwright mint https://app.example.com -a api.example.com` |
| An OpenAPI spec | `toolwright capture import openapi.yaml -a api.example.com` |
| A HAR file | `toolwright capture import traffic.har -a api.example.com` |
| OTEL traces | `toolwright capture import traces.json --input-format otel -a api.example.com` |
| An MCP server | `toolwright wrap npx -y @modelcontextprotocol/server-github` |

All paths produce the same governed artifacts: tools, policy, lockfile, baselines, and verification contracts.

## How the supply chain works

```
                     ┌──────────────────────────────────────────────┐
  Browser traffic    │                                              │
  OpenAPI spec   ──> │   capture / mint   ──>   compile   ──>       │
  HAR / OTEL         │                                              │
                     │   toolpack (tools + policy + lockfile)       │
                     │                                              │
                     │   serve  ──>  governed MCP server            │
                     │     ├── credential injection (proxy layer)   │
                     │     ├── signed approval gates                │
                     │     ├── circuit breakers                     │
                     │     └── drift / verify / repair              │
                     └──────────────────────────────────────────────┘
```

1. **Capture** — Record real API behavior from any source
2. **Compile** — Generate deterministic tool definitions with schemas, risk tiers, and policies
3. **Approve** — Sign changes with Ed25519 keys. Nothing runs until reviewed.
4. **Serve** — Expose tools via MCP with auth injection, policy enforcement, and circuit breakers
5. **Heal** — Detect drift, verify behavior, and auto-repair within safety bounds

## Core capabilities

### Credentials never touch model context

Auth is resolved at runtime via environment variables — per-host, isolated. Tool definitions, logs, evidence bundles, and agent prompts are all credential-free.

```bash
export TOOLWRIGHT_AUTH_API_GITHUB_COM="Bearer ghp_..."
export TOOLWRIGHT_AUTH_API_STRIPE_COM="Bearer sk_..."
# Toolwright injects the right token for each upstream call
```

### Every change is signed before it runs

Ed25519 signatures on a lockfile. New tools, changed schemas, expanded capabilities — all gated behind explicit approval. No silent privilege escalation.

```bash
toolwright gate allow --all              # interactive review
toolwright gate check                    # verify lockfile integrity
toolwright gate block delete_user        # block a specific tool
```

### Fail-closed by default

Default deny. Explicit allowlists only. Network safety is hardcoded: SSRF prevention, private CIDR filtering, redirect validation, and response size limits.

### Drift detection and bounded self-healing

Continuous health probing catches upstream changes before your agent breaks. Safe patches auto-apply. Risky ones escalate for approval. Snapshots enable instant rollback.

```bash
toolwright drift                              # one-shot check
toolwright serve --watch --auto-heal safe      # continuous monitoring
```

### Behavioral rules and circuit breakers

Composable constraints at invocation time. Kill misbehaving tools instantly.

```bash
toolwright rules template apply crud-safety   # require read before delete
toolwright kill search_api --reason "500s"    # circuit breaker kill switch
toolwright enable search_api                  # bring it back
```

## Already have an MCP server? Wrap it.

```bash
toolwright wrap npx -y @modelcontextprotocol/server-github
toolwright wrap --url https://mcp.sentry.dev/mcp --header "Authorization: Bearer $TOKEN"
```

`wrap` discovers an upstream server's tools and applies the same approval, rules, circuit breaker, and fail-closed enforcement. No tool recreation — just governance.

## Serving options

```bash
toolwright serve                                    # stdio (Claude Desktop)
toolwright serve --http                             # HTTP + web dashboard
toolwright serve --scope repos,issues               # serve specific groups
toolwright serve --max-risk low                     # cap risk tier exposure
toolwright serve --watch --auto-heal safe           # continuous healing
```

## Documentation

- **[GitHub API in 60 seconds](docs/quickstarts/github.md)** — quickstart with `toolwright create github`
- **[Any REST API](docs/quickstarts/any-rest-api.md)** — browser capture for custom APIs
- [User Guide](docs/user-guide.md) — full lifecycle reference
- [Architecture](docs/architecture.md) — internals
- [Known Limitations](docs/known-limitations.md) | [Troubleshooting](docs/troubleshooting.md) | [Glossary](docs/glossary.md)

Run `toolwright --help` for the quick reference. Run `toolwright --help-all` for every command.

## Install options

```bash
pip install "toolwright[all]"             # MCP server + browser capture + TUI
python -m playwright install chromium     # for browser capture (use same interpreter)
```

Or install only what you need:

```bash
pip install toolwright                    # core
pip install "toolwright[mcp]"             # + MCP server
pip install "toolwright[playwright]"      # + browser capture
pip install "toolwright[tui]"             # + dashboard TUI
```

## License

MIT
