|
| 1 | +# FilOzzy MCP Server |
| 2 | + |
| 3 | +MCP server for managing the FilOzone FOC project board (GitHub Projects v2 #14). |
| 4 | + |
| 5 | +Fills the gap that GitHub's official MCP and `gh` CLI don't cover: **reading and setting project-level field values** (Status, Cycle Theme, Dev Days Estimate, Cycle, etc.). |
| 6 | + |
| 7 | +For issue/PR-level operations (assignees, milestones, reviewers), use `gh` CLI directly. |
| 8 | + |
| 9 | +## Setup |
| 10 | + |
| 11 | +### 1. Install dependencies |
| 12 | + |
| 13 | +```bash |
| 14 | +cd filozzy-mcp |
| 15 | +uv sync |
| 16 | +``` |
| 17 | + |
| 18 | +### 2. Get a GitHub token |
| 19 | + |
| 20 | +You need a token with scopes: `project`, `repo`, `read:org`. |
| 21 | + |
| 22 | +The easiest way is to use the GitHub CLI: |
| 23 | + |
| 24 | +```bash |
| 25 | +gh auth token |
| 26 | +``` |
| 27 | + |
| 28 | +If your token doesn't have the `project` scope yet: |
| 29 | + |
| 30 | +```bash |
| 31 | +gh auth refresh -s project |
| 32 | +``` |
| 33 | + |
| 34 | +Alternatively, create a [personal access token](https://github.com/settings/tokens) with the required scopes. |
| 35 | + |
| 36 | +### 3. Configure Claude Code |
| 37 | + |
| 38 | +You can configure the MCP server in one of two places: |
| 39 | + |
| 40 | +**Option A: Project-level config (`.mcp.json` in the repo root)** |
| 41 | + |
| 42 | +Create a `.mcp.json` file in the `tpm-utils/` root (this file is gitignored): |
| 43 | + |
| 44 | +```json |
| 45 | +{ |
| 46 | + "mcpServers": { |
| 47 | + "filozzy": { |
| 48 | + "command": "uv", |
| 49 | + "args": ["--directory", "./filozzy-mcp", "run", "filozzy-mcp"], |
| 50 | + "env": { |
| 51 | + "GITHUB_TOKEN": "<paste output of gh auth token>" |
| 52 | + } |
| 53 | + } |
| 54 | + } |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +**Option B: User-level config (`~/.claude/settings.json`)** |
| 59 | + |
| 60 | +Add the server to your global Claude Code settings. You can do this via the CLI: |
| 61 | + |
| 62 | +```bash |
| 63 | +claude mcp add filozzy \ |
| 64 | + --command uv \ |
| 65 | + --args "--directory" "/absolute/path/to/tpm-utils/filozzy-mcp" "run" "filozzy-mcp" \ |
| 66 | + --env GITHUB_TOKEN="<paste output of gh auth token>" |
| 67 | +``` |
| 68 | + |
| 69 | +Or edit `~/.claude/settings.json` directly and add the same JSON block as Option A under `mcpServers`. |
| 70 | + |
| 71 | +### 4. Restart Claude Code |
| 72 | + |
| 73 | +After configuring, restart Claude Code (or start a new session). The FilOzzy tools will be available automatically. |
| 74 | + |
| 75 | +## Available tools |
| 76 | + |
| 77 | +### Read tools |
| 78 | + |
| 79 | +- **`list_board_items`** — List project items with optional filter (same `q` syntax as the board UI) |
| 80 | +- **`list_board_view_items`** — List items for a project view URL (resolves saved view filter, URL `filterQuery` override, and optional `visibleFields` field ordering) |
| 81 | +- **`get_board_item`** — Get full details of a specific item (e.g., `dealbot#111`) |
| 82 | +- **`list_board_fields`** — List all project fields |
| 83 | +- **`list_board_field_options`** — List valid options for a field (e.g., Status values) |
| 84 | + |
| 85 | +For `list_board_view_items`: |
| 86 | +- `visibleFields` in the URL is authoritative and preserved exactly in that order. |
| 87 | +- If `visibleFields` is not present, FilOzzy uses the view default field order from GraphQL metadata, which may differ from the live UI column order. |
| 88 | +- `sliceBy[...]` URL parameters are currently ignored. |
| 89 | + |
| 90 | +`get_board_item` is intentionally kept as a first-class primitive, even though |
| 91 | +you could emulate it with `list_board_items`. It gives MCP clients one stable |
| 92 | +"resolve this reference" operation that accepts `repo#number`, `owner/repo#number`, |
| 93 | +or a GitHub URL, then returns a single hydrated board item. This keeps lookup |
| 94 | +logic (reference parsing, query construction, pagination, exact-match selection) |
| 95 | +inside the server instead of duplicating it across agents and clients. |
| 96 | + |
| 97 | +### Mutation tools |
| 98 | + |
| 99 | +- **`set_board_item_field`** — Set a project field value (e.g., set Status to "In Progress") |
| 100 | + |
| 101 | +### Logging |
| 102 | + |
| 103 | +- **`get_action_log`** — View recent FilOzzy actions |
| 104 | + |
| 105 | +Every mutation is logged to `action_log.jsonl`. |
| 106 | + |
| 107 | +## Testing |
| 108 | + |
| 109 | +Integration tests run against the live GitHub API (read-only, no mutations). |
| 110 | + |
| 111 | +### Prerequisites |
| 112 | + |
| 113 | +- A GitHub token with `project` and `repo` scopes (same as the server itself) |
| 114 | +- Network access to `api.github.com` |
| 115 | + |
| 116 | +### Run tests |
| 117 | + |
| 118 | +```bash |
| 119 | +cd filozzy-mcp |
| 120 | +GITHUB_TOKEN=$(gh auth token) uv run pytest tests/test_integration.py -v |
| 121 | +``` |
| 122 | + |
| 123 | +Tests cover: |
| 124 | +- REST API fetcher (pagination, cursors, capping, invalid filters) |
| 125 | +- Item listing (default/custom fields, time-based filters, combined filters) |
| 126 | +- Field discovery and field option enumeration |
| 127 | +- Item lookup by short ref, full ref, and URL |
| 128 | +- Cursor-based pagination with no overlap between pages |
| 129 | + |
| 130 | +## Example usage (in Claude Code) |
| 131 | + |
| 132 | +- "Show me all non-Done items missing a milestone" |
| 133 | +- "What are the valid Status values?" |
| 134 | +- "Set the status of dealbot#88 to Done" |
| 135 | +- "What has FilOzzy done recently?" |
| 136 | + |
| 137 | +## FAQ |
| 138 | + |
| 139 | +### Why not just use GitHub's official MCP server? |
| 140 | + |
| 141 | +GitHub's [official MCP server](https://github.com/github/github-mcp-server) has a Projects v2 toolset (`projects_list`, `projects_get`, `projects_write`) available at the `/x/projects` endpoint. It supports query filtering, pagination, field discovery (including single-select options), and mutations. So why does filozzy-mcp exist? |
| 142 | + |
| 143 | +**The non-negotiable blocker: context window bloat.** Each project item response from GitHub's MCP is ~8KB because it includes the full issue/PR body, complete repository object (~2KB of URL templates), and full user objects for every author/assignee/milestone-creator. The `fields` parameter controls which *project fields* are returned but there is no way to suppress the content blob. |
| 144 | + |
| 145 | +| Query size | GitHub MCP payload | Token cost | Impact | |
| 146 | +|---|---|---|---| |
| 147 | +| 10 items | ~80KB | ~20K tokens | Noticeable | |
| 148 | +| 50 items (max per_page) | ~400KB | ~100K tokens | Half the context window | |
| 149 | +| 100 items (2 pages) | ~800KB | ~200K+ tokens | Entire context window consumed | |
| 150 | + |
| 151 | +filozzy-mcp returns ~200-300 bytes per item (just the project field values you asked for) — a **~40x reduction**. The LLM cannot filter the response before it enters context, so those tokens are consumed regardless of whether the LLM "ignores" the content. |
| 152 | + |
| 153 | +| | github-projects MCP | filozzy-mcp | |
| 154 | +|---|---|---| |
| 155 | +| Per-item response size | ~8KB | ~200-300 bytes | |
| 156 | +| 50-item query | ~400KB / ~100K tokens | ~10-15KB / ~3-4K tokens | |
| 157 | +| Field name resolution | Raw IDs required | By name (`"Status"` → `"Done"`) | |
| 158 | +| Filter syntax docs | None in tool description | Comprehensive reference in docstring | |
| 159 | +| Mutation UX | 3 tool calls with raw IDs | 1 call: `set_board_item_field("dealbot#111", "Status", "Done")` | |
| 160 | +| Audit logging | None | JSONL with old/new values | |
| 161 | + |
| 162 | +This is a [known problem across the GitHub MCP server](https://github.com/github/github-mcp-server/issues/142) (20+ comments, open since April 2025). The maintainers have been fixing it tool-by-tool using "minimal types", but the projects tools haven't been optimized yet. We filed [github/github-mcp-server#2383](https://github.com/github/github-mcp-server/issues/2383) requesting compact output for project items. |
| 163 | + |
| 164 | +**If #2383 gets addressed**, we should revisit this decision — GitHub's official tooling plus CLAUDE.md prompt engineering could replace filozzy-mcp. Until then, filozzy-mcp stays as the thin, context-efficient wrapper it was designed to be. |
| 165 | + |
| 166 | +For the full evaluation, see [FilOzone/tpm-utils#25 (comment)](https://github.com/FilOzone/tpm-utils/issues/25#issuecomment-4314857318). |
| 167 | + |
| 168 | +## Next steps |
| 169 | + |
| 170 | +1. ~~Clarify positioning~~ — Done. See FAQ above. filozzy-mcp exists because |
| 171 | + GitHub's official MCP returns ~8KB per item with no way to suppress the |
| 172 | + content blob. Tracking upstream fix at [github/github-mcp-server#2383](https://github.com/github/github-mcp-server/issues/2383). |
| 173 | +2. Evaluate generalizing both `filozzy-mcp` and |
| 174 | + `foc-pr-report/foc_pr_report/foc_project14_client.py` so they work for any |
| 175 | + GitHub Projects v2 board, not just `https://github.com/orgs/FilOzone/projects/14`. |
| 176 | +3. If generalized, factor the shared project-board client logic out of |
| 177 | + `foc-pr-report` into a reusable module/package, since the API surface is now |
| 178 | + broader than FOC-specific reporting. |
| 179 | +4. If no existing generic GitHub Projects MCP is suitable, review FilOzzy MCP |
| 180 | + docstrings/tool descriptions against GitHub MCP tool descriptions and improve |
| 181 | + wording, guidance, and examples accordingly. |
0 commit comments