grc-evidence-mcp — пошаговое руководство по сборке

Создайте настоящий MCP-сервер для сбора GRC-доказательств (только чтение) на Python, подключите его к Claude Desktop, протестируйте на собственном репозитории GitHub и, при желании, добавьте захват визуальных доказательств с помощью Playwright.

Это руководство написано так, чтобы вы могли завершить сборку, даже если никогда раньше не создавали MCP. Если вы уже уверенно работаете с Python, терминалом, API или Claude Code, вы можете двигаться быстрее и обращаться к объяснениям только по мере необходимости.

Готовый репозиторий: [GITHUB REPO LINK]

Что вы создаёте

К концу ваш MCP сможет:

1. Перечислять известные ему источники доказательств.

2. Собирать реальные доказательства из GitHub для защиты веток (branch protection) и CODEOWNERS.

3. Сопоставлять эти доказательства с контрольными ссылками.

4. Хранить полные доказательства локально в SQLite и возвращать Claude только непрозрачный collection_id.

5. Получать сохранённую коллекцию доказательств по её идентификатору.

6. Опционально делать реальный скриншот веб-страницы с помощью Playwright и сохранять его как визуальное доказательство.

Правило дизайна для всего проекта простое: читайте доказательства ИЗ аудируемой системы; записывайте доказательства ТОЛЬКО в свою локальную зону приземления. Никогда не изменяйте аудируемую систему.

Выберите свой темп

Вы можете собрать проект за один присест, следуя руководству сверху вниз, или растянуть на пять дней.

Related MCP server: Change Trace MCP

Путь на 5 дней

День 1 — Настройте Claude Code и создайте фундамент

Цель: получить рабочий MCP-проект с локальным хранилищем доказательств и одним видимым инструментом.

Действия:

• Установите Claude Code.

• Создайте пустую папку проекта.

• Запустите Claude Code внутри папки.

• Вставьте Prompt 1.

• Позвольте Claude Code создать Python-проект, StateStore на SQLite и инструмент list_evidence_sources.

• Запустите проект локально и устраните ошибки установки, прежде чем двигаться дальше.

Готово, когда: Claude Code может запустить MCP, и list_evidence_sources существует.

День 2 — Подключите MCP к Claude Desktop

Цель: сделать так, чтобы Claude Desktop видел созданный вами MCP.

Действия:

• Вставьте Prompt 2 в Claude Code.

• Позвольте Claude Code обновить конфигурацию MCP в Claude Desktop, используя полный путь к серверу.

• Полностью закройте Claude Desktop и откройте его заново.

• Откройте новый чат и проверьте значок инструментов/молотка.

Готово, когда: list_evidence_sources появляется как инструмент в Claude Desktop.

День 3 — Добавьте реальный источник данных GitHub

Цель: заменить мышление «только демо» на реальный вызов API в режиме чтения.

Действия:

• Вставьте Prompt 3.

• Создайте fine-grained персональный токен доступа 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, которая может использовать Claude Code.

• 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 по порядку.

Prompt 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 идентификатор. Claude может передать этот идентификатор позже, не воспроизводя сами доказательства.

Контрольная точка

Прежде чем двигаться дальше, попросите Claude Code показать вам:

• где запускается MCP-сервер,

• куда StateStore записывает данные,

• где зарегистрирован list_evidence_sources,

• и команду, которую он использовал для подтверждения успешного запуска сервера.

Prompt 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 найти файл конфигурации MCP для Claude Desktop в вашей операционной системе, прежде чем что-либо редактировать.

Используйте полный путь к команде сервера. Claude Desktop не обязательно наследует тот же PATH, что и ваш терминал.

Затем полностью закройте Claude Desktop и откройте его заново. Обычное закрытие окна или перезагрузка могут не перезагрузить конфигурацию MCP.

Откройте новый чат и проверьте значок инструментов/молотка. Вы должны увидеть list_evidence_sources.

Если вы не видите инструмент

Проверьте по порядку:

1. Сохранил ли Claude Code конфигурацию в правильный файл конфигурации Claude Desktop?

2. Использует ли конфигурация полный путь к исполняемому файлу/серверу?

3. Запускается ли MCP успешно из вашего терминала?

4. Полностью ли вы закрыли и заново открыли Claude Desktop?

5. Открыли ли вы новый чат после перезапуска?

Не переходите к шагу GitHub, пока базовый инструмент не станет видимым.

Prompt 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

Создайте fine-grained персональный токен доступа для репозитория, который вы планируете тестировать. Предоставьте только:

• Administration: read

• Contents: read

Не используйте более широкий токен только потому, что он у вас уже есть.

Поместите токен в .env

В готовом репозитории есть .env.example. Скопируйте его:

cp .env.example .env

Затем установите:

GITHUB_TOKEN=your_token_value_here

Готовый репозиторий загружает этот файл .env при запуске сборщика GitHub.

Никогда не вставляйте фактический токен в сообщение 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,

• сопоставленные контрольные ссылки,

• базовые детали доказательств/статуса,

• временную метку коллекции.

Это момент, когда проект становится больше, чем демо: вы собрали и получили доказательства из реальной системы, которой управляете.

Важное ограничение — 404 на GitHub неоднозначны

GitHub может вернуть 404, когда защита веток не настроена, но 404 также может возникнуть, потому что репозиторий/ветка не найдены или у вызывающего недостаточно доступа для подтверждения настройки.

Текущий сборщик GitHub сохраняет детали ответа, но всё равно записывает результат 404 как present: false. Не рассматривайте это автоматически как подтверждённый контрольный пробел. Человек-проверяющий должен убедиться, означает ли результат «не настроено» или «не удалось подтвердить».

Это различие — часть хорошей GRC-инженерии: «нет» и «я не знаю» — это не одно и то же.

Бонус — Добавьте визуальные доказательства с Playwright

Это необязательно. Основной MCP работает и без этого.

В готовом репозитории используется Playwright с headless Chromium. Он не зависит от расширения 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 — StateStore на SQLite с непрозрачными идентификаторами.

• 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-репозиторий того, что вы собрали.

Один победитель будет выбран случайным образом из соответствующих заявок. Отметьте свой проект тегом BuiltinginGRC.

Финальная проверка знаний

Прежде чем считать проект завершённым, вы должны уметь объяснить своими словами следующие пять вещей:

1. Почему MCP доступен только для чтения по отношению к аудируемой системе.

2. Почему сервер сохраняет доказательства и возвращает collection_id вместо того, чтобы возвращать всё напрямую.

3. Почему у GitHub-токена должны быть только те разрешения, которые нужны сборщику.

4. Почему 404 или страница входа не являются автоматическим доказательством отсутствия контроля.

5. Что доказывает результат API в отличие от того, что доказывает скриншот.

Если вы можете это объяснить, вы сделали больше, чем скопировали проект, — вы понимаете инженерные решения GRC, стоящие за ним.