diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 4cceaf7..c97175d 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "name": "unraid", "displayName": "unRAID", "description": "Query, monitor, and manage Unraid servers via GraphQL API.\n\nTools: `unraid` (primary), `diagnose_subscriptions`, `test_subscription_query`\n\nActions + subactions:\n• system: overview, array, network, registration, variables, metrics, services, display, config, online, owner, settings, server, servers, flash, ups_devices, ups_device, ups_config\n• health: check, test_connection, diagnose, setup\n• array: parity_status, parity_history, parity_start, parity_pause, parity_resume, parity_cancel, start_array, stop_array*, add_disk, remove_disk*, mount_disk, unmount_disk, clear_disk_stats*\n• disk: shares, disks, disk_details, log_files, logs, flash_backup*\n• docker: list, details, start, stop, restart, networks, network_details\n• vm: list, details, start, stop, pause, resume, force_stop*, reboot, reset*\n• notification: overview, list, create, archive, mark_unread, recalculate, archive_all, archive_many, unarchive_many, unarchive_all, delete*, delete_archived*\n• key: list, get, create, update, delete*, add_role, remove_role\n• plugin: list, add, remove*\n• rclone: list_remotes, config_form, create_remote, delete_remote*\n• setting: update, configure_ups*\n• customization: theme, public_theme, is_initial_setup, sso_enabled, set_theme\n• oidc: providers, provider, configuration, public_providers, validate_session\n• user: me\n• live: cpu, memory, cpu_telemetry, array_state, parity_progress, ups_status, notifications_overview, notification_feed, log_tail, owner, server_status\n\n* = destructive, requires confirm=True", - "version": "1.1.4", + "version": "1.1.5", "author": { "name": "jmagar", "email": "jmagar@users.noreply.github.com" diff --git a/.gitignore b/.gitignore index 372a953..97bbe36 100644 --- a/.gitignore +++ b/.gitignore @@ -77,3 +77,6 @@ web-ui/backend/.venv-backend/ .dolt/ *.db .beads-credential-key + +# Lavra +.lavra/memory/session-state.md diff --git a/.lavra/config/codebase-profile.md b/.lavra/config/codebase-profile.md new file mode 100644 index 0000000..0a667c6 --- /dev/null +++ b/.lavra/config/codebase-profile.md @@ -0,0 +1,89 @@ +# Codebase Profile +Generated by /project-setup on 2026-03-27 + +## Stack & Integrations +**Language & Runtime** +- Python 3.12+ (min requirement), supports 3.13 +- Build system: Hatchling 1.25.0+, package manager: uv + +**Core Frameworks** +- FastMCP 3.0.0+: MCP server framework +- FastAPI 0.115.0+, Uvicorn 0.35.0+: ASGI layer +- Pydantic: validation/serialization + +**API & Communication** +- httpx 0.28.1+: async HTTP client for GraphQL queries +- websockets 15.0.1+: WebSocket client for real-time subscriptions +- graphql-core 3.2.0+: GraphQL query validation (dev dep) + +**Configuration** +- python-dotenv 1.1.1+: env var management +- rich 14.1.0+: terminal output/logging + +**Testing** +- pytest 8.4.2+, pytest-asyncio 1.2.0+, pytest-cov 7.0.0+ +- respx 0.22.0+: httpx request mocking +- hypothesis 6.151.9+: property-based testing + +**Quality** +- ruff 0.12.8+: lint/format; ty 0.0.15+: type checking + +**External Dependencies** +- Unraid GraphQL API (primary backend via httpx) +- WebSocket subscriptions to Unraid server (persistent connections) +- Supports custom CA certs (UNRAID_VERIFY_SSL) + +**Entry Points** +- CLI: `unraid-mcp-server` / `unraid` bin scripts +- 1 primary MCP tool: `unraid` (15 domains, ~108 subactions) +- 2 diagnostic tools: `diagnose_subscriptions`, `test_subscription_query` +- 10 live snapshot MCP resources under `unraid://` namespace + +## Architecture & Structure +``` +unraid_mcp/ +├── core/ # GraphQL client, exceptions, types, guards +├── config/ # Settings, logging, env validation +├── tools/ # Consolidated unraid tool (15 action domains) +├── subscriptions/ # WebSocket manager, resources, diagnostics +├── main.py # Entry point with shutdown cleanup +└── server.py # FastMCP init + 5-layer middleware chain +``` + +**server.py**: FastMCP init with middleware: logging → error_handling → rate_limiting → response_limiting → caching. Registers all tools/resources at import. + +**tools/unraid.py**: Single consolidated tool (~1900 lines). 15 actions dispatch to domain handlers. Destructive actions require `confirm=True`. + +**core/client.py**: GraphQL HTTP client (httpx-based) with sensitive key redaction, request/response logging, timeout management, credentials elicitation. + +**config/settings.py**: Env var parsing for API URL, credentials, host/port, SSL, timeouts, log level, transport. + +**subscriptions/manager.py**: Singleton SubscriptionManager for WebSocket lifecycle and real-time streaming. + +**Data Flow**: `unraid(action, subaction)` → domain handler → GraphQL query → httpx → Unraid API → response + +**Patterns**: +- Consolidated single-tool MCP (action+subaction multiplexing) +- Singleton SubscriptionManager for WebSocket lifecycle +- Middleware chain (logging wraps all; caching disabled for mutations) +- Elicitation flow for first-run credential setup + +## Conventions & Testing +**Test Framework**: pytest with asyncio auto mode; `make_tool_fn` helper in conftest for tool extraction from FastMCP. + +**Test Layout**: +- Root: domain unit tests (test_array.py, test_docker.py, etc.) +- tests/safety/: destructive action guard audits +- tests/schema/: GraphQL query validation +- tests/http_layer/: respx-based HTTP mocking +- tests/contract/: response structure contracts +- tests/property/: hypothesis property-based tests +- tests/integration/: WebSocket subscription lifecycle (slow, mock WS) + +**Key Patching Rule**: Patch at `unraid_mcp.tools.unraid.make_graphql_request` (tool module level), NOT core module. + +**Naming**: `Test{Feature}` classes, async `test_*` methods, `_DOMAIN_QUERIES` dicts, `register_{domain}_tool()` functions. + +**CI**: uv-based: lint (ruff) → typecheck (ty) → test (pytest) → version-sync → audit. Coverage 80% with branch coverage. Version sync enforces pyproject.toml ↔ .claude-plugin/plugin.json consistency. + +**Ruff config**: line length 100, ignores D1xx/D2xx/D7xx (docstring), S101 (assert in tests). diff --git a/.lavra/config/project-setup.md b/.lavra/config/project-setup.md new file mode 100644 index 0000000..081e5c8 --- /dev/null +++ b/.lavra/config/project-setup.md @@ -0,0 +1,16 @@ +--- +stack: python +review_agents: + - kieran-python-reviewer + - code-simplicity-reviewer + - security-sentinel + - performance-oracle +plan_review_agents: + - kieran-python-reviewer + - code-simplicity-reviewer +disabled_agents: [] +--- + + +MCP server for Unraid GraphQL API, built with FastMCP. Single consolidated `unraid` tool with action/subaction routing (~108 subactions across 15 domains). Python 3.12+, uv, ruff, ty (Astral type checker), pytest. Async throughout (httpx, asyncio). No web framework — stdio transport by default, streamable-http in Docker. Tests: unit (mock at tool module level), schema validation, HTTP layer (respx), safety (destructive action guards), integration (WebSocket subscriptions). Destructive actions require confirm=True gating. + diff --git a/CHANGELOG.md b/CHANGELOG.md index 374cbc7..5d9218d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,17 @@ All notable changes to this project are documented here. +## [1.1.5] - 2026-03-27 + +### Added +- **Beads issue tracking**: `bd init` — Dolt-backed issue tracker with prefix `unraid-mcp-`, hooks, and AGENTS.md integration +- **Lavra project config**: `.lavra/config/project-setup.md` — stack `python`, review agents (kieran-python-reviewer, code-simplicity-reviewer, security-sentinel, performance-oracle) +- **Codebase profile**: `.lavra/config/codebase-profile.md` — auto-generated stack/architecture/conventions reference for planning and review commands + +### Changed +- **`.gitignore`**: Added lavra session-state exclusion (`.lavra/memory/session-state.md`) and beads-related entries +- **`CLAUDE.md`**: Added beads workflow integration block with mandatory `bd` usage rules and session completion protocol + ## [1.1.4] - 2026-03-25 ### Changed diff --git a/CLAUDE.md b/CLAUDE.md index 4e5e34b..5c07ea9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -228,3 +228,50 @@ All runtimes (plugin, direct `uv run`) load credentials from `~/.unraid-mcp/.env ```bash ln -sf CLAUDE.md AGENTS.md && ln -sf CLAUDE.md GEMINI.md ``` + + +## Beads Issue Tracker + +This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # Complete work +``` + +### Rules + +- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists +- Run `bd prime` for detailed command reference and session close protocol +- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files + +## Session Completion + +**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds. + +**MANDATORY WORKFLOW:** + +1. **File issues for remaining work** - Create issues for anything that needs follow-up +2. **Run quality gates** (if code changed) - Tests, linters, builds +3. **Update issue status** - Close finished work, update in-progress items +4. **PUSH TO REMOTE** - This is MANDATORY: + ```bash + git pull --rebase + bd dolt push + git push + git status # MUST show "up to date with origin" + ``` +5. **Clean up** - Clear stashes, prune remote branches +6. **Verify** - All changes committed AND pushed +7. **Hand off** - Provide context for next session + +**CRITICAL RULES:** +- Work is NOT complete until `git push` succeeds +- NEVER stop before pushing - that leaves work stranded locally +- NEVER say "ready to push when you are" - YOU must push +- If push fails, resolve and retry until it succeeds + diff --git a/pyproject.toml b/pyproject.toml index d397124..b4c01b6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,7 +10,7 @@ build-backend = "hatchling.build" # ============================================================================ [project] name = "unraid-mcp" -version = "1.1.4" +version = "1.1.5" description = "MCP Server for Unraid API - provides tools to interact with an Unraid server's GraphQL API" readme = "README.md" license = {file = "LICENSE"}