You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit fdcea8d
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Copy file name to clipboardExpand all lines: filozzy-mcp/README.md
+34-3Lines changed: 34 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -134,11 +134,42 @@ Tests cover:
134
134
- "Set the status of dealbot#88 to Done"
135
135
- "What has FilOzzy done recently?"
136
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.
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.
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
+
137
168
## Next steps
138
169
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).
142
173
2. Evaluate generalizing both `filozzy-mcp` and
143
174
`foc-pr-report/foc_pr_report/foc_project14_client.py` so they work for any
144
175
GitHub Projects v2 board, not just `https://github.com/orgs/FilOzone/projects/14`.
0 commit comments