KryptosAI/mcp-observatory

# MCP Observatory ``` ███╗ ███╗ ██████╗██████╗ ████╗ ████║██╔════╝██╔══██╗ ██╔████╔██║██║ ██████╔╝ ██║╚██╔╝██║██║ ██╔═══╝ ██║ ╚═╝ ██║╚██████╗██║ ╚═╝ ╚═╝ ╚═════╝╚═╝ O B S E R V A T O R Y ``` [](https://github.com/KryptosAI/mcp-observatory/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@kryptosai/mcp-observatory) [](https://www.npmjs.com/package/@kryptosai/mcp-observatory) [](./LICENSE) [](./package.json) [](https://smithery.ai/server/@kryptosai/mcp-observatory) [](https://glama.ai/mcp/servers/KryptosAI/mcp-observatory) **原生的 GitHub CI、SARIF 和安全门禁，在 agents 依赖 MCP servers 之前为其提供保障。** Agents 不应依赖无人测试的工具。MCP Observatory 将本地 MCP 检查转化为维护者已经熟知的发布门禁证据：GitHub Actions、安全发现、schema 漂移检测、PR 报告、评分徽章、agent 可访问的诊断，以及 GitHub Code Scanning SARIF。 从一个 server 开始： ``` npx @kryptosai/mcp-observatory test npx -y my-mcp-server ``` 然后将通过的检查转化为带有 Code Scanning 的 CI： ``` npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y my-mcp-server" --sarif ``` 查看[发布页面](./docs/launch.md)、[GitHub Code Scanning 演示](./docs/code-scanning-demo.md)以及[面向 MCP servers 的 GitHub Code Scanning](./docs/github-code-scanning-for-mcp.md)。 另外两个快速路径： 克隆了此仓库？从这里开始：[`CLONED_THIS.md`](./CLONED_THIS.md)。想要贡献？将一个 server 添加到 [MCP Target Registry](./docs/target-registry.md) 或使用 [Agent Task Pack](./docs/agent-tasks.md)。 使用一条命令添加 MCP CI： ``` npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y my-mcp-server" ``` 当你需要原生安全发布门禁时，将归一化的 MCP 发现上传至 GitHub Code Scanning： ``` npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y my-mcp-server" --sarif ``` 将 Observatory 添加为 agent 可访问的 MCP server： ``` claude mcp add mcp-observatory -- npx -y @kryptosai/mcp-observatory serve ``` 正在构建自主 agent、OpenClaw 风格的生产力机器、MCP gateway 或 bot runtime？请从 [agent runtime 快速入门](./docs/agent-runtime-quickstart.md)开始，复制 [OpenClaw MCP 可靠性 agent 模板](./docs/openclaw-agent-template/SOUL.md)，或将你的 agent 指向 [`llms.txt`](./llms.txt) 和 [`AGENTS.md`](./AGENTS.md)。 或立即测试某个 server： ``` npx @kryptosai/mcp-observatory test npx -y @modelcontextprotocol/server-everything ``` 将其用作 CLI、GitHub Action 或 MCP server，让你的 AI agent 自主扫描、测试、记录、回放并验证其他 MCP servers。

[](https://glama.ai/mcp/servers/KryptosAI/mcp-observatory) ## 为什么使用 MCP Observatory MCP servers 正在成为生产依赖项。如果 agents 依赖它们，团队就需要一种方法，在这些故障触及用户之前，捕获损坏的工具、不安全的 schemas、schema 漂移、缓慢的响应以及安全陷阱。 Observatory 为维护者和团队提供： - 使用 `setup-ci --all` 的**单命令 CI 设置** - 用于兼容性、漂移和安全发现的 **GitHub PR 评论** - 用于归一化 MCP 发现的 **GitHub Code Scanning SARIF** - 用于公共信任信号的**健康分数徽章** - 用于回归测试的**记录/回放/验证**工作流 - **MCP server 模式**，使 agents 能够直接检查其他 MCP servers - 针对托管历史记录、私有仓库报告、认证、支持和集群可见性的**生产支持路径** 查看[发布页面](./docs/launch.md)、[面向 MCP servers 的 GitHub Code Scanning](./docs/github-code-scanning-for-mcp.md)、[Code Scanning 演示](./docs/code-scanning-demo.md)、[目标库](./docs/target-gallery.md)、[目标注册表](./docs/target-registry.md)、[目标贡献指南](./docs/target-contribution-guide.md)、[Agent Task Pack](./docs/agent-tasks.md)、[`setup-ci --doctor`](./docs/setup-ci-doctor.md)、[MCP server 安全实战指南](./docs/mcp-security-field-guide.md)、[安全方法论](./docs/methodology.md)、[MCP Server 安全指数](./docs/mcp-server-safety-index.md)、[2026 年 6 月安全实战报告](./docs/mcp-safety-field-report-2026-06.md)、[参考评估](./docs/reference-evaluations.md)、[MCP lock files](./docs/mcp-lock-files.md)、[公开证据](./docs/proof.md)、[活动归因](./docs/campaign-attribution.md)、[本地指标仪表板](./docs/metrics-dashboard.md)以及[商业支持](./COMMERCIAL.md)。 ## 面向安全和平台团队 MCP servers 正在成为 AI 软件供应链的一部分。在这些工具成为关键任务工作流中的依赖项之前，agents 需要可靠、可测试、可审计的工具。 MCP Observatory 为安全和平台团队提供 MCP server CI、schema 漂移检测、安全发现、SARIF/HTML/Markdown 报告、GitHub Code Scanning 上传，以及通向认证或集群可见性的途径。本地开源使用保持免费；生产、私有仓库和集群使用可通过付费的 MCP Readiness Review 进行。 ## 生产支持 在 MIT 许可下，本地开源使用保持免费。在生产环境中运行 MCP 的团队可以使用 [MCP Readiness Review](./docs/paid-pilot-offer.md) 进行 CI 推广、SARIF/Code Scanning 设置、私有仓库审查、定期安全报告、认证审查、支持和集群可见性。默认套餐起价为 `$2,500`。 运行 `npx @kryptosai/mcp-observatory cloud`，从 issue 选择器打开试用请求，或查看 [COMMERCIAL.md](./COMMERCIAL.md)。另请参阅[隐私和遥测](./PRIVACY.md)、[活动归因](./docs/campaign-attribution.md)以及[生产使用条款](./TERMS.md)。 ## 快速入门 扫描你的 Claude config 中的每个 MCP server： ``` npx @kryptosai/mcp-observatory ``` 深入探索——同时调用安全工具以验证它们是否确实运行： ``` npx @kryptosai/mcp-observatory scan deep ``` 测试特定 server： ``` npx @kryptosai/mcp-observatory test npx -y @modelcontextprotocol/server-everything ``` 将其作为 MCP server 添加到 Claude Code： ``` claude mcp add mcp-observatory -- npx -y @kryptosai/mcp-observatory serve ``` 或手动将其添加到你的 config： ``` { "mcpServers": { "mcp-observatory": { "command": "npx", "args": ["-y", "@kryptosai/mcp-observatory", "serve"] } } } ``` ## 命令 | 命令 | 功能说明 | |---------|-------------| | `scan` | 从 config 文件中自动发现 servers 并检查所有 server（默认） | | `scan deep` | 扫描并调用安全工具以验证它们是否执行 | | `test ` / `test --target ` | 通过命令或目标 config 测试特定 server | | `record ` | 将 server session 记录到 cassette 文件中以供离线回放 | | `replay ` | 离线回放 cassette —— 不需要实时 server | | `verify ` | 验证实时 server 是否仍与记录的 cassette 匹配 | | `diff ` | 比较两次运行 artifact 以发现回归和 schema 漂移 | | `watch ` | 监视 server 的变化，并在发生回归时发出警报 | | `suggest` | 检测你的技术栈并从注册表中推荐 MCP servers | | `serve` | 作为面向 AI agents 的 MCP server 启动 | | `lock` | 将 MCP server schemas 快照到 lock file 中 | | `lock verify` | 验证实时 servers 是否与 lock file 匹配 | | `history` | 显示 MCP servers 的健康分数趋势 | | `setup-ci` / `init-ci` | 为 MCP 兼容性/安全检查创建 GitHub Action 和徽章代码段 | | `setup-ci --sarif` | 生成将归一化发现上传到 GitHub Code Scanning 的工作流 | | `setup-ci --doctor` | 检查仓库是否具有完整的 CI 采用套件 | | `ci-report` | 生成用于创建 GitHub issue 的 CI 报告 | | `enterprise-report` | 从运行 artifact 生成静态生产/安全报告 | | `score ` | 评估 MCP server 的健康状况（0-100） | | `badge ` | 为 README 生成 SVG 健康分数徽章 | | `cloud` | 显示托管报告、安全审查和企业试点选项 | 运行不带参数的命令以获取交互式菜单： ## 它的作用 **检查功能** —— 连接到 server 并验证 tools、prompts 和 resources 是否正确响应。 **调用工具** —— 不仅仅停留在列出阶段。实际调用安全工具（无必需参数 / readOnlyHint）并报告哪些可用，哪些会崩溃。 ``` npx @kryptosai/mcp-observatory scan deep ``` **检测 schema 漂移** —— 对比两次运行的结果，并显示添加/删除的字段、类型更改和破坏性的参数更改。 ``` npx @kryptosai/mcp-observatory diff run-a.json run-b.json ``` **推荐 servers** —— 扫描你的项目以查找语言、框架、数据库和云提供商，然后交叉引用 [MCP registry](https://registry.modelcontextprotocol.io) 以推荐你缺少的 servers。 ``` npx @kryptosai/mcp-observatory suggest ``` 或者在 MCP server 模式下运行时询问你的 agent“我应该添加哪些 MCP servers？”。 **安全扫描** —— 分析 tool schemas 以查找危险模式：shell 注入面、广泛的文件系统访问权限、缺少身份验证以及 response 中的凭据泄露。 ``` npx @kryptosai/mcp-observatory test --security npx -y my-mcp-server ``` **记录 / 回放 / 验证** —— 捕获实时 session，在 CI 中离线回放，并验证没有任何更改。就像 MCP 的 [VCR](https://github.com/vcr/vcr) 一样。 ``` # 记录 session npx @kryptosai/mcp-observatory record npx -y @modelcontextprotocol/server-everything # 离线回放（无需 server） npx @kryptosai/mcp-observatory replay .mcp-observatory/cassettes/latest.cassette.json # 验证 live server 是否仍然匹配 npx @kryptosai/mcp-observatory verify cassette.json npx -y @modelcontextprotocol/server-everything ``` **监视回归** —— 按间隔重新运行检查，并在发生某些变化时发出警报。 ``` npx @kryptosai/mcp-observatory watch target.json ``` ### 扫描位置 当你运行 `scan` 时，它会在以下位置查找 MCP configs： - `~/.claude.json` (Claude Code) - `~/Library/Application Support/Claude/claude_desktop_config.json` (Claude Desktop, macOS) - `%APPDATA%/Claude/claude_desktop_config.json` (Claude Desktop, Windows) - `.claude.json` 和 `.mcp.json`（当前目录） ## CI / GitHub Action 将 Observatory 添加到你的 MCP server 的 CI pipeline 中： ``` npx @kryptosai/mcp-observatory setup-ci --all --command "npx -y my-mcp-server" ``` 检查采用套件： ``` npx @kryptosai/mcp-observatory setup-ci --doctor ``` 或手动创建工作流： ``` # .github/workflows/observatory.yml name: MCP Server Check on: [pull_request] permissions: contents: read jobs: observatory: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: KryptosAI/mcp-observatory/action@v0.27.0 with: command: npx -y my-mcp-server deep: true security: true comment-on-pr: false set-status: false ``` Action 输入： | 输入 | 描述 | 默认值 | |-------|-------------|---------| | `command` | 要测试的 server 命令 | （如果没有 `target` 则为必填） | | `target` | 目标 config JSON 的路径 | | | `targets` | 用于多服务器矩阵扫描的 MCP config 文件路径 | | | `deep` | 同时调用安全工具 | `false` | | `security` | 运行安全分析 | `false` | | `fail-on-regression` | 遇到问题时使 action 失败 | `true` | | `fail-on-baseline-drift` | 基线验证检测到漂移时使 action 失败 | `true` | | `comment-on-pr` | 将报告作为 PR 评论发布。需要 `pull-requests: write` 权限。 | `true` | | `set-status` | 在 HEAD SHA 上设置 commit 状态检查（通过/失败）。需要 `statuses: write` 权限。 | `true` | | `github-token` | 用于 PR 评论和 commit 状态的 token | `${{ github.token }}` | 当工作流授予写入权限时，该 action 可以对 PR 进行评论并设置 commit 状态。`setup-ci` 默认生成对第三方友好的只读工作流，并允许维护者稍后选择加入评论/状态。`init-ci` 仍作为向后兼容的别名提供。有关所有选项，请参见 [`action/README.md`](./action/README.md)。 生产团队可以添加托管 CI 历史记录、私有仓库报告、定期安全报告、认证审查、支持和集群可见性。运行 `npx @kryptosai/mcp-observatory cloud`，查看 [COMMERCIAL.md](./COMMERCIAL.md)，或从 issue 选择器打开试点请求。 ### 由 MCP Observatory 认证 MCP server 维护者可以在其 README 中添加公共兼容性/安全信号： ``` [](https://github.com/KryptosAI/mcp-observatory) ``` 或从实时检查中生成分数徽章： ``` npx @kryptosai/mcp-observatory badge npx -y my-mcp-server --output docs/mcp-health.svg ``` 有关 GitHub Action 模板、维护者 PR 正文和徽章推广手册，请参见[认证分发循环](./docs/certification-distribution.md)。 从本地运行 artifact 生成为试点准备好的生产/安全报告： ``` npx @kryptosai/mcp-observatory enterprise-report \ --account "Your Company" \ --format html \ --output observatory-enterprise-report.html ``` 为了在 CI 中更清晰的内部账户归因，请设置： ``` MCP_OBSERVATORY_ORG=your-company.com MCP_OBSERVATORY_CONTACT=your-team-contact ``` 正在测试 Feishu/Lark 集成？请参见 [Feishu/Lark MCP 指南](./docs/feishu-lark-mcp.md)。 ### Lock Files ``` $ npx @kryptosai/mcp-observatory lock # Snapshot all server schemas $ npx @kryptosai/mcp-observatory lock verify # Verify no drift since last lock ``` Lock files 是 AI 工具的 package-lock：提交 MCP 合约，然后让 CI 中的每个 tool、schema、prompt 或 resource 漂移变得可见。请参见 [MCP lock files]()。 ### 趋势跟踪 ``` $ npx @kryptosai/mcp-observatory history # Show health trends over time ``` ### 夜间扫描 ``` $ npx @kryptosai/mcp-observatory ci-report # Generate regression report for CI ``` ## MCP Server 模式 **没有其他测试工具本身是 MCP server。** 将 Observatory 添加为 server，你的 AI agent 就可以自主测试、诊断和监视其他 MCP servers。 ``` claude mcp add mcp-observatory -- npx -y @kryptosai/mcp-observatory serve ``` 你的 agent 获得 10 个工具： | 工具 | 何时使用 | |------|---------------| | `scan` | 检查所有已配置的 MCP servers 是否健康 | | `check_server` | 在安装前或更新后测试特定 server | | `score_server` | 获取 server 的快速健康分数和评级 | | `record` | 捕获正常工作的 server 的基线以供将来比较 | | `replay` | 针对记录的 session 进行测试 —— 不需要实时 server | | `verify` | 确认 server 更新没有破坏任何东西 | | `watch` | 检查 server 并查看自上次检查以来发生了什么变化 | | `diff_runs` | 在两次检查结果之间发现回归 | | `get_last_run` | 检索 server 以前的检查结果 | | `suggest_servers` | 发现与你的项目技术栈匹配的 MCP servers | 一个检查其他 AI 工具的 AI 工具。它是一个测试服务于工具的工具的工具。 ### 安全性 MCP server 在 AI 主机内运行，其中 LLM 选择要调用哪些工具。为防止 prompt 注入攻击： - **命令允许列表：** 仅允许 `npx`、`node`、`python`、`python3`、`uvx`、`docker`、`deno`、`bun` 作为基础可执行文件。CLI 没有限制。 - **路径验证：** 文件读取工具被限制在 runs/cassettes 目录中。 - **无任意执行：** 使用 CLI 执行不受限制的命令。 ### CLI 与 MCP：故意的差异 | 功能 | CLI | MCP Server | 原因 | |---------|-----|------------|-----| | `watch` | 轮询循环 | 单次检查 + diff | 请求/响应不支持长轮询 | | 交互式菜单 | 方向键导航 | 不可用 | MCP 没有交互式 UI | | 彩色输出 | `--no-color` 标志 | 始终为纯文本 | MCP 返回结构化内容 | | `report` | 渲染已保存的 artifact | 不可用 | Agents 直接读取 artifact | | `serve` | 启动 MCP server | 不适用 | 本身就是 MCP server | | `run` | 读取目标 config 文件 | 内联参数 | MCP tools 直接接受参数 | | `get_last_run` | 不可用（使用 `ls` + `diff`） | 可用 | 为 agents 提供便利 | ## 兼容性 适用于任何使用标准 transports 的 MCP server： | Transport | 示例 | 适配器 | |-----------|----------|---------| | **stdio**（大多数 servers） | [filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)、[memory](https://www.npmjs.com/package/@modelcontextprotocol/server-memory)、[context7](https://www.npmjs.com/package/@upstash/context7-mcp)、[brave-search](https://www.npmjs.com/package/@modelcontextprotocol/server-brave-search)、[sentry](https://www.npmjs.com/package/@sentry/mcp-server)、[notion](https://www.npmjs.com/package/@notionhq/notion-mcp-server)、[stripe](https://www.npmjs.com/package/@stripe/mcp) | `local-process` | | **HTTP/SSE**（远程） | [Cloudflare](https://developers.cloudflare.com/mcp/)、[Exa](https://exa.ai)、[Tavily](https://tavily.com) | `http` | | **Docker** | 所有 `@modelcontextprotocol/server-*` 镜像 | 通过 `docker run -i` 的 `local-process` | 需要 API keys 的 servers 通过目标 config 中的 `env` 进行工作。Python servers 通过 `uvx` 工作。有关已测试的 servers 和已知问题，请参见[完整兼容性矩阵](./docs/compatibility.md)。 ### 目标 config 文件 以获取更多控制（环境变量、元数据、自定义超时）： ``` { "targetId": "filesystem-server", "adapter": "local-process", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."], "timeoutMs": 15000, "skipInvoke": false } ``` ``` npx @kryptosai/mcp-observatory run --target ./target.json ``` ### HTTP / SSE 目标 ``` { "targetId": "my-remote-server", "adapter": "http", "url": "https://mcp.example.com/mcp", "authToken": "${MCP_SERVER_TOKEN}", "headers": { "X-Api-Key": "$MCP_SERVER_API_KEY" }, "timeoutMs": 15000 } ``` 目标 configs 支持 `${VAR}`, `$VAR`, 和 `env:VAR` 引用，可用于 `authToken`、`headers` 以及本地进程 `env` 值。 ## 对比 | 功能 | Observatory | [mcp-recorder](https://github.com/punkpeye/mcp-recorder) | [MCPBench](https://github.com/QuantGeekDev/mcpbench) | [mcp-jest](https://github.com/nicobailon/mcp-jest) | |---------|:-----------:|:----------:|:-------:|:-------:| | 自动发现 servers | ✅ | — | — | — | | 检查功能 | ✅ | — | ✅ | ✅ | | 调用工具 | ✅ | — | — | ✅ | | Schema 漂移检测 | ✅ | — | — | — | | 记录 / 回放 | ✅ | ✅ | — | — | | 针对 cassette 验证 | ✅ | — | — | — | | 响应快照 diff | ✅ | — | — | — | | 基准测试 / 延迟 | — | — | ✅ | — | | Jest 集成 | — | — | — | ✅ | | MCP 代理模式 | — | ✅ | — | — | | **作为 MCP server 工作** | **✅** | — | — | — | 每个工具都有其优势。Observatory 专注于回归检测和 CI 友好的工作流。mcp-recorder 非常适合用作透明代理。MCPBench 是性能基准测试的首选。如果你已经在使用 Jest 工作流，mcp-jest 是理想的选择。 ## 先前技术 记录/回放/验证模式受以下项目启发： - [VCR](https://github.com/vcr/vcr) (Ruby) —— 率先推出了基于 cassette 的 HTTP 记录/回放 - [Polly.js](https://github.com/Netflix/pollyjs) (Netflix) —— 用于 JavaScript 的 HTTP 交互记录 - [mcp-recorder](https://github.com/punkpeye/mcp-recorder) —— 特定于 MCP 的流量记录代理 - [MCPBench](https://github.com/QuantGeekDev/mcpbench) —— MCP server 基准测试 - [mcp-jest](https://github.com/nicobailon/mcp-jest) —— 用于 MCP servers 的 Jest 风格测试 ## 局限性 - 需要交互式 OAuth（例如 Google Drive）的 servers 需要在 Observatory 连接之前进行预身份验证 - 不支持自定义 WebSocket transports（例如 BrowserTools MCP） - 少数 servers 在初始化之前超时或关闭 —— 请参见[已知问题](./docs/known-issues.md)和[兼容性](./docs/compatibility.md) ## 贡献 请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 获取指南。最快的贡献方式是添加一个具有独特功能形态、更清晰的报告界面或更简洁的启动诊断的真实通过目标。 如果 Observatory 帮你避免了一次糟糕的部署，请考虑给它点个 [star](https://github.com/KryptosAI/mcp-observatory)。这有助于其他人发现该项目。

标签：GNU通用公共许可证, MCP, MITM代理, Node.js, 安全测试, 攻击性安全, 暗色界面, 自动化攻击