MCP Capability Ledger

MCP Capability Ledger is a small command line tool for reviewing the gap between the tools an agent is allowed to use and the tools it actually used. It reads an MCP-style tool catalog plus a JSONL trace of agent tool calls, scores tool risk, flags suspicious trace events, and writes a starter least-privilege policy.

MCP Capability Ledger 是一个小型命令行工具，用来检查 Agent “被允许使用的工具”和“实际使用过的工具”之间的差距。它读取类似 MCP 的工具目录和 Agent 工具调用 JSONL 轨迹，计算工具风险、发现可疑调用，并生成一个最小权限策略草案。

What is implemented

  • A Python CLI named mcp-ledger.
  • JSON catalog loading for server/tool declarations.
  • JSONL trace loading for observed tool calls.
  • Deterministic risk scoring for mutating, authenticated, filesystem, shell, network, wallet, and destructive tools.
  • Trace anomaly detection for undeclared tools, literal credentials, destructive arguments, and broad filesystem patterns.
  • A generated JSON report, YAML policy draft, and static HTML report.
  • Unit tests covering scoring, unused high-risk tools, unknown calls, and secret literal detection.

中文说明：

  • 实现了一个名为 mcp-ledger 的 Python CLI。
  • 支持读取 server/tool 结构的 JSON 工具目录。
  • 支持读取 Agent 工具调用 JSONL。
  • 使用确定性规则给高风险工具打分，例如写操作、认证、文件系统、Shell、网络、钱包、破坏性操作。
  • 检测未声明工具、明文凭证、危险参数、宽泛路径等异常。
  • 可以输出 JSON 报告、YAML 策略草案和静态 HTML 报告。
  • 包含针对核心规则的单元测试。

Architecture

The project is intentionally simple:

  • mcp_capability_ledger.io parses tool catalogs and traces into small dataclasses.
  • mcp_capability_ledger.analyzer scores declared tools, aggregates observed usage, flags anomalies, and builds policy groups.
  • mcp_capability_ledger.report_html renders a standalone HTML report from the analysis output.
  • mcp_capability_ledger.cli wires the modules into the mcp-ledger analyze command.

中文说明：

  • io 模块负责把输入文件解析成结构化对象。
  • analyzer 模块负责风险评分、使用统计、异常检测和策略生成。
  • report_html 模块负责把分析结果渲染成可以放到 GitHub Pages 的 HTML。
  • cli 模块负责命令行参数和文件输出。

How to run

Use Python 3.10 or newer.

git clone https://github.com/jsdnaasd/mcp-capability-ledger.git
cd mcp-capability-ledger
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
mcp-ledger analyze \
  --catalog samples/tool_catalog.json \
  --trace samples/agent_trace.jsonl \
  --out report.json \
  --policy policy.yaml \
  --html docs/index.html

You can also run the module without installing:

PYTHONPATH=src python -m mcp_capability_ledger.cli analyze \
  --catalog samples/tool_catalog.json \
  --trace samples/agent_trace.jsonl

中文说明：

先创建虚拟环境并安装本项目，然后运行 mcp-ledger analyze。最重要的两个输入是工具目录 --catalog 和工具调用轨迹 --trace。输出可以是 JSON、YAML policy，也可以是 HTML 页面。

Verification / tests

python -m unittest discover -s tests
PYTHONPATH=src python -m mcp_capability_ledger.cli analyze \
  --catalog samples/tool_catalog.json \
  --trace samples/agent_trace.jsonl \
  --out report.json \
  --policy policy.yaml \
  --html docs/index.html

Expected behavior:

  • Tests pass.
  • report.json contains summary counts, tool rows, anomalies, and generated policy data.
  • policy.yaml groups tools into allow, review_required, and disabled.
  • docs/index.html opens as a static report.

中文说明：

验证方式包括单元测试和一次完整 CLI 运行。成功后会生成 JSON 报告、YAML 策略草案和 HTML 页面。

Known limitations

  • The tool does not connect to a real MCP server. It analyzes exported catalog and trace files.
  • The risk model is rule-based and should be reviewed before production use.
  • YAML output is generated by a small formatter instead of a full YAML library.
  • Trace correlation is simple; it does not reconstruct nested agent spans or multi-step plans.
  • Secret detection uses conservative patterns and will miss some private formats.

中文说明：

当前版本不会直接连接真实 MCP server，只分析导出的文件。风险评分是规则模型，不等于正式安全审计。轨迹分析也比较轻量，还没有完整还原复杂 Agent span。

Roadmap

  • Add an importer for common MCP server manifests.
  • Add span-level grouping for multi-step agent runs.
  • Add configurable risk weights in a project policy file.
  • Add diff mode to compare two traces or two catalogs.

中文说明：

后续可以增加 MCP manifest 导入、多步骤 Agent span 聚合、可配置风险权重，以及 catalog/trace 的差异比较模式。

Research note

The project direction comes from current interest in MCP, agent observability, tool governance, and least-privilege controls for autonomous agents. The implementation here is a compact local tool rather than a production observability platform.

中文说明：

这个项目的方向来自 MCP、Agent 可观测性、工具治理、最小权限控制这些近期热点。这里实现的是一个本地小工具，不是完整生产级平台。