feat: REST API layer for github-projects-client + MCP coordinator refactor#40
Merged
Conversation
Specifies a stateless REST API that wraps the existing Python client, enabling LLM agents to fetch board data directly to disk via curl instead of piping through MCP context. Audit logging moves from filozzy-mcp into the API layer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Phase 0 (research) and Phase 1 (design) artifacts: plan, research decisions, data model, REST API contracts, and quickstart guide. API server lives inside github-projects-client as a server/ subpackage rather than a separate package. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Generate Phase 2 tasks (32 total) organized by user story. Update plan and research to use FastAPI — auto-generates OpenAPI spec from route definitions, eliminating a separate spec file. MCP coordinator will reference the OpenAPI URL for agent discoverability. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…coordinator Add a FastAPI REST API server inside github-projects-client that exposes board operations as HTTP endpoints callable via curl. This enables agents to pipe board data directly to disk without entering LLM context. Key changes: - New server/ subpackage with FastAPI app, auth, routes, models, formats - Audit log moved from filozzy-mcp to github-projects-client with caller/endpoint fields - Query syntax reference extracted to shared query_syntax.py (single source of truth) - Rich OpenAPI endpoint descriptions with full parameter docs - filozzy-mcp refactored to thin coordinator (get_board_context tool only) - filozzy-mcp no longer requires GITHUB_TOKEN - .mcp.json updated: removed GITHUB_TOKEN from filozzy, added API_BASE_URL - README rewritten with tool comparison table and project tenet - Future ideas added for removing compact format and field options endpoint Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace all MCP tool references (list_board_items, get_board_item, set_board_item_field, bulk_set_board_item_field, list_board_field_options) with REST API curl patterns and gh CLI equivalents. Agent now discovers board identity and API base URL from get_board_context (FilOzzy MCP coordinator) rather than hardcoded values. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…gs, add tests
- Consolidate single-item and bulk mutation endpoints into one:
PUT /items/field/{field_name} (was separate PUT /items/{ref}/fields/{name}
and PUT /fields/{name}/bulk)
- Remove field_name body override from BulkSetFieldRequest (URL-encoding
spaces in field names works fine)
- Fix iteration fields (Cycle) returning "" — REST API returns title as
{"raw": "...", "html": "..."} not a plain string
- Fix empty-string stripping that silently dropped fields with no value
from responses (build_display_items and get_item route)
- Add sub-issues progress rendering ("N/N" instead of silent data loss)
- Add dev mode server entry point (github-projects-api-dev) with auto-reload
- Add mutation route tests (9 tests) with real API response shapes
- Rewrite item unit tests to use real REST API field shapes (33 tests)
- Update README, spec contract, and filoszy MCP server docs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rule changes: - R-SL-007: Add "skip if" for new commits after changes-requested review (consistent with R-PR-006 case 3 — avoids cross-rule conflict) - R-FC-001: Verify assignment persisted (API silently succeeds without write access); exclude bot-created Done items from assignee requirement - R-PR-006: Clarify cases 2/3 with timestamp comparison language and R-SL-001 re-request exception note - Phase 2 trigger: Tighten guidance — skip when PR is already in correct status with no competing rule trigger Sweep playbook: - Add foc_gh_get/foc_gh_put helper scripts (Stage 0) with env.sh for non-sensitive config; token resolved at runtime via gh auth token - Switch to dev mode server start (github-projects-api-dev, auto-reload) - Fix @ in sweep dir name (breaks zsh PATH lookup) - Note fresh-shell behavior: always use full path "$SWEEP/bin/foc_gh_get" - Fix jq -e pagination check (exit code 1 cancels parallel siblings) - Add R-PR-002/003/004 to single-pass jq action list examples - Add guidance to write action lists to disk, not context Agent prompt: - Consolidate pitfalls — move procedural details to playbook, keep only non-obvious gotchas (fresh shell, jq -e, context bucketing) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
Author
|
Lots of changes here. I think the key thing to look at is the READMEs, which attempt to provide justification for any of this code. Ideally a lot of this is code that wouldn't need to be written and we could just have a ruleset that can use out-of-the-box tools... |
Tests asserted "/fields" in context output but endpoint was renamed
from /fields/{name}/bulk to /items/field/{name}. Update assertions
to match.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR introduces a FastAPI-based REST server inside github-projects-client to expose board read/mutation operations as stateless HTTP endpoints, and refactors filozzy-mcp into a thin coordinator that only returns board/API usage context (no GitHub API calls). It also updates sweep playbooks/rules/docs to use the new API-first workflow and adds/updates tests around the new behavior.
Changes:
- Add a REST API server (
github_projects_client.server) with items/fields/mutations endpoints, auth dependency, formatting helpers, and centralized error handling. - Move/extend mutation audit logging into
github-projects-clientand refactorfilozzy-mcpto a singleget_board_contextcoordinator tool. - Update board sweep playbooks/rules/docs and expand tests to cover new API shapes + field formatting fixes.
Reviewed changes
Copilot reviewed 37 out of 41 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| specs/005-rest-api-layer/tasks.md | Implementation task breakdown for REST API layer + MCP refactor. |
| specs/005-rest-api-layer/spec.md | Feature spec and acceptance scenarios for the REST API + coordinator. |
| specs/005-rest-api-layer/research.md | Framework/auth/logging design decisions and tradeoffs. |
| specs/005-rest-api-layer/quickstart.md | Curl-first quickstart for running/using the REST API and coordinator. |
| specs/005-rest-api-layer/plan.md | Repository structure + execution plan for the feature. |
| specs/005-rest-api-layer/data-model.md | Request/response entities and audit log schema definition. |
| specs/005-rest-api-layer/contracts/rest-api.md | REST endpoint contract and error/response shapes. |
| specs/005-rest-api-layer/checklists/requirements.md | Spec quality checklist completion. |
| github-projects-client/tests/test_mutations_route.py | Unit tests for consolidated mutation endpoint and audit logging behavior. |
| github-projects-client/tests/test_items_unit.py | Updated unit tests using real REST API response shapes + formatting fixes. |
| github-projects-client/README.md | Document REST API server usage and positioning vs GitHub tools. |
| github-projects-client/pyproject.toml | Add FastAPI/uvicorn deps and server entry points; add httpx for tests. |
| github-projects-client/github_projects_client/server/routes/mutations.py | Mutation + audit-log endpoints (bulk/single via consolidated route). |
| github-projects-client/github_projects_client/server/routes/items.py | Item list/get/view endpoints with formatting + query syntax reference. |
| github-projects-client/github_projects_client/server/routes/fields.py | Field listing and field options endpoints. |
| github-projects-client/github_projects_client/server/routes/init.py | Route package initializer. |
| github-projects-client/github_projects_client/server/models.py | Pydantic request/response models for OpenAPI. |
| github-projects-client/github_projects_client/server/formats.py | Compact/columnar formatting + display-item sanitization helper. |
| github-projects-client/github_projects_client/server/auth.py | Bearer token extraction dependency + requests session builder. |
| github-projects-client/github_projects_client/server/app.py | FastAPI app factory, router registration, and exception mapping. |
| github-projects-client/github_projects_client/server/init.py | Server package marker. |
| github-projects-client/github_projects_client/query_syntax.py | Shared query syntax reference (API + coordinator). |
| github-projects-client/github_projects_client/items.py | Field-value formatting fixes (iteration title dict; sub-issues progress). |
| github-projects-client/github_projects_client/audit_log.py | Audit log implementation (env-configurable path; caller/endpoint fields). |
| foc-board-rules/sweep-playbook.md | Update sweep workflow to use curl + helper scripts + REST API. |
| foc-board-rules/sweep-agent-prompt.md | Update agent instructions for coordinator + REST API workflow. |
| foc-board-rules/status-lifecycle.md | Update/clarify rules to reference REST API endpoints and add skip logic. |
| foc-board-rules/README.md | Update rule application guidance to reference coordinator + REST API. |
| foc-board-rules/pr-hygiene.md | Clarify R-PR-006 cases with timestamp comparison language. |
| foc-board-rules/future-ideas.md | Update/retire ideas based on new REST-API-to-disk architecture. |
| foc-board-rules/field-completeness.md | Update rules to reference REST API and add assignment-persistence guidance. |
| filozzy-mcp/uv.lock | Lockfile updates reflecting dependency changes. |
| filozzy-mcp/tests/test_integration.py | Replace live GitHub API integration tests with coordinator tool checks. |
| filozzy-mcp/tests/test_format.py | Replace formatting tests with coordinator output tests. |
| filozzy-mcp/README.md | Reposition to coordinator-only server; update setup/config. |
| filozzy-mcp/pyproject.toml | Remove requests dep; ensure editable client source configured. |
| filozzy-mcp/filozzy_mcp/server.py | Remove GitHub API tools; add get_board_context tool and shared query docs. |
| CLAUDE.md | Add repo guidance: prefer GitHub-supported tools where possible. |
| .gitignore | Broaden ignore pattern for .mcp.json*. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Fix typo "Ssee" → "See" in github-projects-client README - Fix typo "githut-projects-turbo" → "github-projects-client" in filozzy-mcp README - Stop leaking exception details in catch-all error handler — return generic "Internal server error" message, log full exception server-side Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
rjan90
reviewed
May 11, 2026
rjan90
reviewed
May 11, 2026
Incorporates 7 improvements observed during a live sweep: - Fix dependabot author format in jq examples (app/dependabot, not [bot]) - Add title-based exclusion for bot/release PRs in R-PR-006 filter - Add Phase 2 skip heuristic for In Progress + CHANGES_REQUESTED - Note that ~75% of unassigned PRs are bots (filter before reading) - Narrow unlinked PR discovery to current cycle (low historical yield) - Document empty objects in cross-reference GraphQL results - Add pitfall: verify assignee mutations stuck (GitHub silent 201) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ub errors Audit log endpoint now validates bearer tokens against GitHub API before returning entries (FR-008). GraphQL auth/scope failures surface as 401 with actionable message instead of being swallowed as generic 500s. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add timing instrumentation helper (foc_timer) to Stage 0 - Add Phase 2 jq summary template — never print raw review JSON into context - Add single-pass action bucketing with counts-first verification - Add field-gap jq filtering example (bots, external repos) - Add Stage 5 unassigned-issue investigation with cross-reference priority order - Consolidate prompt pitfalls 9-13 into two lean entries pointing to playbook Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
github-project-automation
Bot
moved this from 🔎 Awaiting review
to ✔️ Approved by reviewer
in FOC
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a REST API layer for github-projects-client, refactors filozzy-mcp to a thin coordinator, and updates board sweep rules based on live sweep runs.
Library / API changes
Board rule changes (from live sweep feedback)
Sweep playbook improvements
Test plan