Metadata-Version: 2.4
Name: mcp-toolguard
Version: 0.2.0
Summary: Contracts, drift detection and security checks for MCP servers — in CI and in production.
Project-URL: Homepage, https://toolguard.io
Project-URL: Repository, https://github.com/toolguard-io/toolguard
Project-URL: Issues, https://github.com/toolguard-io/toolguard/issues
Author: David PV
License-Expression: MIT
License-File: LICENSE
Keywords: contract-testing,drift-detection,mcp,model-context-protocol,security
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.20
Requires-Dist: mcp>=1.27.2
Description-Content-Type: text/markdown

# ToolGuard

**Contracts, drift detection and security checks for MCP servers — in CI and in production.**

Know when an MCP server changes — yours, or the one you depend on.

> ⚠️ **Pre-release.** The full toolkit ships before the MCP **2026-07-28** spec lands.
>
> - ✅ `mcp-toolguard scan` — snapshot an MCP server's tools, schemas, capabilities and descriptions (stdio & streamable HTTP), with security findings
> - ✅ `mcp-toolguard baseline [--update]` — commit a reference snapshot to your repo
> - ✅ `mcp-toolguard diff` — classified diff against the baseline: **breaking** / **compatible** / **suspicious**
> - ✅ `mcp-toolguard ci` — exit codes and Markdown output for any CI, plus spec-version matrix validation (2025-11-25 + 2026-07-28)
> - ✅ 15 security rules against tool poisoning, exfiltration and lying annotations
> - ✅ A GitHub Action wrapping all of the above: [`toolguard-io/action@v1`](https://github.com/toolguard-io/action)

## Usage

```bash
# Snapshot a server over stdio…
mcp-toolguard scan "python -m my_mcp_server"

# …or over streamable HTTP; --json emits the full canonical snapshot
mcp-toolguard scan https://api.example.com/mcp --json

# Save the reference contract to .toolguard/baseline.json (commit it!)
mcp-toolguard baseline https://api.example.com/mcp

# What changed since the baseline? breaking / compatible / suspicious
mcp-toolguard diff https://api.example.com/mcp

# Gate your CI: fails on breaking changes or spec errors (policy: breaking)
# --policy audit never fails; --policy strict fails on any change
# Also validates against the MCP spec matrix: 2025-11-25 + 2026-07-28 (RC)
mcp-toolguard ci https://api.example.com/mcp --markdown

# Accepting a contract change is explicit and visible in code review:
mcp-toolguard baseline https://api.example.com/mcp --update
```

Exit codes: `0` ok · `1` policy failure (`ci`) · `2` operational error.

## Security rules

Every `scan` and `ci` runs a pack of 15 rules over the snapshot — the text and
schemas that reach your model's context:

- **TG1xx — tool poisoning / prompt injection**: imperative instructions to the
  model ("ignore previous instructions", "do not tell the user"), hidden
  `<IMPORTANT>`-style tags, cross-tool coercion, references to `~/.ssh` and
  other sensitive files, embedded URLs, encoded blobs, invisible characters.
- **TG2xx — exfiltration via schemas**: credential-shaped input parameters,
  environment-variable harvesting, conversation harvesting, unconstrained
  input schemas.
- **TG3xx — broad permissions and lying annotations**: arbitrary-execution
  tools, `readOnlyHint`/`destructiveHint` contradicted by what the tool says
  it does, credentials returned in outputs.

In `ci`, findings already present in the committed baseline are the accepted
state; only **new** findings gate. Policy `breaking` fails on new high-severity
findings; `strict` fails on any new finding.

## Install

```bash
uvx mcp-toolguard --version
# or
pip install mcp-toolguard
```

## License

MIT — see [LICENSE](LICENSE).
