AI导哈

MCP就绪扫描工具

MCP就绪扫描工具是一个用于分析MCP服务器和代理AI工具配置以检测操作问题的生产就绪性扫描工具，适用于开发和生产环境。

  • by nik-kale
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 nik-kale/mcp-readiness-scanner

使用说明

MCP就绪扫描仪

MCP服务器和代理人工智能工具的生产准备扫描仪

注： 有关安全扫描，请参阅 思科MCP扫描仪。此工具侧重于 战备状态 --您的MCP工具在生产中的性能是否可靠。

它做什么

MCP就绪扫描程序分析MCP工具定义和配置，以解决以下操作问题：

  • 缺少超时保护 --行动会无限期地暂停吗？
  • 不安全的重试循环 --重试会导致资源耗尽吗？
  • 无声的故障路径 --错误是否被正确地暴露出来？
  • 工具范围过载 --这个工具是否做得太多了？
  • 缺少错误架构 --代理能否以编程方式处理故障？

快速开始

# Install
pip install mcp-readiness-scanner

# Scan a single tool definition
mcp-readiness scan-tool --tool my_tool.json

# Scan multiple tool definitions
mcp-readiness scan-tools tool1.json tool2.json --aggregate

# Scan with glob patterns
mcp-readiness scan-tools "tools/**/*.json" --glob --format markdown

# Scan an MCP config
mcp-readiness scan-config --config-file ~/.config/mcp/config.json

# List available providers
mcp-readiness list-providers

不需要API密钥。 开箱即用，零外部依赖。

壳牌完井

为您的shell启用选项卡补全：

# Bash
_MCP_READINESS_COMPLETE=bash_source mcp-readiness > ~/.mcp-readiness-complete.bash
echo 'source ~/.mcp-readiness-complete.bash' >> ~/.bashrc

# Zsh
_MCP_READINESS_COMPLETE=zsh_source mcp-readiness > ~/.mcp-readiness-complete.zsh
echo 'source ~/.mcp-readiness-complete.zsh' >> ~/.zshrc

# Fish
_MCP_READINESS_COMPLETE=fish_source mcp-readiness > ~/.config/fish/completions/mcp-readiness.fish

输出示例

$ mcp-readiness scan-tool --tool examples/sample_tool_definitions/bad_tool.json --format markdown

# MCP Readiness Scan Report

## Summary
**Target:** `examples/sample_tool_definitions/bad_tool.json`
**Readiness Score:** **25/100** (Critical)
**Production Ready:** No ❌

### Findings Overview
| Severity | Count |
|----------|-------|
| 🔴 Critical | 0 |
| 🟠 High | 1 |
| 🟡 Medium | 4 |
| 🔵 Low | 2 |
| ⚪ Info | 0 |

## Findings

### 🟠 High (1)
#### 1. No timeout configuration
- **Category:** Missing Timeout Guard
- **Location:** `tool.do_everything`

Tool 'do_everything' does not specify a timeout. Operations may hang indefinitely...

特性

规则抑制

抑制误报或故意偏差：

# Suppress specific rules via CLI
mcp-readiness scan-tool --tool my_tool.json --ignore-rules HEUR-001,YARA-002

# Use an ignore file
mcp-readiness scan-tool --tool my_tool.json --ignore-file .mcp-readiness-ignore

# Show what was suppressed
mcp-readiness scan-tool --tool my_tool.json --ignore-rules HEUR-001 --show-suppressed

或者在工具定义中添加内联抑制：

{
  "name": "my_tool",
  "description": "Does something useful",
  "mcp-readiness-ignore": ["HEUR-001", "HEUR-003"]
}

检验供应商

提供者 状态 依赖关系 描述
启发式 ✅ 始终可用 无 常见问题的静态分析
YARA 可选 yara-python 元数据上的模式匹配
OPA 可选 opa 二进制 使用Rego进行基于策略的检查
法学硕士评委 默认禁用 LiteLLM+模型 语义分析

输出格式

  • JSON --用于CI管道和程序化消费
  • 标记语言 --用于PR评论和人工审查
  • 静态分析结果交换格式 --用于GitHub代码扫描集成
  • 超文本标记语言 --独立的交互式报告（无外部依赖关系）
# Generate an HTML report
mcp-readiness scan-tool --tool my_tool.json --format html --output report.html

HTML报告包括：

  • 按严重程度进行交互式过滤
  • 可折叠的查找细节
  • 通过CSS媒体查询支持暗/亮主题
  • 单文件格式（无外部CSS/JS）

操作风险类别

类别 描述
silent_failure_path 工具可能会出现故障，但不会出现表面错误
non_deterministic_response 响应格式变化不可预测
missing_timeout_guard 操作可能无限期暂停
no_observability_hooks 缺乏日志记录、指标或跟踪
unsafe_retry_loop 重试逻辑可能会导致资源耗尽
overloaded_tool_scope 一个工具中的功能太多
no_fallback_contract 未定义优雅降级
missing_error_schema 错误响应缺乏结构

安装

# Basic installation
pip install mcp-readiness-scanner

# With YARA support
pip install mcp-readiness-scanner[yara]

# With all optional dependencies
pip install mcp-readiness-scanner[all]

可选依赖关系

# For YARA pattern matching
pip install yara-python

# For OPA policy checks
brew install opa  # macOS
# or download from https://www.openpolicyagent.org/

# For LLM semantic analysis
pip install litellm
export MCP_READINESS_LLM_MODEL=ollama/llama2  # or gpt-4, claude-3-sonnet, etc.

CI/CD集成

预提交钩子

添加到您的 .pre-commit-config.yaml:

repos:
  - repo: https://github.com/nik-kale/mcp-readiness-scanner
    rev: v0.1.0 # Use the latest version
    hooks:
      - id: mcp-readiness-scan-tool
        # Scans files matching *tool*.json
      - id: mcp-readiness-scan-config
        # Scans files matching mcp*config*.json
      - id: mcp-readiness-scan-all
        # Scans all .json files

然后运行：

pre-commit install
pre-commit run --all-files

GitHub操作

name: MCP Readiness Check
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install mcp-readiness-scanner
      - run: mcp-readiness scan-tool --tool tool.json --format sarif -o results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

退出代码

代码 含义
0 成功（无关键/高发现）
1 发现高度严重的发现
2 发现关键发现

配置

创建 .mcp-readiness.toml 在您的项目中：

[scan]
fail_on_critical = true
fail_on_high = false
min_score = 70
max_concurrent_providers = 4  # Limit concurrent provider execution
provider_timeout = 30  # Timeout per provider in seconds

[heuristic]
max_capabilities = 10

[yara]
enabled = true

[llm]
enabled = false  # Disabled by default
model = "ollama/llama2"

或者使用环境变量：

export MCP_READINESS_SCAN_FAIL_ON_CRITICAL=true
export MCP_READINESS_SCAN_MIN_SCORE=70

程序化使用

import asyncio
from mcpreadiness import ScanOrchestrator
from mcpreadiness.providers import HeuristicProvider

async def main():
    orchestrator = ScanOrchestrator()
    orchestrator.register_provider(HeuristicProvider())

    result = await orchestrator.scan_tool({
        "name": "my_tool",
        "description": "Does something useful",
        "timeout": 30000,
    })

    print(f"Score: {result.readiness_score}/100")
    print(f"Ready: {result.is_production_ready}")

asyncio.run(main())

文档

贡献

欢迎投稿！请参阅我们的投稿指南。

# Development setup
git clone https://github.com/mcp-readiness/scanner
cd scanner
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check mcpreadiness tests

许可证

Apache-2.0--参见 许可证 了解详情。

MCP就绪扫描仪 --因为生产可靠性很重要。

相关 MCP