md-github

A small MCP server that lets a claude.ai custom connector do surgical markdown edits across the GitHub repositories of one account, batching any number of changes into exactly one commit.

Claude authenticates with OAuth 2.1 + DCR (which the connector form requires). Each person's consent secret selects their own GitHub PAT and their own account. Zero runtime dependencies, no database, all state in memory.

This is not a GitHub MCP passthrough. It exposes seven tools and nothing else.

The tools

Tool	What it does
overview	One call to orient in a repository: its root INDEX.md verbatim plus every file path with its size. Read-only.
list_md	Every .md file with byte size and git blob SHA, optionally with each file's heading outline. Read-only.
read_md	One file's exact bytes — or several files in one call — each with its blob SHA and a heading outline with line ranges. Read-only.
history	Recent commits — who authored each, when, and the message. Optional path filter. Read-only.
show_commit	One commit's author, message, and per-file diff. Read-only.
commit_edits	Applies an ordered list of edits and pushes them as one commit. The only tool that edits markdown.
create_repo	Creates a repository and seeds it with its own INDEX.md.

Every tool except create_repo requires repo — a bare name ("notes") or "owner/name". Start a session with overview(repo); it is the one call that tells you what is in there.

AGENT-TEMPLATE.md is the instruction block to paste at an agent that will use this connector, and ./connector-prompt.sh <repo> fills in the repository name and copies it to the clipboard.

Many repositories, one connection

An identity reaches every repository its PAT can see — owned, collaborated on, or via an organization. There is no owner to configure: a token already belongs to one account and already carries its own access, so the set of repositories it can see is the namespace. Configuring that again would only create a second source of truth that can disagree with the token.

A bare repo:"notes" is resolved against that visible set; repo:"owner/notes" skips the lookup and addresses the repository directly. A name visible under two owners is a refusal naming both, not a guess. Nothing is enumerated at boot, so a repository made by create_repo resolves on the very next call with no redeploy.

There is no default repository

repo is required, and a call that omits it is an error rather than a guess. With several projects behind one connection there is no such thing as "the" repository, and every plausible fallback — the first one, the one configured at boot, the one touched last — is a way for an edit to land in the wrong project while every message still reads like success. A wrong-repo commit is also the one mistake here that expect_sha cannot catch, because the blob it guards is in a repository nobody is looking at.

Nothing lists the repositories a connection can reach — not on results, not in the handshake. Every tool names its repository explicitly, so a roster is never needed to make a call, and for a broadly-scoped PAT it would put a screenful of irrelevant names on every single result. The visible set is read from GitHub only to resolve a bare name, and it is never printed.

That resolution reads GET /user/repos, not GET /users/:owner/repos — the latter returns only public repositories even for your own account, so a private notes repo would not resolve by name at all. It is cached for five minutes, and a miss refetches once before failing, so a repository created moments ago somewhere else still resolves.

Nothing narrows a connection except its PAT

There is no pinned repository, no repository allowlist, no name prefix, no branch override and no subtree confinement. Earlier versions had all of them; they were removed. Each was a second boundary sitting next to the PAT's own scopes, able only to disagree with it, and each made create_repo incoherent — a repository that does not exist yet cannot be on an allowlist written at boot. Every repository uses its own default branch, for the same reason: one identity spans many repositories, and a branch that exists in one rarely exists in the next.

The PAT is the boundary. Scope it in GitHub, where it actually holds.

Each repository documents itself

There is deliberately no cross-repository index file. Each repository documents itself in its own root INDEX.md, which is the file create_repo seeds and the file this server feeds back into context. A registry in one repo would be a second place the truth lives, and it would go stale the first time someone renamed a project outside the connector.

Orienting: overview

A session starts by calling overview(repo). One round trip returns that repository's root INDEX.md verbatim — the router that says which file answers which question — plus every path in the repository with its size. On this project's own context repo that is 152 paths and ~7k tokens, after which the model knows where everything is and how big it is before fetching anything.

Everything else follows from the router: read_md({paths:[...]}) for the folder indexes it points at, list_md({path_prefix, outline:true}) to narrow.

Deliberately not inlined: the folder-level index files. One of them in this project's context repo is 66 KB — inlining them all would cost more than reading the files they describe.

Nothing else ever attaches an index to a result. An earlier version appended the router to every tool result; a 13 KB index is ~3.5k tokens, so a ten-call session paid for one piece of information ten times. overview delivers it once, when asked, and nothing else ever attaches one.

The index is read from the first of INDEX.md, index.md, README.md at the repository root, cached for two minutes, and invalidated by any commit through this server — so a router the model just rewrote is never read back stale. That cache and the name-resolution list are the only things this server caches: neither is ever a source of a blob SHA, so a stale one cannot cause a wrong write. The tree is deliberately not cached, for that reason.

Who edited what

Each person's own PAT is injected, so GitHub records the real human as the commit author — this is genuine git attribution, not anything the server synthesizes. history answers "who changed this file", show_commit shows the actual diff, and git blame works normally outside the app.

Two limits worth knowing. history(path) does not follow renames, so commits from before a rename are listed under the old path — same as git log without --follow. And a commit's file list is paginated by GitHub at 300 files; the tool reports when it has hit that boundary rather than presenting a partial list as complete.

Reading several files at once

read_md takes paths: [...] (up to 20) instead of path. Reading five folder indexes is then one round trip rather than five, and max_bytes becomes a budget shared across the batch and spent in the order given. The batch is deliberately not all-or-nothing: a path that does not exist reports its own error while the others still return. All-or-nothing is a property of commit_edits, where a partial result would be a corrupt repository; here it would only cost a round trip.

list_md takes outline: true to show each file's headings without reading it. That is one read per file, so it is refused above 40 files and says how to narrow.

Creating a repository

create_repo({name, overview}) creates the repository under the connection's owner and seeds it with an INDEX.md of # <name> plus the overview. The overview is meant to be the document a reader lands on first, not a one-line summary — it is that repository's router.

Its two effects on GitHub — the repository, then its first commit — cannot be one transaction, so they are reported separately. If the seeding commit fails, the result says the repository exists and is empty, and names the exact commit_edits call that finishes the job. It does not delete the repository it just made: destroying a namespace to tidy up an error is a far worse failure than an empty repository.

Writing to a repository that has no commits

A brand-new repository cannot be written through GitHub's git-data API at all: blobs, trees and commits all answer 409 Git Repository is empty. The only endpoint that works is PUT /contents, which creates the branch and the initial commit in one request — so that is what create_repo seeds with, and it is the only place this server ever calls PUT /contents.

It writes exactly one file, so exactly one file is what a batch into an empty repository may carry. A multi-file batch is refused with instructions rather than split across two commits, because "one call, one commit" is the guarantee the whole design rests on.

POST /user/repos creates under the account the token belongs to, not under a name in the request body — so a PAT that merely collaborates on someone else's repositories creates new ones in its own account. The result reports the full_name GitHub returned rather than a name this server assumed. It resolves by name on the very next call.

Creating a repository needs more than Contents: Read and write. A classic PAT with the repo scope works; a fine-grained PAT needs Administration: Read and write, cannot create repositories in a personal account at all (only in an organization), and if it is limited to selected repositories it could not write to the new repository anyway — so multi-repo use wants All repositories. A 403 says exactly this instead of the generic contents message.

commit_edits takes four operations:

op	Fields	Notes
write	path, content, mode	create (default), overwrite (needs expect_sha), append.
str_replace	path, old_string, new_string, replace_all	Exact byte match; must be unique unless replace_all.
edit_section	path, heading, mode, content	replace / append / prepend / delete a section addressed by its heading.
delete	path, expect_sha	Removes a file.

Why there is no start_commit / end_commit

The obvious design is a staging area you open and later close with a message. It was rejected deliberately: it creates a place where finished-looking work can sit unpublished, so "I made the edits and forgot to commit" becomes constructible. Three independent design reviews converged on the same conclusion.

Instead there is no staging area at all. commit_edits is atomic — a whole batch of changes across many files, applied and pushed in one call, or nothing sent to GitHub whatsoever. The agent accumulates its plan in its own context (the one store a model reads reliably) and spends it in a single call. Every tool result ends with a standing line saying nothing is pending, so the belief that something is queued is refuted continuously rather than left to be discovered later.

There is also no auto-commit timer, at any timeout. An idle timer publishes work nobody approved — a retracted deletion, a half-finished restructure. Zero unwanted commits is a designed property, not an omission. On shutdown the server logs what it is dropping and commits nothing.

The one piece of retained state is failure-only: a batch that fails is held for 30 minutes as a retry_ref so a large batch need not be retyped from a context that may already have been compacted. It is announced on every subsequent result, it is cleared by any success, and it can never produce a success receipt. It is also bound to the repository it was authored against: replaying it into another one is refused, because those edits were built from text the other repository has never contained.

Atomicity, precisely

commit_edits runs two phases and the boundary is the guarantee.

• Plan — validation, snapshot fetch, expect_sha checks, applying every op to in-memory buffers. Any failure aborts here having issued only GETs. Not "rolled back": no mutative request was ever sent. All failures in a batch are reported together, so a 12-op batch with 3 defects costs one turn rather than three.
• Execute — three mutative requests (POST /git/trees, POST /git/commits, PATCH /git/refs) regardless of how many files changed. Only the final PATCH is observable.

So after any call there are exactly two observable states: one commit exists, or the branch is byte-identical to before.

expect_sha is required exactly where an operation destroys a whole file — delete and write mode=overwrite. You cannot wholesale replace or remove a file you never observed. list_md returns full blob SHAs, so a deletion never needs a content read.

Concurrency

Content is re-read at commit time from a single pinned snapshot, so the read-modify-write window is about a second rather than the length of a conversation. PATCH ... force:false is a real server-side compare-and-swap; force: true is never sent anywhere. On a collision the whole plan re-runs against the new head: if nothing the batch touches moved, it lands silently; if something did, it stops and returns the fresh upstream content inline rather than clobbering.

Environment

Var	Notes
JWT_SECRET	Signs the tokens this server issues.
PUBLIC_URL	This service's own base URL, no trailing slash.
PORT	Pinned to 3000 to match the generated Railway domain.
GITHUB_API_URL	Defaults to https://api.github.com. The testing seam.

One numbered triple per person:

Var	Notes
USER<N>_SECRET	What that person types on the consent page. Identity is the secret.
USER<N>_PAT	That person's GitHub PAT. Used only for their own requests, and the whole of their reach.
USER<N>_NAME	Optional label, defaults to user<N>. Becomes the token sub.

That is the entire per-person configuration: a secret and a PAT. There is nothing else to set — every repository the PAT can see is reachable, and every call names the one it acts on.

USER<N>_NAME is an identity key, not a label: renaming someone invalidates their live tokens and they must reconnect. Changing their PAT takes effect immediately with no reconnect.

Migrating an older deployment: delete USER<N>_REPO, USER<N>_OWNER, USER<N>_REPOS, USER<N>_REPO_PREFIX, USER<N>_BRANCH and USER<N>_ROOT if you have any of them. None are read any more, and a secret plus a PAT is the whole configuration.

Connect from claude.ai

1. Settings → Connectors → Add custom connector.
2. URL: <PUBLIC_URL>/mcp.
3. Leave client ID and secret empty.
4. Connect, then type your own USER<N>_SECRET.

Both people add the same URL; the secret each types binds their session to their own PAT and repo.

Tests

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 is a stateful fake with a real git-blob-SHA implementation, a commit DAG, per-token repository visibility (owned plus collaborated-on, so name resolution proves something), a request log and injectable faults, so a commit made through the server is observable by a later read. It is what lets the suite assert the things that actually matter: that N edits produce exactly one commit and zero PUT /contents calls, that a deletion survives serialization as a literal "sha":null, that force:false appears on every ref update, that a failed batch leaves zero mutative requests, that a colleague's concurrent push is never clobbered, that a call naming one repository issues requests to no other, that create_repo produces exactly one commit in exactly the new repository and reports the account GitHub really created it under, and that a batch held after a failure cannot be replayed into a different repository.

Deploying

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

Builds via the Dockerfile, deliberately. Railway's default builder (railpack) fails this service with failed to solve: secret RAILWAY_GIT_REPO_OWNER not found — its generated plan declares the RAILWAY_GIT_* build secrets, which only exist when the service's source is a connected GitHub repo, not a CLI tarball upload.

Notes

• The markdown scanner is a real CommonMark block scanner, not a ^#{1,6} regex. Front matter's closing --- is a legal setext H2 underline, so a naive scan invents a phantom heading named after the last YAML line and an agent would edit straight into the front matter. Headings inside fences, indented code, HTML blocks and blockquotes are correctly not addressable.
• Byte fidelity is deliberate: CRLF files keep CRLF on untouched lines, a BOM is split off so a start-anchored old_string can match, and nothing is ever trimmed — two trailing spaces are a markdown hard line break.
• read_md returns content without line-number gutters, because numbers next to text the model is about to copy into old_string is exactly how a gutter ends up in the needle. Line numbers appear only in outlines and error messages — places nothing is copied from.
• A short file returned whole gets no outline. An outline is a map of a file you have not read; printing one above the twelve lines it describes is noise. It reappears the moment the file is long enough to page through, or the window is partial.
• A GitHub 401 is surfaced as tool-error text and never as an HTTP 401 from /mcp. The old proxy forwarded GitHub's WWW-Authenticate, which sent claude.ai to re-authenticate against GitHub and produced a reauth loop while the real problem — a dead PAT — stayed invisible.
• The PAT is the real security boundary, and now it is also the only one that decides reach: nothing in this server's configuration narrows it. Scope the PAT itself in GitHub. Note the tension with create_repo: it wants a token that can reach repositories that did not exist when the token was made, which is the opposite of a selected-repositories fine-grained PAT.