Skip to content

CLAUDE.md

Latest commit

 

History

History
109 lines (85 loc) · 7 KB

CLAUDE.md

File metadata and controls

109 lines (85 loc) · 7 KB

CLAUDE.md - mfbt CLI

Project Overview

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.

  • Language: Python 3.10+ (uses modern features: pattern matching, improved type hints)
  • Backend: Integrates with mfbt REST API ({BASE_URL}/api/v1/)
  • Auth: OAuth 2.1 with PKCE (1hr access tokens, 30-day refresh tokens), plus API key management (mfbtsk-{uuid}, passed as Authorization: Bearer {key})
  • Config: Global ~/.mfbt/ directory stores auth tokens and configuration (no per-project config)

API Specification

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.

Architecture

Core Systems

  1. Authentication & Configuration — Browser-based OAuth flow with PKCE, auto token refresh + interactive re-auth on 401, API key support. Shared auth flow in auth_flow.py. Config/auth in ~/.mfbt/ (schema v2, no per-project project_id).
  2. Interactive TUI Mode — Launched when CLI runs without subcommands; K9S-style keyboard-driven navigation: Projects > Phases > Modules > Features. Ralph orchestration integrated via r key.
  3. Subcommands — auth, projects (list, show, create, archive, delete), ralph, tui. Consistent output formatting (table, JSON, etc.)
  4. API Integration Layer — REST client with on_auth_required callback for auto re-auth on 401. Paginated responses ({items, total, page, page_size, total_pages}), error handling (402 for token limits), job polling, WebSocket support.
  5. API Key Management — CRUD via /api/v1/users/me/api-keys
  6. Coding Agent Checks — coding_agents.py provides pre-flight checks (agent installed, MCP configured) before Ralph orchestration.

Key API Endpoints

  • Projects CRUD
  • Brainstorming phases
  • Modules, features, and implementations
  • Job monitoring: GET /api/v1/jobs/{job_id}
  • Thread comments
  • MCP config retrieval: GET /api/v1/projects/{id}/mcp-config
  • API key management: /api/v1/users/me/api-keys

Constraints

  • Must work with existing mfbt FastAPI backend
  • Support both UUIDs and short URL identifiers
  • Handle ISO 8601 UTC timestamps
  • Graceful degradation when token limits reached (HTTP 402)

MFBT MCP Server (Virtual Filesystem)

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.

Key MCP Concepts

  • The VFS exposes project phases, modules, features, and implementations as a navigable filesystem
  • Use UNIX-like commands: ls, cat, tree, find, grep, head, tail
  • Smart metadata on directories guides what to work on next (progress %, next feature, completion status)
  • Two feature sources: system-generated/ (AI-created from brainstorming) and user-defined/ (manually created or imported)

MCP VFS Structure

/
├── phases/
│   ├── system-generated/{phase}/
│   │   ├── phase-spec/          # full.md, summary.md, by-section/
│   │   ├── phase-prompt-plan/   # full.md, by-section/
│   │   └── features/{module}/{feature}/
│   │       ├── implementations/{impl}/
│   │       │   ├── spec.md          # WHAT to build
│   │       │   ├── prompt_plan.md   # HOW to build
│   │       │   └── notes.md         # Writable learnings
│   │       └── conversations/conversations.md
│   └── user-defined/features/{module}/{feature}/
│       └── (same structure as above)
├── project-info/team-info.json
├── system-info/users/available-users-list.csv
└── for-coding-agents/
    ├── agents.md              # Grounding context (read at session start)
    └── mfbt-usage-guide/      # Workflow guides

MCP Recommended Workflow

  1. cat /for-coding-agents/agents.md --branch_name='your-branch' — grounding context
  2. ls / → ls /phases/ → drill into phases, modules, features
  3. Read spec.md (what to build) and prompt_plan.md (how to build)
  4. setMetadataValueForKey .../features/{module}/{feature}/ in_progress true — mark as started
  5. Implement the feature
  6. write .../implementations/{impl}/notes.md '<learnings>' — document what you learned
  7. setMetadataValueForKey .../implementations/{impl}/ is_complete true — mark done (auto-syncs feature status)

MCP Tips

  • Include coding_agent_name: "claude_code" and branch_name in tool calls
  • Use summary.md for quick spec overviews; by-section/ for large specs
  • Focus on must_have features first, then important, then optional
  • notes.md auto-feeds into agents.md grounding — document architectural decisions and gotchas
  • Use grep to search across specs and prompt plans
  • For team communication (posting comments), see /for-coding-agents/mfbt-usage-guide/
  • To update status: in_progress on features when starting, is_complete on implementations when done

Development

  • Venv: .venv/bin/python, .venv/bin/pytest
  • Run tests: .venv/bin/pytest tests/unit/ -v
  • Config functions no longer take project_root — load_config(), save_config(), load_auth(), save_auth(), init_mfbt_dir(), resolve_config() all operate on ~/.mfbt/ via get_mfbt_dir(). TokenManager.__init__ takes only base_url.
  • API response formats: List endpoints (/features, /implementations) return paginated {"items": [...], "total": N, ...} — always extract via body["items"]. Some endpoints (/brainstorming-phases) return plain lists. See src/mfbt/tui/data_provider.py for the canonical parsing pattern.
  • TUI navigation: Projects > Phases > Modules > Features (4 levels). NavigationState stack depth: 0=projects, 1=phases, 2=modules, 3=features. Phase list shows brainstorming phases + virtual "Orphan modules" entry.
  • Ralph in TUI: Integrated into main TUI (r key), not a standalone app. Uses RalphPanel widget in #main-content with PreflightModal for agent checks. Standalone tui_app.py deleted.
  • Ralph subcommand: src/mfbt/commands/ralph/ — orchestrator, display (console), tui_display (Textual adapter), ralph_widgets (TUI widgets), agent runner, progress (API), prompt builder, types.
  • Display duck typing: RalphOrchestrator.display is typed as Any — both RalphDisplay and RalphTUIDisplay are structurally compatible (same 8 methods).
  • Key new files: auth_flow.py (shared OAuth), coding_agents.py (agent pre-flight checks), tui/screens/phase_list.py, tui/screens/preflight_modal.py, tui/screens/ralph_panel.py, commands/ralph/ralph_widgets.py.
  • TUI shortcuts: r = Ralph, ctrl+r = Refresh, d = Describe, enter = Open/Detail, esc = Back, ? = Help, q = Quit.