Skip to content

Commit fdcea8d

Browse files
BigLepclaude
andcommitted
docs: add FAQ explaining why filozzy-mcp exists vs GitHub's official MCP
Context window bloat from GitHub's MCP server (~8KB per item, no way to suppress) makes it impractical for LLM workflows. Documents the evaluation, links to upstream issue github/github-mcp-server#2383, and sets clear revisit criteria. Co-Authored-By: Claude Opus 4.6 <[email protected]>
1 parent d317a98 commit fdcea8d

1 file changed

Lines changed: 34 additions & 3 deletions

File tree

‎filozzy-mcp/README.md‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,11 +134,42 @@ Tests cover:
134134
- "Set the status of dealbot#88 to Done"
135135
- "What has FilOzzy done recently?"
136136

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+
137168
## Next steps
138169

139-
1. Clarify positioning: FilOzzy is filling a gap where GitHub's MCP tooling does
140-
not currently expose the project board APIs/operations we need. Research
141-
whether a generic GitHub Projects MCP already exists before expanding scope.
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).
142173
2. Evaluate generalizing both `filozzy-mcp` and
143174
`foc-pr-report/foc_pr_report/foc_project14_client.py` so they work for any
144175
GitHub Projects v2 board, not just `https://github.com/orgs/FilOzone/projects/14`.

0 commit comments

Comments
 (0)