github-projects

Ein Plugin für Claude Code und Codex: Pydantic v2-Modelle, PEP 544-Protokolle und ein MCP-Server zur Verwaltung von GitHub Projects v2-Boards (z. B. github.com/users/<owner>/projects/<n>) – mit erstklassiger Unterstützung für die als Entwurf vorliegende HTTP QUERY-Methode.

Architektur

server.py      MCP server (mcp SDK v2, stdio) — 19 tools, structured output
   │  depends on
protocols.py   ProjectsBackend / GraphQLTransport (runtime-checkable Protocols)
   │  implemented by
service.py     GitHubProjectsService — GraphQL over the transport,
               project-id + field caching, string→typed field-value coercion
graphql.py     GraphQL documents (works for both user and org owners)
http.py        QueryClient — HTTP QUERY (draft-ietf-httpbis-safe-method-w-body)
               with per-origin capability memory and POST fallback
models.py      Frozen Pydantic v2 models, __typename-discriminated unions

• Die MCP-Ebene ist ausschließlich vom ProjectsBackend-Protokoll abhängig, sodass Backends austauschbar sind und Tests strukturell Fakes einsetzen.

• QueryClient sendet QUERY optimistisch, erfasst Accept-Query-Ankündigungen, unternimmt bei Transportfehlern einen erneuten Versuch (QUERY ist sicher und idempotent) und fällt pro Origin bei 405/501 dauerhaft auf POST zurück – er funktioniert also bereits heute mit GitHub und aktualisiert sich selbst, sobald GitHub die QUERY-Unterstützung ausliefert.

Einrichtung

Die primäre Laufzeitumgebung ist CPython 3.14.7 free-threaded (3.14.7t). Außerdem muss die gh-CLI mit dem project-Scope authentifiziert sein:

gh auth refresh -s project      # grants read + write for Projects v2

Tokens werden aus GITHUB_TOKEN / GH_TOKEN ermittelt, andernfalls aus gh auth token.

uv sync
uv run pytest             # 32 tests
uv run gh-projects-mcp    # run the server on stdio

Verwendung in Claude Code und Codex

Vom Repository-Stammverzeichnis aus:

# Claude Code (registered user-wide)
claude mcp add --scope user github-projects -- uv --directory "$PWD" run gh-projects-mcp

# Codex
codex mcp add github-projects -- uv --directory "$PWD" run gh-projects-mcp

Plugin-Manifeste befinden sich in .claude-plugin/plugin.json (wobei der MCP-Server über ${CLAUDE_PLUGIN_ROOT} deklariert ist) und .codex-plugin/plugin.json; ein Skill zur Nutzung für beide Hosts liegt in skills/github-projects/SKILL.md.

Werkzeuge