|
| 1 | +# CLAUDE.md - mfbt CLI |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +**mfbt CLI** is a Python-based CLI tool for the mfbt platform, targeting publication to PyPI. It provides both an interactive TUI mode (K9S-style) and traditional subcommands for managing mfbt projects. |
| 6 | + |
| 7 | +- **Language:** Python 3.10+ (uses modern features: pattern matching, improved type hints) |
| 8 | +- **Backend:** Integrates with mfbt REST API (`{BASE_URL}/api/v1/`) |
| 9 | +- **Auth:** OAuth 2.1 with PKCE (1hr access tokens, 30-day refresh tokens), plus API key management (`mfbtsk-{uuid}`, passed as `Authorization: Bearer {key}`) |
| 10 | +- **Config:** `.mfbt` directory stores auth tokens and project configuration |
| 11 | + |
| 12 | +## API Specification |
| 13 | + |
| 14 | +The file `openapi.json` in the project root contains the full OpenAPI spec for the mfbt backend. **Do NOT read this file in full** — it is very large. Instead, use Grep or search tools to find specific endpoints, schemas, or parameters as needed. |
| 15 | + |
| 16 | +## Architecture |
| 17 | + |
| 18 | +### Core Systems |
| 19 | + |
| 20 | +1. **Authentication & Configuration** — Browser-based OAuth flow, token refresh/session management, API key support, project selection post-auth |
| 21 | +2. **Interactive TUI Mode** — Launched when CLI runs without subcommands; K9S-style keyboard-driven navigation with real-time status updates |
| 22 | +3. **Subcommands** — `status`, `next`, `modules`, `features`, plus commands for brainstorming phases, implementations, and jobs. Consistent output formatting (table, JSON, etc.) |
| 23 | +4. **API Integration Layer** — REST client for all mfbt endpoints, paginated responses (`{items, total, page, page_size, total_pages}`), error handling (404 for unauthorized, 402 for token limits), job polling for async operations, WebSocket support for real-time job status |
| 24 | +5. **API Key Management** — CRUD via `/api/v1/users/me/api-keys` |
| 25 | + |
| 26 | +### Key API Endpoints |
| 27 | + |
| 28 | +- Projects CRUD |
| 29 | +- Brainstorming phases |
| 30 | +- Modules, features, and implementations |
| 31 | +- Job monitoring: `GET /api/v1/jobs/{job_id}` |
| 32 | +- Thread comments |
| 33 | +- MCP config retrieval: `GET /api/v1/projects/{id}/mcp-config` |
| 34 | +- API key management: `/api/v1/users/me/api-keys` |
| 35 | + |
| 36 | +### Constraints |
| 37 | + |
| 38 | +- Must work with existing mfbt FastAPI backend |
| 39 | +- Support both UUIDs and short URL identifiers |
| 40 | +- Handle ISO 8601 UTC timestamps |
| 41 | +- Graceful degradation when token limits reached (HTTP 402) |
| 42 | + |
| 43 | +## MFBT MCP Server (Virtual Filesystem) |
| 44 | + |
| 45 | +This project uses the **mfbt MCP server**, which exposes a virtual filesystem (VFS) for navigating mfbt project data. **Always call `readMeFirst`** at the start of a session to get the full VFS guide, available tools, and recommended workflow. |
| 46 | + |
| 47 | +### Key MCP Concepts |
| 48 | + |
| 49 | +- The VFS exposes project phases, modules, features, and implementations as a navigable filesystem |
| 50 | +- Use UNIX-like commands: `ls`, `cat`, `tree`, `find`, `grep`, `head`, `tail` |
| 51 | +- Smart metadata on directories guides what to work on next (progress %, next feature, completion status) |
| 52 | +- Two feature sources: `system-generated/` (AI-created from brainstorming) and `user-defined/` (manually created or imported) |
| 53 | + |
| 54 | +### MCP VFS Structure |
| 55 | + |
| 56 | +``` |
| 57 | +/ |
| 58 | +├── phases/ |
| 59 | +│ ├── system-generated/{phase}/ |
| 60 | +│ │ ├── phase-spec/ # full.md, summary.md, by-section/ |
| 61 | +│ │ ├── phase-prompt-plan/ # full.md, by-section/ |
| 62 | +│ │ └── features/{module}/{feature}/ |
| 63 | +│ │ ├── implementations/{impl}/ |
| 64 | +│ │ │ ├── spec.md # WHAT to build |
| 65 | +│ │ │ ├── prompt_plan.md # HOW to build |
| 66 | +│ │ │ └── notes.md # Writable learnings |
| 67 | +│ │ └── conversations/conversations.md |
| 68 | +│ └── user-defined/features/{module}/{feature}/ |
| 69 | +│ └── (same structure as above) |
| 70 | +├── project-info/team-info.json |
| 71 | +├── system-info/users/available-users-list.csv |
| 72 | +└── for-coding-agents/ |
| 73 | + ├── agents.md # Grounding context (read at session start) |
| 74 | + └── mfbt-usage-guide/ # Workflow guides |
| 75 | +``` |
| 76 | + |
| 77 | +### MCP Recommended Workflow |
| 78 | + |
| 79 | +1. `cat /for-coding-agents/agents.md --branch_name='your-branch'` — grounding context |
| 80 | +2. `ls /` → `ls /phases/` → drill into phases, modules, features |
| 81 | +3. Read `spec.md` (what to build) and `prompt_plan.md` (how to build) |
| 82 | +4. `setMetadataValueForKey .../features/{module}/{feature}/ in_progress true` — mark as started |
| 83 | +5. Implement the feature |
| 84 | +6. `write .../implementations/{impl}/notes.md '<learnings>'` — document what you learned |
| 85 | +7. `setMetadataValueForKey .../implementations/{impl}/ is_complete true` — mark done (auto-syncs feature status) |
| 86 | + |
| 87 | +### MCP Tips |
| 88 | + |
| 89 | +- Include `coding_agent_name: "claude_code"` and `branch_name` in tool calls |
| 90 | +- Use `summary.md` for quick spec overviews; `by-section/` for large specs |
| 91 | +- Focus on `must_have` features first, then `important`, then `optional` |
| 92 | +- `notes.md` auto-feeds into `agents.md` grounding — document architectural decisions and gotchas |
| 93 | +- Use `grep` to search across specs and prompt plans |
| 94 | +- For team communication (posting comments), see `/for-coding-agents/mfbt-usage-guide/` |
| 95 | +- To update status: `in_progress` on features when starting, `is_complete` on implementations when done |
0 commit comments