MCP Yoshi

mcp yoshi

好好看MCP的通信！

日本语版README

MCP（Model Context Protocol）工具通信的实时安全过滤器。 作为Claude Code的hook动作，检查MCP工具的发送接收数据，判断安全性。

为什么需要

• MCP工具的说明文97%不充分，13%与实施不一致（研究论文）
• 现有工具（mcp-scan，mcp-drift-detector）仅用于静态检查和预检查
• 实时通信过滤器不存在

mcp-yoshi会在通信瞬间检查数据，如果有问题会立即阻止或警告。

机能

出站检查（发送数据→MCP服务器）

｜ID｜检查｜检测对象｜ |----|---------|---------| API密钥Pattern AWS，OpenAI，GitHub，Slack，谷歌，Stripe等API密钥 |OUT-002 |私钥|RSA/EC/DSA/OPENSSH秘密鍵 | OUT-003\\High Entropy String=32个字符以上的高随机字符串 | OUT-004 | Env Value Pattern | PASSWORD，SECRET，TOKEN等の环境变数値| 邮箱地址、电话号码、信用卡号码 请求有效载荷超过50KB（大量数据传输） OUT-007Path Traversal/etc/passwd，~/.ssh/，C:\\Windows\\等敏感路径

入站检查（MCP服务器→接收数据）

｜ID｜检查｜检测对象｜ |----|---------|---------| | IN-001 | Prompt Injection |“ignore previous instructions”等の指示上书き| |IN-002| Shell命令嵌入| $(...), ; rm, \| bash 等命令注入 | IN-003 | Suspicious URL / SSRF | javascript:,缩短URL、内部网络、云元数据（169.254.169.254等） |IN-004|脚本注入| `, eval(), document.cookie 等 | 在工具说明文中嵌入的隐藏指示（12个模式） | IN-006 | ASCII Smuggling | 不可視Unicode文字（U+E0000台Tags Block, Zero-Width文字） | 在解码了Base64之后，在现有模式下重新检测 响应超过512KB（上下文窗口毒盛对策） |IN-009|隐藏字段| _hidden, $meta 等未声明字段 IN-010｜Elicitation Abuse｜将认证信息请求、命令执行引导设为BLOCK｜ \[/IN-011\]\[Sampling Injection\]\[LLM谈话器标记（[INST], >, 等）的嵌入 | IN-012 | Log-To-Leak | データ窃取指示（「send this data to...」「call the logging tool」等） | 对话标记（Human:, Assistant:）的行首嵌入 | IN-014 | Credentials in Response | stdout/stderr内の认证情报残留検出（AWS/OpenAI/GitHub等のキー、Bearer Token、秘密键）| |IN-015|参数覆盖| overrideConfig 键+ mcpServerConfig/NODE_OPTIONS/executablePath 同居のAllowlist Bypass攻撃（CVE-2026-40933关连）| |IN-017|路径遍历| ../ 目录移动+ basePath/filePath/filename 的机密路径指定（/etc/, /root/, C:\Windows\, /proc/） | |IN-018|查询注入|SQL/Cypher/NoSQL注入——块： UNION SELECT, DROP TABLE, MATCH...DELETE, ;-- /警告： ' OR ', sleep() | |IN-019|沙盒逃逸|虚拟机/功能/全局访问(globalThis.process.mainModule.require, constructor.constructor() vm2 escape 等） | 信任边界旁路（x-request-from: internal, x-forwarded-for: 127.0.0.1 等） | |IN-021 |浏览器启动RCE |木偶师/剧作家 executablePath 的规格化距离的幂函数/bin/sh, /usr/bin/nc` 等） |

速率限制（通信模式）

｜ID｜检查｜检测对象｜ |----|---------|---------| 在60秒内调用同一工具10次以上时，WARN

Rug Pull检测（工具定义篡改检测）

｜ID｜检查｜检测对象｜ |----|---------|---------| 工具定义更改检测工具定义的SHA-256散列更改 用于检测来自不同服务器的同名工具注册

在首次调用时记录工具定义的散列，如果在以后的调用中有变更，则会发生WARN。哈希波 ~/.mcp-yoshi/tool-hashes.json 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

NFKC正规化（难読化对策）

在所有入站/出站检查之前NFKC正规化中所述修改相应参数的值。透明地检测全角字符（ignore→ignore）和Unicode兼容字符的混淆。

3段阶判定

安装

npm install -g mcp-yoshi

安装，安装

# Claude Code の settings.json に hook 設定を自動追加
mcp-yoshi init

# プロジェクト単位で設定する場合
mcp-yoshi init --project

这将自动设置以下hook：

• PreToolUse: mcp__.* 匹配-出站检查
• PostToolUse: mcp__.* 匹配-入站检查

用法

设置后自动运行。每次调用MCP工具时都会执行检查。

日志检查

# 直近20件のログを表示
mcp-yoshi logs

# 直近50件のWARN以上のみ表示
mcp-yoshi logs --tail 50 --level warn

# BLOCK のみ表示
mcp-yoshi logs --level block

统计报表

# 過去7日間の検出統計を表示
mcp-yoshi stats

# 過去30日間
mcp-yoshi stats --days 30

设定确认

mcp-yoshi config

受信任的服务器

您可以将特定MCP服务器注册为受信任并跳过检查。 用户责任中的操作，但日志记录仍在继续（severity:SKIPPED）。

# サーバーを allowlist に追加（理由必須推奨）
mcp-yoshi allow memory --reason "社内ナレッジグラフ、信頼済み"

# allowlist 一覧
mcp-yoshi allow --list

# allowlist から削除
mcp-yoshi allow --remove memory

~/.mcp-yoshi/config.json 来定义自定义外观

{
  "allowlist": [
    { "server": "memory", "reason": "社内ナレッジグラフ", "addedAt": "2026-03-12T00:00:00.000Z" }
  ]
}

配置自定义

~/.mcp-yoshi/config.json 中所述修改相应参数的值。

{
  "logLevel": "warn",
  "checks": {
    "outbound": {
      "highEntropy": false
    }
  },
  "servers": {
    "*": { "enabled": true },
    "memory": { "enabled": true },
    "trusted-server": { "enabled": false }
  },
  "severity": {
    "WARN": ["highEntropy", "pii", "suspiciousUrls", "base64Payload", "largePayload", "responseSizeLimit", "hiddenFields", "rapidFire"],
    "BLOCK": ["apiKeys", "privateKeys", "promptInjection", "shellCommands", "scriptInjection", "toolTampering", "envValues", "asciiSmuggling", "pathTraversal", "elicitationAbuse"]
  }
}

按MCP服务器设置

servers 在章节中，可以控制每个MCP服务器的过滤器的ON/OFF和检查项目。

{
  "servers": {
    "*": { "enabled": true },
    "trusted-internal": { "enabled": false },
    "external-api": {
      "enabled": true,
      "checks": {
        "outbound": { "pii": false },
        "inbound": { "promptInjection": true }
      }
    }
  }
}

｜键｜说明｜ |------|------| | "*" 默认设置（适用于未定义的服务器） | "" | mcp____* 的工具

• enabled: false →完全跳过该服务器的检查
• checks -以服务器为单位覆盖全局设置

设定项目

｜项目｜默认｜说明｜ |------|-----------|------| | logDir | ~/.mcp-yoshi/logs ｜日志输出目的地｜ | logLevel | info | info：全记録， warn: WARN以上, none：无记录 | checks.outbound.* | true 启用/禁用每个出站检查 | checks.inbound.* | true 启用/禁用每个入站检查 | servers | {"*": {"enabled": true}} 按服务器ON/OFF | severity.WARN | ["highEntropy", "pii", "suspiciousUrls", ...] 判断为WARN的检查ID | severity.BLOCK | ["apiKeys", "privateKeys", "promptInjection", ...] 判断为BLOCK的检查ID

卸载

# hook 設定を削除
mcp-yoshi uninstall

# パッケージ削除
npm uninstall -g mcp-yoshi

与现有工具的区别

工具｜时机｜对象｜ |--------|----------|------| | mcp扫描 事先（静态检查）｜工具定义的安全性｜ | mcp漂移探测器 定期（检测到变更）｜篡改工具定义｜ | mcp yoshi | 实时（通信时） | 收发数据的安全性 |

安全建议

单击功能区上 .mcp.json 关于

克隆外部存储库时 .mcp.json 中定义的MCP服务器低信頼中所述修改相应参数的值。恶意 .mcp.json 报告了工具自动注册的攻击。

• 外部报告 .mcp.json 源服务器 不添加到allowlist
• 在mcp-yoshi的检查有效的状态下使用
• 检查日志以查看是否有可疑的工具调用

注意事项

• 性能：由于所有MCP工具调用都执行hook，因此MCP操作会出现若干延迟（数十ms左右）。在意的时候 logLevel: "warn" 或将受信任的服务器更改为 enabled: false 中描述的相应参数的值
• 误検出（False Positive）：高熵字符串和PII模式也可以匹配正规数据。如果经常发生错误，请禁用相应的检查，或者在severity设置中降低到WARN
• 検出限界：基于正则表达式的模式匹配和NFKC规范化检测。可能无法检测到高度混淆的攻击或未知模式。建议与其他安全工具（mcp-scan等）一起使用
• Rug Pull検出：工具定义散列 ~/.mcp-yoshi/tool-hashes.json 中所述修改相应参数的值。如果文件损坏，则自动从空状态恢复

许可证

麻省理工学院