quickshell-mcp AGENTS.md

AGENTS.md

Guidance for AI agents (Claude Code, opencode, etc.) working on this repository.

Quick start

• pip install -e '.[dev]' for the venv (or nix develop for the CI-equivalent shell)
• pytest -q for the offline suite; see Build/test commands below for the full list

Scope

Governs agent behavior within quickshell-mcp only. This is a single-author personal tool, so keep changes proportional: no release automation, no features without a stated consumer, no dependencies without a reason.

Project overview

An MCP server that serves live Quickshell documentation from quickshell.org so LLMs read real docs instead of hallucinating API surface (the API has shifted heavily between releases). Three companion sources round it out: Qt type docs from doc.qt.io (base types like Rectangle that Quickshell configs import but quickshell.org doesn't document), the official quickshell-examples repo via its Gitea API, and real-world QML shells (Caelestia, Noctalia, end-4's dots-hyprland) indexed from their GitHub repos. Everything is fetched at query time; nothing is hardcoded.

Project structure

• quickshell_mcp/, the package itself:
  • config.py: URLs, repo identities, strip-selector lists, TTL/retry constants
  • caches.py: 30-minute in-memory cache per fetch, plus a disk layer that persists built indexes (guide/type/qt) across restarts (30-day default TTL); QUICKSHELL_DOCS_MCP_DISK_CACHE env var to disable/redirect
  • utils.py: logging, HTTP client, _fetch_raw (retry + stats), citation prefix; domain modules call utils._fetch_raw by module attribute so tests monkeypatch one seam
  • versions.py, extraction.py: runtime version discovery; HTML→Markdown with per-source strip rules
  • sources/: shared-services layer (data-source access, index building, parsing, project context, orchestration). No MCP decorators here, and it never imports capabilities/ (dependencies point down). Roughly grouped as: doc/content sources (docs, qt_docs, examples, implementations), code-shaping tools (compat, migrate, validate, generate, refactor), project-facing tools (assistant, explain_error, find_pattern, search_all, project, project_intel, project_validate, project_memory), and runtime/analysis tooling (intelligence, agent_tools, knowledge2, ecosystem, perf_profile, runtime_profile, runtime_session, runtime_debug, runtime_test, runtime_visual, ui_runtime, style_match, adapters/). See individual module docstrings for specifics.
  • capabilities/: capability/domain layer between the tools and the sources, one module per capability (knowledge, knowledge2, validation, generation, migration, project, runtime, inspection, testing, performance, debugging, adapters, ecosystem, intelligence, agent, assistant). Each declares CAPABILITY_NAME/CAPABILITY_TOOLS/CAPABILITY_DEPENDS_ON and re-exports the source entry points; registry.py aggregates the tool→capability map, a cycle-checked dependency_order(), and the safety model. Every capability carries a safety_level (read-only default; runtime and testing are mutating), with per-tool overrides in _TOOL_SAFETY_LEVELS (apply_patch, ui_set_property, ui_invoke, reload are mutating; ui_eval is high-risk).
  • server.py: FastMCP instance, every @mcp.tool() wrapper + docstring (the trigger surface), main(), and re-exports of helper names so tests keep addressing srv.<helper>; tool logic is routed through capabilities/
• tests/: offline pytest suite driven by saved snapshots in tests/fixtures/. conftest.py provides mock_fetch (patches utils._fetch_raw), docs_fixture_urls, http_404, and an autouse cache/stats reset.
• scripts/: smoke_test.py (end-to-end stdio client), standalone headless CI entrypoints (ci_validate.py, ci_screenshot.py, ci_runtime_test.py, ci_api_compat.py, ci_migration.py), and QA tooling (quality_audit.py, benchmark.py). Each CI script exposes a testable run() function separate from its argparse main().
• flake.nix / Dockerfile / .github/workflows/ci.yml + .releaserc.js: packaging + CI + semantic release. The flake has a ci devShell (nix develop .#ci) with quickshell, weston, grim, and imagemagick for headless runtime/screenshot jobs. CLAUDE.md is a symlink to this file.