grc-evidence-mcp — 分步构建指南

用 Python 构建一个真实的、只读的 GRC 证据收集 MCP，将其连接到 Claude Desktop，针对你自己的 GitHub 仓库进行测试，并可选地使用 Playwright 添加可视化证据捕获。

本指南的编写方式使得即使你从未构建过 MCP，也能完成构建。如果你已经熟悉 Python、终端、API 或 Claude Code，你可以加快速度，仅在需要时使用解释。

完成后的仓库： [GITHUB REPO LINK]

你要构建的内容

到结束时，你的 MCP 将能够：

1. 列出它知道的证据来源。

2. 为分支保护和 CODEOWNERS 收集真实的 GitHub 证据。

3. 将该证据映射到控制引用。

4. 将完整证据本地存储在 SQLite 中，并仅向 Claude 返回一个不透明的 collection_id。

5. 通过其 id 检索存储的证据收集。

6. 可选地使用 Playwright 捕获真实网页截图，并将其存储为视觉证据。

整个项目的设计规则很简单：从被审计系统读取证据；仅将证据写入你的本地着陆区。绝不修改被审计系统。

选择你的节奏

你可以按照指南从头到尾一次性完成构建，也可以分散在五天内完成。

Related MCP server: Change Trace MCP

5 天路径

第 1 天 — 设置 Claude Code 并构建基础

目标： 获得一个带有本地证据存储和一个可见工具的可用 MCP 项目。

操作：

• 安装 Claude Code。

• 创建一个空的项目文件夹。

• 在该文件夹内启动 Claude Code。

• 粘贴提示 1。

• 让 Claude Code 创建 Python 项目、基于 SQLite 的 StateStore 和 list_evidence_sources 工具。

• 在本地运行项目，并在继续之前解决任何安装错误。

完成标准： Claude Code 可以运行 MCP，并且 list_evidence_sources 存在。

第 2 天 — 将 MCP 连接到 Claude Desktop

目标： 让 Claude Desktop 看到你构建的 MCP。

操作：

• 将提示 2 粘贴到 Claude Code 中。

• 让 Claude Code 使用完整的服务器路径更新 Claude Desktop MCP 配置。

• 完全退出并重新打开 Claude Desktop。

• 打开一个新聊天并检查工具/锤子图标。

完成标准： list_evidence_sources 作为工具出现在 Claude Desktop 中。

第 3 天 — 添加真实的 GitHub 证据来源

目标： 用真实的只读 API 调用替换“仅演示”的思维。

操作：

• 粘贴提示 3。

• 创建一个细粒度的 GitHub 个人访问令牌，仅具有此构建所需的权限。

• 将 .env.example 复制为 .env 并在其中添加令牌。

• 切勿将令牌本身粘贴到 Claude Desktop 或 Claude Code 聊天中。

• 在环境/配置更改后重启 Claude Desktop。

完成标准： MCP 具有可用的 collect_evidence 工具，并且你的令牌可供服务器使用。

第 4 天 — 测试、检索和检查真实证据

目标： 证明你的 MCP 能针对你实际控制的仓库工作。

操作：

• 针对你自己的仓库运行 GitHub 测试提示。

• 复制返回的 collection_id。

• 要求 Claude Desktop 检索该收集。

• 审查分支保护和 CODEOWNERS 发现。

• 在将“缺失”结果视为控制差距之前，阅读 404 限制部分。

完成标准： 你已经检索到由实时 GitHub API 调用生成的存储记录。

第 5 天 — 添加视觉证据、清理并发布

目标： 将项目变成适合作品集的东西。

操作：

• 安装可选的 Playwright 附加组件和 Chromium。

• 添加或验证 collect_visual_evidence。

• 捕获你有权访问的真实页面的截图。

• 检索截图证据收集并检查其元数据。

• 清理你的 README，确认 .env 被忽略，并将项目推送到 GitHub。

• 如果你要参加挑战，请按照挑战说明提交你的仓库。

完成标准： 你的仓库解释了 MCP 的功能、如何运行它、其局限性是什么，并且不包含任何秘密。

开始之前

你需要：

• 一台带终端的计算机。

• 一个可以使用 Claude Code 的 Claude 账户。

• 用于桌面工具部分的 Claude Desktop。

• GitHub 账户访问权限，以及至少一个你被允许测试的仓库。

• Python 3.10 或更高版本。

• 如果你的机器还没有 Node.js，则需要安装它。

如果你是新手

你不需要在开始之前理解每一行 Python。在构建过程中，你的工作是理解每个组件的职责、输入什么数据、返回什么，以及安全边界在哪里。当 Claude Code 创建或更改文件时，如果你不确定，请在继续之前要求它用简单的英语解释该文件。

如果你更有技术经验

你可以检查生成的文件，在每个提示之间运行测试，并就实现选择向 Claude Code 提出质疑。完成的仓库是参考实现，而不是要求每个文件都完全相同。

第 1 步 — 安装 Claude Code

运行：

npm install -g @anthropic-ai/claude-code

如果因为缺少 Node.js 而出错，请安装 Node.js，然后再次运行该命令。

启动 Claude Code：

claude

首次运行会要求你登录。

此构建有意以终端为先。你不需要单独的编辑器来完成它。

第 2 步 — 创建你的项目文件夹

mkdir my-evidence-mcp
cd my-evidence-mcp
claude

从现在开始，按顺序将构建提示粘贴到 Claude Code 中。

提示 1 — 构建基础

Help me build a small MCP server in Python called grc-evidence-mcp, using
FastMCP over stdio, that I'll connect to Claude Desktop.

Purpose: read-only compliance evidence collection. It reads evidence FROM
systems and writes evidence TO a local landing zone — it must never modify
the audited system itself.

Build the foundation first, not real sources yet:

1. A StateStore class backed by SQLite — save(record) returns an opaque id,
   get(id) returns the record back. That id is the only handle anything
   else gets to a stored record.
2. One tool: list_evidence_sources — returns available sources and flags
   which ones are just stubs for now. Register one stub source so the
   list isn't empty.

Get this running and visible as a tool in Claude Code before we add
anything real.

此步骤教给你什么

StateStore 将对话与完整证据记录分开。服务器不是将所有收集到的证据直接交回给模型，而是将其本地存储并给 Claude 一个 id。Claude 可以在以后传递该 id，而不必自己重现证据。

检查点

在继续之前，要求 Claude Code 向你展示：

• MCP 服务器从哪里启动，

• StateStore 在哪里写入数据，

• list_evidence_sources 在哪里注册，

• 以及它用来确认服务器成功启动的命令。

提示 2 — 将其连接到 Claude Desktop

Add this server to my Claude Desktop config at ~/Library/Application
Support/Claude/claude_desktop_config.json. Use the full path to the
server, not just the command name, so it doesn't rely on my terminal's
PATH.

此路径是演练中使用的 macOS 路径。如果你使用其他操作系统，请要求 Claude Code 在编辑任何内容之前，为你的操作系统找到 Claude Desktop MCP 配置文件。

使用服务器命令的完整路径。Claude Desktop 不一定继承与你的终端相同的 PATH。

然后完全退出并重新打开 Claude Desktop。普通的窗口关闭或重新加载可能不会重新加载 MCP 配置。

打开一个新聊天并检查工具/锤子图标。你应该看到 list_evidence_sources。

如果你没有看到该工具

按顺序检查这些：

1. Claude Code 是否将配置保存到了正确的 Claude Desktop 配置文件？

2. 配置是否使用了完整的可执行文件/服务器路径？

3. MCP 是否从你的终端成功启动？

4. 你是否完全退出并重新打开了 Claude Desktop？

5. 重启后你是否打开了新聊天？

在基础工具可见之前，不要继续 GitHub 步骤。

提示 3 — 添加真实的 GitHub 来源

Now build the first real source: GitHub.

Add a collect_evidence(source_name, params) tool that, for source_name=
"github", checks branch protection status and CODEOWNERS presence on a
repo I specify (owner/repo/branch), using my own GitHub token
(read-only — Administration:read and Contents:read, nothing else).

Map each result to a control reference:
- branch protection present → SOC2-CC8.1, ISO27001-A.8.32
- CODEOWNERS present → SOC2-CC8.1, ISO27001-A.5.3

Return a collection_id from StateStore, not the raw evidence directly.
I want to run this against a real repo of mine and see actual results,
not sample data.

创建 GitHub 令牌

为你计划测试的仓库创建一个细粒度个人访问令牌。仅授予：

• 管理：读取

• 内容：读取

不要仅仅因为你已经有一个更广泛的令牌就重复使用它。

将令牌放入 .env

完成的仓库包含 .env.example。复制它：

cp .env.example .env

然后设置：

GITHUB_TOKEN=your_token_value_here

完成的仓库在 GitHub 收集器启动时加载此 .env 文件。

切勿将实际令牌粘贴到 Claude Desktop 或 Claude Code 消息中。 令牌属于环境，而不是对话。同时将 .env 保留在 .gitignore 中，以便永远不会提交它。

更改令牌/环境后，完全重启 Claude Desktop。

第 4 步 — 针对你自己的仓库进行测试

在 Claude Desktop 中，询问：

Check branch protection and CODEOWNERS on [your-username]/[your-repo],
branch main.

这应该对你命名的仓库进行真实的 GitHub API 调用。

该工具应返回一个 collection_id，而不是完整的原始记录。

然后询问：

Get the evidence collection with id [collection_id].

你现在应该看到存储的证据记录。

要检查什么

查找：

• 仓库和分支名称，

• 分支保护结果，

• CODEOWNERS 结果，

• 映射的控制引用，

• 底层证据/状态详细信息，

• 收集时间戳。

这是项目变得不仅仅是演示的时刻：你已经从你控制的真实系统收集并检索了证据。

重要限制 — GitHub 404 是模糊的

当分支保护未配置时，GitHub 可能返回 404，但 404 也可能是因为找不到仓库/分支，或者调用者没有足够的访问权限来确认设置。

当前的 GitHub 收集器保留响应详细信息，但仍将 404 结果记录为 present: false。不要自动将其视为已确认的控制差距。 人工审查员应验证结果是指“未配置”还是“无法确认”。

这种区别是良好 GRC 工程的一部分：“否”和“我不知道”不是相同的发现。

奖励 — 使用 Playwright 添加视觉证据

这是可选的。核心 MCP 在没有它的情况下也能工作。

完成的仓库使用带有无头 Chromium 的 Playwright。它不依赖于 Claude for Chrome 扩展。

安装可选包和浏览器：

pip install -e ".[screenshot]"
playwright install chromium

如果你从提示构建，请使用：

Add a tool collect_visual_evidence(url, subject) that opens the given URL
in headless Chromium via Playwright, captures a full-page screenshot, and
stores it the same way collect_evidence does — save the result to
StateStore, return only a collection_id, never the raw image bytes.

Classify the result conservatively: a successful page load can be stored
as present; a 401/403 authentication wall, a 404, or a navigation failure
must not be treated as proof that a control is missing. Record those as
indeterminate or error as appropriate. Burn a timestamp using the local
machine timezone into the screenshot metadata so a reviewer knows when
it was captured.

然后尝试：

Capture visual evidence of https://github.com/[your-username]/[your-repo]/settings/branches.

截图工具将 PNG 存储在 MCP 的本地截图目录下，并将其元数据存储在 StateStore 中。它为该截图证据记录返回一个新的 collection_id。

截图显示了捕获时页面的样子。它本身不是控制有效的证明。实现有意将身份验证墙和 404 视为不确定，而不是控制失败。视觉捕获是特定于页面的，不会截取你的本地桌面。

完成的仓库包含什么

• grc_evidence_mcp/store.py — 基于 SQLite 的 StateStore，带有不透明的 id。

• grc_evidence_mcp/server.py — MCP 工具注册和证据存储工作流。

• grc_evidence_mcp/github.py — 只读 GitHub API 证据收集器。

• grc_evidence_mcp/screenshot.py — 可选的 Playwright 截图收集器。

• .env.example — GitHub 令牌变量的安全模板。

• .gitignore — 防止本地秘密（如 .env）被提交。

• pyproject.toml — Python 依赖项和可选的截图附加组件。

核心工具：

• list_evidence_sources

• collect_evidence

• get_evidence_collection

可选奖励工具：

• collect_visual_evidence

按症状进行故障排除

claude 命令未找到

如果需要，安装 Node.js，然后重新运行 Claude Code npm 安装。

MCP 工具未出现在 Claude Desktop 中

验证配置位置和完整服务器路径，确认服务器在终端中启动，完全重启 Claude Desktop，然后打开一个新聊天。

GITHUB_TOKEN is not set

确认 .env 存在于项目根目录中，包含 GITHUB_TOKEN=...，并且你正在运行加载 .env 的更新项目。更改环境/配置后重启 Claude Desktop。

GitHub 返回 401

令牌无效、已过期或未被正确读取。

GitHub 返回 403

令牌/账户可能没有对仓库或设置所需的读取访问权限。

GitHub 返回 404

不要立即将其称为控制失败。确认仓库、分支、令牌访问权限以及底层 GitHub 响应。

Playwright 未安装

运行：

pip install -e ".[screenshot]"
playwright install chromium

截图显示登录页面

这仍然是一个真实的截图，但它不能证明控制状态。将其视为不确定，并在你有权这样做的情况下，先进行适当的身份验证，然后再试一次。

在发布你的仓库之前

• 确保 .env 不会被提交。

• 在仓库中搜索你的令牌或其他机密信息。

• 保留 README 中的限制说明部分。

• 说明 GitHub 调用是只读的。

• 说明截图展示的是捕获时的页面状态，而非控制措施的有效性。

• 提供足够的设置说明，使其他人能够复现构建过程。

• 在截图/示例中使用你自己的仓库，或对任何不应公开的内容进行脱敏处理。

挑战内容

为庆祝订阅者达到 100 人：$306 赠品 —— 一年 Claude Pro 会员加一年 GRC Engineering Club 会员资格。

参与方式：

1. 订阅。

2. 构建 MCP。

3. 提交你所构建内容的 GitHub 仓库。

将从符合条件的提交中随机抽取一名获胜者。请将你的项目标记为 Built with BuildinginGRC。

最终学习检查

在宣布项目完成之前，你应该能够用自己的话解释以下五点：

1. 为什么 MCP 对被审计系统是只读的。

2. 为什么服务器存储证据并返回 collection_id，而不是直接返回所有内容。

3. 为什么 GitHub 令牌应只拥有收集器所需的权限。

4. 为什么 404 或登录墙并不能自动证明某项控制措施缺失。

5. API 结果证明的是什么，截图证明的又是什么。

如果你能解释这些，说明你不仅仅是复制了一个项目——你理解了其背后的 GRC 工程决策。