md-github

claude.ai 사용자 지정 커넥터가 한 계정의 GitHub 저장소 전반에 걸쳐 정밀한 마크다운 편집을 수행할 수 있게 해주는 작은 MCP 서버로, 원하는 수의 변경 사항을 정확히 하나의 커밋으로 묶습니다.

Claude는 커넥터 양식에서 요구하는 OAuth 2.1 + DCR로 인증합니다. 각 사용자의 동의 시크릿(consent secret)은 해당 사용자 자신의 GitHub PAT와 자신의 계정을 선택합니다. 런타임 의존성이 전혀 없고, 데이터베이스도 없으며, 모든 상태는 메모리에 있습니다.

이것은 GitHub MCP 패스스루가 아닙니다. 일곱 개의 도구만 노출하며 그 외에는 아무것도 없습니다.

도구들

create_repo를 제외한 모든 도구는 repo — 단순 이름("notes") 또는 "owner/name" — 을 요구합니다. 세션은 overview(repo)로 시작하세요. 그 안에 무엇이 있는지 알려주는 유일한 호출입니다.

AGENT-TEMPLATE.md는 이 커넥터를 사용할 에이전트에 붙여넣을 지시 블록이며, ./connector-prompt.sh <repo>는 저장소 이름을 채워 넣고 클립보드에 복사합니다.

Related MCP server: brain-mcp

여러 저장소, 하나의 연결

하나의 정체성(identity)은 해당 PAT가 볼 수 있는 모든 저장소에 도달합니다 — 소유한 저장소, 협업 중인 저장소, 또는 조직을 통한 저장소. 구성할 소유자가 없습니다: 토큰은 이미 한 계정에 속해 있고 이미 자체 접근 권한을 지니고 있으므로, 토큰이 볼 수 있는 저장소 집합이 곧 네임스페이스입니다. 그것을 다시 구성하는 것은 토큰과 불일치할 수 있는 두 번째 진실 공급원(source of truth)을 만들 뿐입니다.

단순한 repo:"notes"는 그 보이는 집합을 기준으로 해석됩니다. repo:"owner/notes"는 조회를 건너뛰고 저장소를 직접 지정합니다. 두 소유자 아래에서 보이는 이름은 추측이 아니라 두 소유자를 모두 명시하는 거절입니다. 부팅 시 아무것도 열거되지 않으므로 create_repo로 만든 저장소는 재배포 없이 바로 다음 호출에서 해석됩니다.

기본 저장소는 없습니다

repo는 필수이며, 이를 생략한 호출은 추측이 아니라 오류입니다. 하나의 연결 뒤에 여러 프로젝트가 있으면 "그" 저장소라는 것은 존재하지 않으며, 그럴듯한 모든 폴백(fallback) — 첫 번째 저장소, 부팅 시 구성된 저장소, 마지막으로 건드린 저장소 — 은 모든 메시지가 여전히 성공처럼 읽히는 동안 편집이 잘못된 프로젝트에 들어가는 경로입니다. 잘못된 저장소에 대한 커밋은 expect_sha가 잡을 수 없는 유일한 실수이기도 합니다. 보호하는 blob이 아무도 보고 있지 않은 저장소에 있기 때문입니다.

연결이 도달할 수 있는 저장소를 나열하는 것은 없습니다 — 결과에도, 핸드셰이크에도 없습니다. 모든 도구는 저장소를 명시적으로 지명하므로 호출을 위해 명단이 필요하지 않으며, 범위가 넓은 PAT의 경우 모든 결과에 관련 없는 이름이 화면 가득 표시될 것입니다. 보이는 집합은 단순 이름을 해석하기 위해서만 GitHub에서 읽히며, 결코 출력되지 않습니다.

그 해석은 GET /user/repos를 읽지 GET /users/:owner/repos를 읽지 않습니다 — 후자는 자신의 계정에서도 공개 저장소만 반환하므로, 비공개 메모 저장소는 이름으로 전혀 해석되지 않을 것입니다. 5분 동안 캐시되며, 캐시 미스 시 실패하기 전에 한 번 다시 가져오므로, 방금 다른 곳에서 생성된 저장소도 여전히 해석됩니다.

PAT 외에는 연결을 좁히는 것이 없습니다

고정된 저장소도, 저장소 허용 목록도, 이름 접두사도, 브랜치 재정의도, 하위 트리 제한도 없습니다. 이전 버전에는 모두 있었습니다. 제거되었습니다. 각각은 PAT 자체의 범위 옆에 있는 두 번째 경계였으며, PAT와 불일치할 수만 있었고, 각각은 create_repo를 모순되게 만들었습니다 — 아직 존재하지 않는 저장소는 부팅 시 작성된 허용 목록에 있을 수 없기 때문입니다. 모든 저장소는 같은 이유로 자체 기본 브랜치를 사용합니다: 하나의 정체성은 여러 저장소에 걸쳐 있으며, 한 저장소에 존재하는 브랜치가 다음 저장소에 존재하는 경우는 드뭅니다.

PAT가 경계입니다. GitHub에서 실제로 유효한 곳에서 범위를 지정하세요.

각 저장소는 스스로를 문서화합니다

의도적으로 저장소 간 인덱스 파일이 없습니다. 각 저장소는 자신의 루트 INDEX.md에서 스스로를 문서화하며, 이 파일은 create_repo가 시드하는 파일이자 이 서버가 컨텍스트로 다시 공급하는 파일입니다. 한 저장소의 레지스트리는 진실이 존재하는 두 번째 장소가 되며, 누군가 커넥터 밖에서 프로젝트 이름을 바꾸는 첫 순간에 낡은 상태가 될 것입니다.

방향 잡기: overview

세션은 overview(repo)를 호출하여 시작합니다. 한 번의 왕복으로 해당 저장소의 루트 INDEX.md 원문 — 어떤 질문에 어떤 파일이 답하는지를 알려주는 라우터 — 과 저장소의 모든 경로 및 크기를 반환합니다. 이 프로젝트 자체의 컨텍스트 저장소에서는 152개 경로와 ~7k 토큰이며, 그 후 모델은 무엇이든 가져오기 전에 모든 것이 어디에 있고 얼마나 큰지 알게 됩니다.

그 외의 모든 것은 라우터를 따릅니다: 라우터가 가리키는 폴더 인덱스는 read_md({paths:[...]})로, 좁히기는 list_md({path_prefix, outline:true})로.

의도적으로 인라인되지 않은 것: 폴더 수준 인덱스 파일. 이 프로젝트의 컨텍스트 저장소에 있는 그중 하나는 66 KB입니다 — 모두 인라인하는 것은 그들이 설명하는 파일을 읽는 것보다 더 많은 비용이 듭니다.

다른 어떤 것도 결과에 인덱스를 첨부하지 않습니다. 이전 버전은 모든 도구 결과에 라우터를 덧붙였습니다. 13 KB 인덱스는 ~3.5k 토큰이므로, 10회 호출 세션은 하나의 정보에 대해 열 배를 지불했습니다. overview는 요청받았을 때 한 번 전달하며, 다른 어떤 것도 인덱스를 첨부하지 않습니다.

인덱스는 저장소 루트의 INDEX.md, index.md, README.md 중 첫 번째에서 읽히며, 2분 동안 캐시되고, 이 서버를 통한 모든 커밋에 의해 무효화됩니다 — 따라서 모델이 방금 다시 작성한 라우터가 낡은 상태로 다시 읽히는 일은 없습니다. 그 캐시와 이름 해석 목록이 이 서버가 캐시하는 유일한 것들입니다: 둘 중 어느 것도 blob SHA의 출처가 아니므로, 낡은 캐시가 잘못된 쓰기를 유발할 수 없습니다. 트리는 바로 그 이유로 의도적으로 캐시되지 않습니다.

누가 무엇을 편집했는가

각 사용자 자신의 PAT가 주입되므로 GitHub는 실제 인간을 커밋 작성자로 기록합니다 — 이것은 서버가 합성하는 것이 아닌 진짜 git 귀속(attribution)입니다. history는 "이 파일을 누가 변경했는가"에 답하고, show_commit은 실제 diff를 보여주며, git blame은 앱 밖에서 정상적으로 작동합니다.

알아둘 만한 두 가지 제한이 있습니다. history(path)는 이름 변경(rename)을 추적하지 않으므로, 이름 변경 이전의 커밋은 이전 경로 아래에 나열됩니다 — --follow 없는 git log와 동일합니다. 그리고 커밋의 파일 목록은 GitHub에서 300개 파일 단위로 페이지네이션됩니다. 도구는 부분 목록을 완전한 것으로 제시하는 대신 그 경계에 도달했음을 보고합니다.

여러 파일을 한 번에 읽기

read_md는 path 대신 paths: [...](최대 20개)를 받습니다. 그러면 다섯 개의 폴더 인덱스를 읽는 것이 다섯 번이 아니라 한 번의 왕복이 되며, max_bytes는 배치 전체가 공유하고 주어진 순서대로 소진하는 예산이 됩니다. 배치는 의도적으로 전부 아니면 전무(all-or-nothing)가 아닙니다: 존재하지 않는 경로는 자체 오류를 보고하는 동안 나머지는 여전히 반환됩니다. 전부 아니면 전무는 commit_edits의 속성입니다. 부분 결과는 손상된 저장소가 되기 때문입니다. 여기서는 왕복 한 번의 비용만 들 뿐입니다.

list_md는 파일을 읽지 않고 각 파일의 제목을 표시하기 위해 outline: true를 받습니다. 파일당 한 번의 읽기가 필요하므로 40개 파일을 초과하면 거부되며 좁히는 방법을 안내합니다.

저장소 만들기

create_repo({name, overview})는 연결의 소유자 아래에 저장소를 생성하고 # <name>과 overview로 구성된 INDEX.md로 시드합니다. overview는 한 줄 요약이 아니라 독자가 가장 먼저 도달하는 문서를 의미합니다 — 그것이 그 저장소의 라우터입니다.

GitHub에 대한 두 가지 효과 — 저장소 생성, 그다음 첫 커밋 — 는 하나의 트랜잭션이 될 수 없으므로 별도로 보고됩니다. 시드 커밋이 실패하면 결과는 저장소가 존재하고 비어 있다고 말하며, 작업을 완료할 정확한 commit_edits 호출을 명명합니다. 방금 만든 저장소를 삭제하지 않습니다: 오류를 정리하려고 네임스페이스를 파괴하는 것은 빈 저장소보다 훨씬 더 나쁜 실패입니다.

커밋이 없는 저장소에 쓰기

새로 만든 저장소는 GitHub의 git-data API를 통해서는 전혀 쓸 수 없습니다: blob, tree, 커밋 모두 409 Git Repository is empty.로 응답합니다. 작동하는 유일한 엔드포인트는 PUT /contents이며, 이는 브랜치와 초기 커밋을 한 요청으로 생성합니다 — 그래서 create_repo가 이것으로 시드하며, 이 서버가 PUT /contents를 호출하는 유일한 곳입니다.

정확히 하나의 파일을 쓰므로, 빈 저장소에 대한 배치가 담을 수 있는 것도 정확히 하나의 파일입니다. 다중 파일 배치는 두 커밋으로 나뉘는 대신 지침과 함께 거부됩니다. "한 번의 호출, 하나의 커밋"이 전체 설계가 의존하는 보장이기 때문입니다.

POST /user/repos는 요청 본문의 이름이 아니라 토큰이 속한 계정 아래에 생성합니다 — 따라서 다른 사람의 저장소에 단순히 협업만 하는 PAT는 자신의 계정에 새 저장소를 만듭니다. 결과는 이 서버가 가정한 이름이 아니라 GitHub가 반환한 full_name을 보고합니다. 바로 다음 호출에서 이름으로 해석됩니다.

저장소를 만들려면 Contents: Read and write보다 더 많은 것이 필요합니다. repo 범위의 클래식 PAT는 작동합니다. fine-grained PAT는 Administration: Read and write가 필요하며, 개인 계정에서는 저장소를 전혀 만들 수 없고(조직에서만 가능), 선택된 저장소로 제한된 경우 어차피 새 저장소에 쓸 수 없습니다 — 따라서 다중 저장소 사용은 All repositories를 원합니다. 403은 일반적인 contents 메시지 대신 정확히 이것을 말합니다.

commit_edits는 네 가지 연산을 받습니다:

start_commit / end_commit이 없는 이유

당연한 설계는 열었다가 나중에 메시지와 함께 닫는 스테이징 영역입니다. 그것은 의도적으로 거부되었습니다: 완료된 것처럼 보이는 작업이 게시되지 않은 채 놓여 있을 수 있는 공간을 만들기 때문에, "편집을 했는데 커밋하는 것을 잊었다"가 성립 가능해집니다. 세 번의 독립적인 설계 검토가 같은 결론에 수렴했습니다.

대신 스테이징 영역이 전혀 없다. commit_edits는 원자적이다. 즉, 여러 파일에 걸친 변경 사항 전체 배치가 한 번의 호출로 적용되고 푸시되거나, GitHub에 아무것도 전송되지 않는다. 에이전트는 자신의 컨텍스트(모델이 안정적으로 읽는 유일한 저장소)에 계획을 쌓아 두고, 단 한 번의 호출로 그것을 사용한다. 모든 도구 결과는 보류 중인 것이 없다는 상설 문구로 끝나므로, 무언가가 대기열에 있다는 믿음은 나중에 발견되도록 내버려 두지 않고 계속해서 반박된다.

또한 어떤 타임아웃에서도 자동 커밋 타이머가 없다. 유휴 타이머는 아무도 승인하지 않은 작업(철회된 삭제, 반쯤 끝난 재구성)을 게시한다. 원치 않는 커밋이 0개라는 것은 설계된 속성이지 누락이 아니다. 종료 시 서버는 버리는 것을 로그로 남기고 아무것도 커밋하지 않는다.

유지되는 상태의 유일한 조각은 실패 전용이다. 실패한 배치는 retry_ref로 30분간 보관되므로, 이미 압축되었을 수 있는 컨텍스트에서 큰 배치를 다시 입력할 필요가 없다. 그것은 이후의 모든 결과에서 공지되고, 어떤 성공이든 그것을 지우며, 결코 성공 영수증을 만들어 내지 못한다. 또한 그것이 작성된 저장소에 묶여 있어서, 다른 저장소에 재생하는 것은 거부된다. 그 편집들은 다른 저장소가 한 번도 포함한 적 없는 텍스트로 만들어졌기 때문이다.

원자성, 정확히는

commit_edits는 두 단계로 실행되며, 그 경계가 곧 보장이다.

• 계획 — 검증, 스냅샷 가져오기, expect_sha 확인, 모든 작업을 메모리 내 버퍼에 적용. 여기서 어떤 실패든 GET만 발행한 채 중단된다. "롤백"된 것이 아니다: 변경 요청은 결코 전송된 적이 없다. 배치의 모든 실패는 함께 보고되므로, 결함이 3개인 12개 작업 배치는 세 번이 아니라 한 턴만 소요된다.

• 실행 — 파일이 몇 개 바뀌었든 관계없이 세 개의 변경 요청(POST /git/trees, POST /git/commits, PATCH /git/refs)을 보낸다. 오직 마지막 PATCH만 관찰 가능하다.

따라서 어떤 호출 후에도 정확히 두 가지 관찰 가능한 상태만 존재한다. 커밋이 하나 있거나, 브랜치가 이전과 바이트 단위로 동일하거나.

expect_sha는 작업이 파일 전체를 파괴하는 경우, 즉 delete와 write mode=overwrite에서 정확히 요구된다. 관찰한 적 없는 파일을 통째로 교체하거나 제거할 수 없다. list_md는 전체 blob SHA를 반환하므로 삭제에는 콘텐츠 읽기가 절대 필요 없다.

동시성

콘텐츠는 커밋 시점에 단일 고정 스냅샷에서 다시 읽히므로, 읽기-수정-쓰기 창은 대화 길이가 아니라 약 1초다. PATCH ... force:false는 실제 서버 측 compare-and-swap이며, force: true는 어디에도 전송되지 않는다. 충돌이 발생하면 전체 계획이 새 헤드에 대해 다시 실행된다. 배치가 건드린 것 중 움직인 것이 없으면 조용히 적용되고, 움직인 것이 있으면 중단하고 덮어쓰는 대신 새 업스트림 콘텐츠를 인라인으로 반환한다.

환경

사람마다 번호가 매겨진 세 가지 변수:

이것이 사람별 구성의 전부다. 비밀 하나와 PAT 하나. 설정할 다른 것은 없다. PAT이 볼 수 있는 모든 저장소에 접근할 수 있고, 모든 호출은 자신이 작용할 저장소를 하나 지정한다.

USER<N>_NAME은 레이블이 아니라 정체성 키다. 누군가의 이름을 바꾸면 그들의 활성 토큰이 무효화되고 다시 연결해야 한다. PAT를 변경하면 재연결 없이 즉시 적용된다.

이전 배포에서 마이그레이션: USER<N>_REPO, USER<N>_OWNER, USER<N>_REPOS, USER<N>_REPO_PREFIX, USER<N>_BRANCH, USER<N>_ROOT 중 가지고 있는 것이 있으면 삭제하라. 더 이상 읽히지 않으며, 비밀 하나와 PAT 하나가 전체 구성이다.

claude.ai에서 연결

1. 설정(Settings) → 커넥터(Connectors) → 사용자 지정 커넥터 추가.

2. URL: <PUBLIC_URL>/mcp.

3. 클라이언트 ID와 시크릿은 비워 둡니다.

4. 연결을 누른 다음 자신의 USER<N>_SECRET을 입력합니다.

두 사람 모두 같은 URL을 추가합니다. 각자가 입력하는 비밀은 자신의 세션을 자신의 PAT과 저장소에 묶습니다.

테스트

npm install && npm run build
npm run test:unit       # 92 assertions: scanner, edit ops, byte fidelity — no network

# integration: 258 assertions against a stateful fake GitHub
USER1_NAME=alice USER1_SECRET=secret-alice USER1_PAT=pat-alice \
USER2_NAME=bob   USER2_SECRET=secret-bob   USER2_PAT=pat-bob \
USER3_NAME=frank USER3_SECRET=secret-frank USER3_PAT=pat-frank \
JWT_SECRET=test-jwt PUBLIC_URL=http://127.0.0.1:8787 PORT=8787 \
GITHUB_API_URL=http://127.0.0.1:8899 npm start &
npm run test:smoke

tests/fake-github.mjs는 상태를 가진 페이크(fake)로, 실제 git-blob-SHA 구현, 커밋 DAG, 토큰별 저장소 가시성(소유한 저장소와 협업 중인 저장소를 포함하므로 이름 확인이 실제로 무언가를 증명한다), 요청 로그, 주입 가능한 오류를 갖추고 있다. 따라서 서버를 통해 만들어진 커밋은 이후 읽기에서 관찰 가능하다. 이 덕분에 테스트 스위트는 실제로 중요한 것들을 검증할 수 있다. 즉, N번의 편집이 정확히 하나의 커밋과 PUT /contents 호출 0회를 만들어 내는지, 삭제가 직렬화 후에도 리터럴 "sha":null로 유지되는지, 모든 ref 업데이트에 force:false가 나타나는지, 실패한 배치가 변경 요청을 0개 남기는지, 동료의 동시 푸시가 절대 덮어써지지 않는지, 하나의 저장소를 지정한 호출이 다른 저장소로는 요청을 보내지 않는지, create_repo가 정확히 새 저장소에 정확히 하나의 커밋을 만들고 GitHub가 실제로 그 저장소를 만든 계정을 보고하는지, 그리고 실패 후 보류된 배치가 다른 저장소에 재생될 수 없는지.

배포

railway up --service mcp-github-proxy --detach

일부러 Dockerfile로 빌드한다. Railway의 기본 빌더(railpack)는 이 서비스를 failed to solve: secret RAILWAY_GIT_REPO_OWNER not found 오류로 실패시킨다. railpack이 생성한 플랜이 RAILWAY_GIT_* 빌드 시크릿을 선언하는데, 이 시크릿은 서비스 소스가 연결된 GitHub 저장소일 때만 존재하며 CLI tarball 업로드일 때는 존재하지 않는다.

참고

• 마크다운 스캐너는 실제 CommonMark 블록 스캐너이지 ^#{1,6} 정규식이 아니다. 프런트 매터의 닫는 ---는 유효한 setext H2 밑줄이므로, 단순한 스캔은 마지막 YAML 줄의 이름을 딴 유령 제목을 만들어 내고 에이전트는 프런트 매터로 바로 편집하게 될 것이다. 펜스 안의 제목, 들여쓰기된 코드, HTML 블록, 인용 블록은 올바르게 주소 지정이 불가능하다.

• 바이트 충실성은 의도적이다. CRLF 파일은 건드리지 않은 줄에서 CRLF를 유지하고, BOM은 분리해 두어 시작 위치에 고정된 old_string이 매칭될 수 있으며, 어떤 것도 절대 트리밍되지 않는다. 끝의 공백 두 개는 마크다운 하드 줄바꿈이다.

• read_md는 줄 번호 여백 없이 콘텐츠를 반환한다. 모델이 old_string에 복사하려는 텍스트 옆에 숫자가 있으면, 그 숫자가 정확히 그대로 검색어(needle)에 들어가기 때문이다. 줄 번호는 개요와 오류 메시지에만 나타난다. 즉, 아무것도 복사하지 않는 곳에만 나타난다.

• 짧은 파일이 전체로 반환되면 개요가 없다. 개요는 읽지 않은 파일의 지도다. 그것이 설명하는 열두 줄 위에 개요를 인쇄하는 것은 소음이다. 파일이 페이지를 넘길 만큼 길어지거나 창이 부분적이 되는 순간 개요는 다시 나타난다.

• GitHub 401은 도구 오류 텍스트로 표시되며 /mcp의 HTTP 401로는 절대 표시되지 않는다. 이전 프록시는 GitHub의 WWW-Authenticate를 전달했고, 이로 인해 claude.ai가 GitHub에 다시 인증하도록 보내져 재인증 루프가 발생했다. 실제 문제인 죽은 PAT는 보이지 않은 채였다.

• PAT이 실제 보안 경계이며, 이제 그것이 도달 범위를 결정하는 유일한 요소이기도 하다. 이 서버의 구성 중 그것을 좁히는 것은 없다. GitHub에서 PAT 자체의 범위를 지정하라. create_repo와의 긴장 관계에 유의하라. create_repo는 토큰이 만들어질 당시 존재하지 않았던 저장소에 도달할 수 있는 토큰을 요구하는데, 이는 선택된 저장소만 대상으로 하는 fine-grained PAT와 정반대다.