Metadata-Version: 2.4
Name: agent-mcp-check
Version: 0.1.0
Summary: One-shot black-box security check for MCP servers. Malformed probes, method-not-found, unknown-tool, fail-closed grading, hash-chained trail.
Author: maintainers
License: MIT
Keywords: mcp,security,audit,testing,agent,jsonrpc
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# agent-mcp-check

> **你的 MCP Server 敢过一遍安全体检吗？**  
> One-shot black-box security check for MCP servers — 6 probes, PASS/FAIL/WARN, hash-chained trail.

```bash
pip install agent-mcp-check            # zero deps, Python 3.9+
```

<a href="https://gitcode.com/gcw_MKhSyoGN/agent-mcp-check"><img src="https://img.shields.io/badge/GitCode-gcw_MKhSyoGN%2Fagent-mcp-check-blue" alt="GitCode"></a>
<a href="https://github.com/langarden/agent-mcp-check"><img src="https://img.shields.io/badge/GitHub-langarden%2Fagent-mcp-check-black" alt="GitHub"></a>
<img src="https://img.shields.io/badge/tests-7%20passed-green" alt="tests">
<img src="https://img.shields.io/badge/license-MIT-yellow" alt="license">
<img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="python">

`agent-mcp-check` launches your MCP server (stdio transport) and throws a battery of malformed and hostile JSON-RPC messages at it. A well-behaved server rejects them all with proper JSON-RPC errors. A sloppy server crashes, hangs, or — worst case — *executes a tool it should never have run*. Part of the **Verifiable-agent family**.

> ⚠️ **Research prototype — AI-assisted development.** This is an open-source
> research/experimental prototype produced with AI assistance. It is provided
> **AS IS**, without warranty of any kind, and is not a commercial or
> production-grade product. Use at your own risk.

## Verifiable-agent family

| Repo | Role |
|:--|:--|
| **agent-mcp-check** | MCP **security check** (this repo) |
| [agent-call-audit](https://gitcode.com/gcw_MKhSyoGN/agent-call-audit) | audit **engine** |
| [agent-memory-ledger](https://gitcode.com/gcw_MKhSyoGN/agent-memory-ledger) | verifiable **memory** layer |
| [agent-audit-gateway](https://gitcode.com/gcw_MKhSyoGN/agent-audit-gateway) | HTTP **gateway** |
| [agent-route-grid](https://gitcode.com/gcw_MKhSyoGN/agent-route-grid) | audited multi-agent **routing** |

## Why

MCP is the new Unix pipe for AI agents. Everyone is shipping MCP servers fast, and most of them were never pushed with `{"method": "tools/call", "params": null}`. This tool turns "is my MCP server fail-closed?" into one command.

**What you get:**

- **6 black-box probes**: malformed params, unknown method, missing tool name, notification without id, unknown tool, missing arguments.
- **PASS / FAIL / WARN** grading per probe, with the exact sent/received pairs.
- **Hash-chained probe trail**: every probe verdict is recorded in a verifiable JSONL trail.
- Zero dependencies — pure Python 3.9+ stdlib, launches any stdio MCP server.

## Install

```bash
pip install agent-mcp-check
```

## Quick start

```bash
# Probe an MCP server that starts as `python -m my_server` (stdio transport)
agent-mcp-check run --command python --args -m my_server

# Append a hash-chained trail
agent-mcp-check run --command npx --args mcp-server-filesystem --trail ./probe.trail.jsonl
```

## Proof of life

```
$ agent-mcp-check run --command python --args tests/mock_mcp_server.py
# MCP Server Security Check

- **Server**: `python tests/mock_mcp_server.py`
- **Grade**: **PASS**
- **Passed / Failed / Warned**: 6 / 0 / 0

| Probe | Description | Status | Note |
|:--|:--|:--|:--|
| P-01 | malformed JSON must yield an error, not a crash | PASS | server answered with a JSON-RPC error |
| P-02 | unknown method must answer method-not-found | PASS | server answered with a JSON-RPC error |
| P-03 | tools/call without a name must be rejected | PASS | server answered with a JSON-RPC error |
| P-04 | tools/call notification (no id) must not execute | PASS | notification sent, no unexpected execution |
| P-05 | unknown tool must answer an error | PASS | server answered with a JSON-RPC error |
| P-06 | tools/call missing arguments must be protocol-rejected | PASS | server answered with a JSON-RPC error |
```

A failing server shows `FAIL` entries with the received payload, so you can
see exactly where it misbehaves.

## Probes

| ID | Probe | Why it matters |
|:--|:--|:--|
| P-01 | `tools/call` with `params: null` | fail-closed servers reject; weak ones crash |
| P-02 | unknown method | must answer -32601, never silently succeed |
| P-03 | `tools/call` missing tool name | protocol error, must not fall through |
| P-04 | notification without `id` | a server must never execute a tool for it |
| P-05 | unknown tool | must answer an error, not pretend success |
| P-06 | `tools/call` missing `arguments` | protocol error |

## Invariants

| # | Invariant | Enforced by |
|:--|:--|:--|
| 1 | Every malformed call expects a JSON-RPC error | `_run_probe` |
| 2 | No response / crash / hang → FAIL | `_run_probe` |
| 3 | Trail is a hash chain (prev_hash + entry_hash) | `run_checks` trail writer |
| 4 | Synthetic data only — probes never persist real payloads | `_build_probes` |
| 5 | Server is launched fresh per run | `McpProbeClient.start` |

## License

MIT. [中文版](docs/README.zh-CN.md)
