Skip to content

Commit cfb6c99

Browse files
BigLepclaude
andauthored
feat: add FilOzzy MCP project board tools and view URL support (#30)
* feat: add filozzy-mcp server for FOC project board operations MCP server wrapping GitHub Projects v2 read and mutation operations for the FOC board (#14). Fills the gap that GitHub's official MCP and gh CLI don't cover: reading/setting project-level field values (Status, Cycle Theme, Dev Days Estimate, Cycle, etc.). Tools: list_board_items, get_board_item, list_board_fields, list_board_field_options, set_board_item_field, get_action_log. Every mutation is logged to action_log.jsonl with timestamps and old/new values. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * feat: add cursor pagination, verbose mode, filter docs, and integration tests - Add cursor-based pagination to fetch_project_v2_items_rest (max_pages, cursor params) so callers can page through large result sets without re-fetching everything from GitHub on each call - Add verbose/debug mode to list_board_items showing the raw REST query, endpoint, field IDs, and pagination state - Expand list_board_items docstring with comprehensive GitHub Projects v2 filter syntax reference (custom fields, time-based filters, negation, relationships, etc.) so Claude can translate natural language queries - Add 24 integration tests covering the REST fetcher, read tools, field discovery, item lookup, and cursor pagination - Clean up unused imports in server.py Co-Authored-By: Claude Opus 4.6 <[email protected]> * refactor: route item detail lookup through list_board_items Make get_item_details reuse list_project_items with a repo+number query so lookups stay server-filtered and avoid expensive full fetches, and document why get_board_item remains a core MCP primitive. Made-with: Cursor * test: validate list_board_items docstring queries against live board Add integration coverage that parses query examples from list_board_items docs, prints runnable and syntax-only sets, and verifies runnable examples return non-empty results while skipped examples execute without API errors. Made-with: Cursor * feat: add view-url listing with filter and field-order resolution Add a board-view URL flow that resolves saved or override filters, supports visibleFields order from URLs, and warns when falling back to GraphQL default field order; move shared resolver logic into foc-pr-report and cover with integration tests. Made-with: Cursor * docs: add roadmap next steps for project MCP generalization Document follow-up work on positioning against GitHub MCP, generalizing board support beyond Project 14, extracting shared client logic, and improving tool docstrings. Made-with: Cursor * fix: address PR #30 review feedback - Fix regression in rest_export.py: adapt to new dict return type from fetch_project_v2_items_rest (was iterating dict instead of items list) - Fix falsy value filtering: use `v not in (None, "")` instead of `and v` to preserve legitimate 0 values in display dicts - Remove dead `content_type` variable in read_tools._format_item - Remove unused `list_project_items` import in mutation_tools - Make action log path configurable via FILOZZY_ACTION_LOG env var - Improve token scope error message with specific required scopes - Add pytest integration marker config to pyproject.toml - Add module-level pytestmark for integration tests - Loosen test assertions that depended on specific board state - Fix docstring: document that per_page is also ignored with cursor Co-Authored-By: Claude Opus 4.6 <[email protected]> * 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]> --------- Co-authored-by: Claude Sonnet 4.6 <[email protected]>
1 parent da95c24 commit cfb6c99

14 files changed

Lines changed: 3162 additions & 19 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
__pycache__/
22
*.pyc
33
.claude/settings.local.json
4+
.mcp.json

‎filozzy-mcp/.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.venv/
2+
__pycache__/
3+
*.pyc
4+
.pytest_cache/
5+
action_log.jsonl

‎filozzy-mcp/README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
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.
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
"""FilOzzy MCP server for FOC project board operations."""
2+
3+
__version__ = "0.1.0"
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
"""Append-only JSONL action log for FilOzzy mutations."""
2+
3+
from __future__ import annotations
4+
5+
import json
6+
import os
7+
from datetime import datetime, timezone
8+
from pathlib import Path
9+
from typing import Any, Dict, Optional
10+
11+
12+
# Default: next to the package root (dev use).
13+
# Override with FILOZZY_ACTION_LOG for installed/read-only environments.
14+
_default_log = Path(__file__).resolve().parent.parent / "action_log.jsonl"
15+
LOG_PATH = Path(os.environ.get("FILOZZY_ACTION_LOG", str(_default_log)))
16+
17+
18+
def log_action(
19+
tool: str,
20+
params: Dict[str, Any],
21+
result: str,
22+
*,
23+
old_value: Optional[str] = None,
24+
new_value: Optional[str] = None,
25+
) -> None:
26+
"""Append a mutation record to the action log."""
27+
entry = {
28+
"timestamp": datetime.now(timezone.utc).isoformat(),
29+
"tool": tool,
30+
"params": params,
31+
"result": result,
32+
}
33+
if old_value is not None:
34+
entry["old_value"] = old_value
35+
if new_value is not None:
36+
entry["new_value"] = new_value
37+
38+
with LOG_PATH.open("a", encoding="utf-8") as f:
39+
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
40+
41+
42+
def read_recent_actions(n: int = 50) -> list[Dict[str, Any]]:
43+
"""Read the last N actions from the log."""
44+
if not LOG_PATH.exists():
45+
return []
46+
lines = LOG_PATH.read_text(encoding="utf-8").strip().splitlines()
47+
recent = lines[-n:] if len(lines) > n else lines
48+
return [json.loads(line) for line in recent]

0 commit comments

Comments
 (0)