HoneyMCP 蜜罐式上下文服务中间件
使用说明（Markdown 格式）
-
项目简介
- HoneyMCP 是一个面向 Model Context Protocol (MCP) 的后端中间件，旨在为 LLM 客户端提供可上下文化的资源访问、工具执行与提示模板渲染能力，同时注入“鬼工具”（ghost tools）进行攻击检测与监控。它通过拦截工具调用、生成攻击指纹、并将事件写入日志存储，提升对数据泄露与提示注入等攻击的可观测性。
- 核心能力包括：资源与数据访问管理、注册与执行工具、定义与渲染 Prompt 模板、以及基于 LLM 的动态 ghost tools 生成。服务器与客户端通过 JSON-RPC 风格的请求/响应进行通信，并且支持多种传输协议（如 stdio、SSE、WebSocket）。
-
主要功能点
- 资源与数据访问能力的托管与管理
- Ghost Tools（鬼工具）的注册、拦截与指纹记录
- 动态 ghost tool 生成（LLM 驱动）与静态工具组合
- Prompt 模板的渲染与装配
- Attack Fingerprint 级攻击指纹与事件日志的存储与 dashboard 展示
- 多传输协议支持（stdio、SSE 等）以及仪表盘与 API 的集成
- ToolGen 等工具，用自然语言描述生成新的鬼工具
- 配置、日志与仪表盘的完备集成（CLI、配置文件、REST API）
-
安装步骤
- 安装并配置 Python 运行环境（建议 Python 3.11+）
- 安装 HoneyMCP：pip install honeymcp
- 初始化配置（CLI）：honeymcp init
- 如需使用动态 ghost tools，需要提供 LLM 相关凭据（.env.honeymcp），并按需配置 llm_provider（如 openai、watsonx 等）
-
服务器配置（供 MCP 客户端参考，JSON 形式，包含 server name、command、args 等，帮助客户端了解如何启动 MCP 服务器。MCP 客户端本身不需要直接执行代码）
- 示例 1：stdio 传输（适用于 Claude Desktop 等）
- server_name: "HoneyMCP-Demo"
- transport: "stdio"
- command: "uv"
- args: ["run", "python", "examples/demo_server.py"]
- env: {"MCP_TRANSPORT": "stdio"}
- 示例 2：可选的 SSE/HTTP 传输（适用于 Web/CLAUDE 直连场景）
- server_name: "HoneyMCP-Demo"
- transport: "sse"
- command: "uv"
- args: ["run", "python", "examples/demo_server.py"]
- env: {"MCP_TRANSPORT": "sse"}
- 示例 1：stdio 传输（适用于 Claude Desktop 等）
-
基本使用方法
- 将 HoneyMCP 挂接到现有的 FastMCP 服务器：
-
- 启动一个 FastMCP 服务器并实现你的真实工具
-
- 在服务器初始化后，使用一个一行调用将 HoneyMCP 注入为中间件：mcp = honeypot(mcp)
-
- 启动服务器，蜜罐工具会随同真实工具一起暴露给客户端，并在被触发时记录攻击指纹、日志并返回伪造的响应
-
- 动态工具生成与静态工具配置：
- 动态工具：LLM 驱动，默认开启，生成域相关的 ghost tools
- 静态工具：预配置的常用 ghost tools，可快速上线
- 事件日志与仪表盘：
- 攻击指纹会被写入本地存储（默认 ~/.honeymcp/events/），可以通过仪表盘实时查看攻击事件
- 配置与扩展：
- 通过 honeymcp.yaml（及可选的 .env.honeymcp）配置、启用/禁用动态工具、仪表盘、Webhook 等
- 兼容性与测试：
- 提供多种测试用例、示例服务器（examples/demo_server.py、examples/demo_server_dynamic.py）以及CI 测试用例，确保核心流程的正确性
- 将 HoneyMCP 挂接到现有的 FastMCP 服务器：
-
需要注意的要点
- 本项目包含完整的服务器拦截、攻击指纹记录与仪表盘展示能力，而不仅仅是客户端调用的演示
- 动态 ghost tools 功能需要正确配置 LLM 提供商的凭据，否则会回落到静态工具模式
- 日志与事件存储路径可通过配置进行定制与持久化