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로 실제 웹페이지 스크린샷을 캡처하여 시각적 증거로 저장합니다.

프로젝트 전체의 설계 규칙은 간단합니다: 감사 대상 시스템에서 증거를 읽고, 로컬 착륙 지점에만 증거를 씁니다. 감사 대상 시스템을 절대 수정하지 마십시오.

속도 선택

이 가이드를 처음부터 끝까지 따라 하면 한 번에 빌드할 수 있고, 5일에 걸쳐 나눌 수도 있습니다.

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 토큰 만들기

테스트할 저장소에 대한 세분화된 개인 액세스 토큰을 만드세요. 다음 권한만 부여하세요:

• Administration: read

• Contents: read

이미 더 넓은 토큰이 있다고 해서 재사용하지 마세요.

토큰을 .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 — 불투명한 id를 가진 SQLite 기반 StateStore.

• 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 1년과 GRC Engineering Club 멤버십 1년.

참여 방법:

1. 구독하세요.

2. MCP를 빌드하세요.

3. 빌드한 GitHub 저장소를 제출하세요.

적격한 제출물 중 무작위 추첨으로 한 명의 당첨자를 선정합니다. 프로젝트에 Built with BuildinginGRC 태그를 달아주세요.

최종 학습 확인

프로젝트를 완료했다고 하기 전에, 다음 다섯 가지를 자신의 말로 설명할 수 있어야 합니다:

1. MCP가 감사 대상 시스템에 대해 읽기 전용인 이유.

2. 서버가 증거를 저장하고 모든 것을 직접 반환하는 대신 collection_id를 반환하는 이유.

3. GitHub 토큰이 수집기에 필요한 권한만 가져야 하는 이유.

4. 404 또는 로그인 벽이 통제가 없다는 자동 증거가 아닌 이유.

5. API 결과가 증명하는 것과 스크린샷이 증명하는 것의 차이.

이것들을 설명할 수 있다면, 단순히 프로젝트를 복사한 것이 아니라 그 뒤에 있는 GRC 엔지니어링 결정을 이해한 것입니다.