Enable client registry discovery and beacon service

mcp-check/README.md

@@ -0,0 +1,96 @@
+# MCP-Check
+
+MCP-Check 是一套面向 MCP 服务器安全检测与治理的综合工具包，覆盖从配置治理、静态分析、动态监测到运行期防护的完整链路。方案聚焦常见威胁（提示注入、工具投毒、跨域越权、敏感数据泄露、RCE 以及 streamable-http 场景下的资源耗尽）并沉淀为统一的 CLI 工作流。
+
+## 代码结构
+
+```
+├── pyproject.toml            # 包定义与 CLI 入口
+├── src/mcp_check             # 核心实现
+│   ├── cli.py                # 命令解析与调度
+│   ├── loader.py             # 配置扫描与指纹计算
+│   ├── models.py             # 数据模型（服务器、诊断结果、策略建议）
+│   ├── state.py              # JSON 状态仓库序列化
+│   ├── discovery.py          # MCP 客户端注册表自动发现
+│   └── commands/             # 各子命令实现（survey/pulse/…）
+├── tests/                    # 单元测试与示例环境
+│   ├── fixtures/manifests.json  # atlas/echo/flux 示例服务器
+│   └── test_*.py             # 覆盖全部命令的测试用例
+└── docs/                     # 设计与实现规划
+    ├── overview.md
+    └── implementation_plan.md
+```
+
+## 命令一览
+
+| 命令 | 说明 | 核心逻辑 |
+| --- | --- | --- |
+| `survey` | 从清单或客户端注册表自动发现 MCP 资产并指纹化 | `commands.survey.execute` 调用 `discovery.discover_environment` + `state.serialize_survey` |
+| `pulse` | 多协议握手体检，记录延迟与错误分类 | `commands.pulse.execute` 读取场景延迟/错误，模拟诊断并写入状态 |
+| `pinpoint` | 定向复现提示注入、工具投毒、RCE 等高危脚本 | `commands.pinpoint.execute` 结合服务器风险向量输出复现证据 |
+| `sieve` | 静态审计工具描述，捕捉隐藏指令/跨域/敏感访问 | `commands.sieve.execute` 基于模式匹配生成 `SieveIssue` |
+| `sentinel` | 运行期代理模拟，监测审批拒绝、命令执行、streamable-http 资源耗尽 | `commands.sentinel.execute` 检测事件阈值并生成告警 |
+| `ledger` | 汇总历史检测结果，导出统一报告 | `commands.ledger.execute` 聚合最新 survey/pulse/pinpoint/sieve/sentinel |
+| `fortify` | 将风险转化为策略补丁与运行期建议 | `commands.fortify.execute` 结合检测结果生成 `FortifyPlan` |
+| `beacon` | 以轻量 HTTP 端点或 JSON 输出方式对外提供统一 MCP 资产视图 | `commands.beacon.execute` 复用 `survey` 指纹并可监听端口 |
+
+每次命令执行都会将结构化结果写入状态目录（默认 `~/.mcp-check`，可通过 `--state-dir` 指定），`ledger` 与 `fortify` 会复用这些数据生成报告与修复计划。`survey`、`pulse` 等命令默认会尝试三种来源发现 MCP：
+
+1. `--client-config` 指定的客户端注册表（JSON/TOML 文件或目录）。
+2. `--root` 指定的 manifest 根目录。
+3. 未显式提供时，会扫描 `MCP_CHECK_CLIENT_PATHS` 环境变量列出的注册表，或常见客户端的默认存储路径。
+
+若不希望自动扫描，可附加 `--no-default-client-search`。
+
+## 快速上手
+
+1. **安装依赖**
+
+   ```bash
+   pip install -e .
+   ```
+
+2. **准备测试环境**
+
+   仓库自带三个示例服务器（`atlas`、`echo`、`flux`），位于 `tests/fixtures/manifests.json`，并额外提供模拟客户端注册表 `tests/fixtures/client-registry.json`，涵盖内联与外部 manifest 两种形式，方便演示自动发现能力。
+
+3. **执行全链路检测示例**
+
+   ```bash
+   # 方式一：显式指定 manifest 目录
+   mcp-check --root tests/fixtures --state-dir .tmp/state survey
+   mcp-check --root tests/fixtures --state-dir .tmp/state pulse echo
+   mcp-check --root tests/fixtures --state-dir .tmp/state pinpoint echo
+   mcp-check --root tests/fixtures --state-dir .tmp/state sieve echo
+   mcp-check --root tests/fixtures --state-dir .tmp/state sentinel flux
+   mcp-check --root tests/fixtures --state-dir .tmp/state fortify
+
+   # 方式二：依赖客户端注册表自动发现
+   export MCP_CHECK_CLIENT_PATHS="$(pwd)/tests/fixtures/client-registry.json"
+   mcp-check --state-dir .tmp/state survey
+   mcp-check --state-dir .tmp/state pulse inline-scout
+   mcp-check --state-dir .tmp/state beacon
+
+   # 汇总
+   mcp-check --state-dir .tmp/state ledger
+   ```
+
+   以上命令会逐步构建状态仓库，并最终输出综合报告与策略建议，同时 `beacon` 将生成可供其他 MCP 客户端消费的统一清单（可搭配 `--serve` 监听端口）。
+
+## 测试
+
+项目使用 `pytest` 覆盖所有命令逻辑及状态持久化流程，包含对 streamable-http 资源耗尽、跨域滥用与提示注入等场景的验证。
+
+```bash
+pytest
+```
+
+## 设计文档
+
+- [`docs/overview.md`](docs/overview.md) 概述系统架构、命令协作与策略落地思路。
+- [`docs/implementation_plan.md`](docs/implementation_plan.md) 对应外部经验映射，明确各模块与参考设计的关系。
+- [`docs/tutorial.md`](docs/tutorial.md) 提供 10 个真实 MCP 服务的本地化演练与七大命令的逐步示例。
+
+---
+
+MCP-Check 通过模块化 CLI、状态仓库与策略引擎，帮助团队以最低的集成成本快速识别 MCP 服务器风险、验证运行期行为并给出修复建议。

mcp-check/docs/implementation_plan.md

@@ -0,0 +1,71 @@
+# MCP-Check 实现规划
+
+本规划梳理即将落地的 MCP-Check 核心能力，并说明它们对应吸收的工程经验（函数 / 模块参考），以便在不直接复制源码的前提下复现既有最佳实践。
+
+## 模块与命令映射
+
+| MCP-Check 命令 | 目标能力 | 参考实现要点 |
+| --- | --- | --- |
+| `survey` | 自动发现与编目 MCP 服务器配置，生成可比较的基线清单。 | 借鉴诊断工具中 `parseMcpConfigContent` / `mergeNormalizedConfig` 的配置读取与规范化流程，以及扫描器 `MCPScanner.get_servers_from_path` 对多格式配置的容错解析，并扩展至客户端注册表（含内联服务器）的合并逻辑。 |
+| `pulse` | 对指定服务器执行多通道握手，采集协议能力、握手延迟与错误分类。 | 参考诊断器 `connectClient` 与 `diagnose` 中的超时封装 `withTimeout`、错误归类 `classifyError`，并结合扫描器 `check_server_with_timeout` 的超时守护逻辑。 |
+| `pinpoint` | 使用预设攻击脚本针对风险服务器做深度复现，捕捉提示注入、工具投毒、RCE 征兆。 | 对照扫描器 `direct_scan` 的 payload 驱动探测，以及 Shield `detectHiddenInstructions` / `detectSensitiveFileAccess` 之类静态模式匹配函数的结果结构，输出含复现脚本的诊断记录。 |
+| `sieve` | 对工具/提示描述执行规则与模型双模静态审计，输出风险评级与修复建议。 | 结合 Shield `detectHiddenInstructions`、`detectExfiltrationChannels` 等分析器的匹配格式，以及扫描器 `analyze_scan_path` 的远程模型调用包装结构。 |
+| `sentinel` | 提供透明代理模拟、审批流与流量限速，监控 streamable-http 资源耗尽与异常命令。 | 借鉴 Snitch `MCPProxy` 的双向管道缓冲 (`LineBuffer`) 与 `MCPSecurityManager` 事件日志思路，以及扫描器 `gateway` 里的运行时拦截策略。 |
+| `ledger` | 聚合历史检测数据，输出 Markdown / JSON 报告与趋势。 | 参考诊断工具服务器端 `attachConfigMetadata` 的清单合并模式，与扫描器 `Storage` 的增量存储接口，将多命令结果标准化写入事件仓库。 |
+| `fortify` | 将检测结果转化为安全策略补丁与配置建议，保持运行期与静态策略一致。 | 结合 Shield 修复建议的结构化输出、扫描器 `Storage` 的差异检测，以及 Snitch 信任库更新逻辑，将策略映射为配置变更计划。 |
+| `beacon` | 以 MCP 服务器身份对外暴露本地已安装 MCP 资产清单。 | 参考诊断器的报告导出与 Snitch 代理的透明中继思路，封装轻量 HTTP 服务 (`/manifest`) 以便 IDE/客户端直接读取。 |
+
+## 核心功能拆解
+
+1. **配置扫描与资产盘点（`survey`）**
+   - 实现跨格式（JSON/TOML）加载、路径归一化与去重。
+   - 支持解析客户端注册表（JSON/TOML 或目录），自动收集内联服务器定义并与 manifest 结果合并。
+   - 产出带哈希指纹的基线记录，便于后续检测漂移。
+   - 存储结构参考 `Storage.record_scan_result` 的增量更新模型。
+
+2. **握手体检与错误分类（`pulse`）**
+   - 模拟 stdio/HTTP/SSE 三通道连接，记录握手延迟、协议版本、能力列表。
+   - 错误分类沿用 `classifyError` 的枚举，同时兼容 streamable-http 连接异常。
+
+3. **高危复现脚本（`pinpoint`）**
+   - 预置注入、命令执行、敏感资源访问三类脚本；可扩展。
+   - 结果格式包含输入 Payload、服务器响应、风险评级，与扫描器 `Issue` 结构对应。
+
+4. **静态审计（`sieve`）**
+   - 基于工具描述文本运行多条规则，使用 Shield 分析器类似的匹配输出。
+   - 可选调用外部模型（预留接口），保持 `analyze_scan_path` 的异步模式。
+
+5. **运行期代理（`sentinel`）**
+   - 构建事件管道模拟器，检测：未授权调用、速率超限、streamable-http 资源耗尽。
+   - 参考 Snitch `LineBuffer` 的流控处理，记录事件轨迹。
+
+6. **资产广播（`beacon`）**
+   - 将 `survey` 结果封装为可复用的 `/manifest` 接口或 JSON 输出。
+   - 提供 `--serve` 选项启动本地 HTTP 服务，让 IDE/模型在无需额外配置的情况下读取 MCP 清单。
+
+7. **报告中心（`ledger`）**
+   - 将所有命令的输出写入统一 state 目录，以时间线组织。
+   - 报告包含风险统计、服务器健康度、策略缺口。
+
+8. **策略落地（`fortify`）**
+   - 根据检测结果生成 YAML/JSON 补丁草案，涵盖：禁用工具、限流、超时、凭证要求。
+   - 对应 Snitch 信任模型：维护 `trusted_servers`、`blocked_tools`、`rate_limits` 等字段。
+
+## 测试与环境准备
+
+- 构建最小 MCP 测试环境：
+  1. `atlas` —— 基线健康服务器。
+  2. `echo` —— 存在提示注入与工具投毒风险。
+  3. `flux` —— streamable-http 端点存在资源耗尽隐患。
+- 提供客户端注册表样例 `client-registry.json`，模拟常见 IDE/助手的 MCP 插件目录，测试自动发现与 `beacon` 广播能力。
+- 提供仿真握手、工具响应、运行期事件数据，用于单元测试与集成测试。
+- 每条命令均需提供对应的单元测试，覆盖正常路径与至少一条异常路径，包括 `beacon` 与基于环境变量的自动发现流程。
+
+## 时间线
+
+1. 完成 CLI 框架、数据模型与状态存储。
+2. 逐条实现命令功能与测试。
+3. 构建测试环境与服务器样例。
+4. 更新 README 与设计文档反映实际实现。
+
+以上规划确保 MCP-Check 能够在继承成熟方案经验的同时，以全新代码落地全链路安全检测能力。

mcp-check/docs/overview.md

@@ -0,0 +1,71 @@
+# MCP-Check 设计概览
+
+本文档总结当前代码实现的模块拆分、命令协作与数据流，帮助读者理解如何在不复用外部仓库源码的情况下实现多阶段 MCP 安全检测。
+
+## 核心模块
+
+- `loader.py`：负责定位并解析 MCP 配置清单，支持 JSON/TOML，提供 `discover_manifests`、`load_manifest` 与 `calculate_fingerprint` 等工具方法。
+- `discovery.py`：新增客户端注册表解析逻辑，合并 `--root`、`--client-config`、环境变量及默认路径的多源发现结果，并处理内联服务器定义。
+- `models.py`：定义 `ServerConfig`、`PulseResult`、`SentinelResult`、`FortifyPlan` 等数据结构，并用枚举刻画传输类型、风险向量与策略动作。
+- `state.py`：提供 `StateStore` 文件存储与 `_default` 序列化逻辑，每个命令使用 `serialize_*` 函数将结果写入 `~/.mcp-check/<command>/timestamp.json`。
+- `commands/`：包含八个子命令的独立实现，模块间通过 `common.py` 提供的 `build_context`、`find_server`、`make_survey_result` 协同工作；`build_context` 现已可处理多源发现与内联服务器合并。
+- `cli.py`：统一封装命令行解析与结果输出，所有命令返回结构化数据并以 JSON 打印，便于脚本化调用或集成到 CI。
+
+## 子命令设计
+
+### `survey`
+- 通过 `discovery.discover_environment` 聚合 `--root`、`--client-config`、环境变量与默认路径的清单，支持解析客户端注册表内的内联服务器定义。
+- `load_manifest` + `calculate_fingerprint` 会将清单文件与内联定义一并纳入哈希，确保资产指纹能反映注册表变化。
+- 结果使用 `serialize_survey` 持久化，供 `ledger`/`fortify`/`beacon` 读取。
+
+### `pulse`
+- 读取 `ServerConfig.scenarios` 中的模拟握手结果，输出握手延迟、协议状态、错误分类，错误列表与状态判定逻辑参考 `handshake_errors`。
+- 支持沿用 `survey` 的发现结果，对自动注册表中的服务器同样生效。
+- 结果写入 `state/pulse/`，`load_all` 可用于后续聚合。
+
+### `pinpoint`
+- 内置注入、工具滥用、RCE 三类脚本，根据服务器的 `RiskVector` 标记判定是否命中漏洞，并生成复现证据。
+- 输出 `PinpointResult`（包含 payload、severity 与 evidence），为 `fortify` 提供策略依据。
+
+### `sieve`
+- 通过正则模式匹配工具描述与输入 schema，识别隐藏指令、数据外传、敏感路径访问与跨域 URL，并以 `SieveIssue` 形式记录。
+- 评分机制采用简单扣分模型（每条问题 -15 分），便于快速排序。
+
+### `sentinel`
+- 消费 `ServerConfig.runtime_profile` 中的运行期事件，检测未授权调用、命令执行、streamable-http 超量流量与速率超标，生成对应告警事件。
+- 支持通过参数调整 `stream_threshold` 与 `rate_limit`，便于评估不同安全策略。
+- 同样复用自动发现上下文，无需手动维护服务器名单。
+
+### `beacon`
+- 基于最新 `survey` 结果生成统一的 MCP 资产视图，可直接输出 JSON 或通过内置 HTTP 服务器 (`--serve`) 提供 `/manifest` 端点。
+- 运行时会写入 `state/beacon/`，便于追踪历史曝光内容或在 CI 中比对资产变化。
+
+### `ledger`
+- 使用 `StateStore` 拉取最新/全部命令结果，构造 `LedgerReport`，形成 `survey + pulse + pinpoint + sieve + sentinel` 的整合视图。
+- 输出 JSON 结构，适合导入安全台账或 CI 报告。
+
+### `fortify`
+- 将 `ledger`、`pinpoint`、`sieve`、`sentinel` 的结果映射为可执行策略建议：如限流、工具隔离、流控、命令白名单等。
+- 针对 `resource_exhaustion` 风险自动补充 streamable-http 限速建议，涵盖新增的问题点。
+
+## 数据流
+
+1. `survey` 生成初始资产清单与指纹，输入源可来自客户端注册表或显式 manifest。
+2. `pulse`、`pinpoint`、`sieve`、`sentinel` 分别写入状态仓库（按命令归档）。
+3. `beacon` 可随时复用 `survey` 结果对外暴露统一视图，供其他 MCP 客户端或安全平台查询。
+4. `ledger` 聚合所有命令结果，形成时间戳化的综合报告。
+5. `fortify` 读取聚合数据，输出面向运行期/配置的策略计划，可进一步转化为配置补丁或审计任务。
+
+## 测试环境
+
+- `tests/fixtures/manifests.json` 提供三个示例服务器：
+  - `atlas`：基线健康。
+  - `echo`：包含提示注入、跨域与命令执行风险。
+  - `flux`：模拟 streamable-http 资源耗尽与速率超限。
+- `tests/fixtures/client-registry.json` 构建了一个模拟的 MCP 客户端注册表，包含对 `manifests.json` 的引用以及一个内联定义的服务器 `inline-scout`，用于验证自动发现与内联合并逻辑。
+- 每条命令均有单元测试：`test_survey.py`、`test_pulse.py`、`test_pinpoint.py`、`test_sieve.py`、`test_sentinel.py`、`test_ledger.py` 覆盖成功/告警路径，确保状态持久化与策略生成逻辑正确。
+- 新增 `test_beacon.py` 验证 MCP-Check 以 MCP 服务形式暴露资产视图的能力，`test_survey.py` 亦扩展为覆盖环境变量驱动的自动发现流程。
+
+---
+
+当前实现以模块化 Python 代码复现 MCP 安全工具链的关键能力，便于进一步扩展真实握手、外部模型接入与 IDE 集成。通过状态仓库与统一 CLI，可快速串联资产发现、风险诊断、动态防护与策略治理的闭环流程。