# CLAUDE.md

This file provides guidance to **Claude** (Claude Desktop, Claude Code, or Claude API) when working with this repository. It is the dedicated Claude-specific version of the shared `CONTEXT.md`. Keep both files in sync where possible, but tailor this one to Claude's strengths (skills, MCP integration, artifact generation, etc.).

## Project Overview

A collection of **Model Context Protocol (MCP)** servers and reusable **agent skills**. These enable Claude (and other LLMs) to perform specialized tasks including:
- Medical imaging QA and analysis (DICOM/MRI, body composition, Dixon sequences, T1 mapping, pixel stats, SNR, Philips private tags, segmentation verification).
- Browser automation and web testing (Playwright and Selenium MCPs).
- Filesystem operations, weather queries (Open-Meteo), document manipulation (DOCX/PDF/PPTX/XLSX), complex HTML artifact generation (React/Tailwind/shadcn), and MCP/skill development guides.

**Core Philosophy**: MCP provides standardized, workflow-oriented tools that reduce boilerplate and enable natural language interaction with external data and services. Skills are structured Markdown/YAML guides with best practices, examples, and evaluation criteria. All new documentation, code, and contributions in this repo must remain **model-provider agnostic** while including platform-specific configuration notes (Claude Desktop/Code, Grok CLI, etc.).

See `README.md` for full structure, MCP descriptions, skills list, setup instructions, and the shared `CONTEXT.md`. Also reference `.grok/context.md` for cross-platform insights (especially Grok's sub-agent patterns that can inspire Claude workflows).

## MCP Servers (in ./mcps/)

Claude integrates MCP servers natively via `.mcp.json`, `.claude/settings.local.json`, and the config in `config/claude_desktop_config.json`. Launch them using the provided scripts.

- **dicom-mcp** (primary focus for QA workflows): 17+ read-only tools optimized for body composition and liver imaging QA. Key tools include `dicom_summarize_directory`, `dicom_find_dixon_series`, `dicom_get_metadata`, `dicom_compare_headers`, `dicom_validate_sequence`, `dicom_analyze_series`, `dicom_query`, `dicom_read_pixels`, `dicom_compute_snr`, `dicom_render_image` (with windowing/ROI overlays), `dicom_dump_tree`, `dicom_analyze_ti`, and more (Philips private tags, UID comparison, segmentation verification).
  - Best for both non-technical users (plain-language QA without shell access) and developers.
  - Launch: `mcps/dicom_mcp/run_dicom_mcp_server.sh` (add `DICOM_MCP_PII_FILTER=true` for patient data redaction).
  - See `mcps/dicom_mcp/README.md`, `docs/CAPABILITIES.md`, `docs/GUIDELINES.md`, and `docs/USAGE.md`.
- **filesystem-mcp**: Full read/write/update/list/delete/move/copy with session defaults (via `@cyanheads/filesystem-mcp-server`).
- **open-meteo-mcp**: Current weather and forecasts (temperature, precipitation, wind, WMO codes decoded to English). No API key needed.
- **playwright-mcp**: Modern browser automation — navigate, click, type, fill forms, take screenshots (viewport/full-page), accessibility snapshots, JS evaluation, tabs, waits, console/network inspection, drag & drop.
- **selenium-mcp**: Alternative multi-session browser automation with smart waits, actionable error suggestions, form filling, content extraction (text/HTML/links), and screenshots.

**Claude Configuration**:
- **Claude Code**: The root `.mcp.json` registers all servers. `.claude/settings.local.json` enables them and registers the skills paths. Open the project to activate.
- **Claude Desktop**: Copy (and update absolute paths in) `config/claude_desktop_config.json` to `~/Library/Application Support/Claude/claude_desktop_config.json`.
- Always prefer MCP tools over writing ad-hoc Python/scripts when the tool matches the task. Use skills for higher-level orchestration.

## Skills (in ./skills/)

Claude has first-class support for these via the Skills feature (see Claude Docs). Load them through `.claude/settings.local.json` (already configured) or the Skills API.

- **artifacts-builder**: Build sophisticated, multi-component HTML artifacts using React 18, TypeScript, Vite, Tailwind, and shadcn/ui. Includes `init-artifact.sh` and `bundle-artifact.sh`. Follow anti-"AI slop" guidelines (avoid excessive centered layouts, purple gradients, uniform rounded corners, Inter font).
- **document-skills/** (docx, pdf, pptx, xlsx): Creation, editing, analysis, forms, merging/splitting, formula support, and OOXML schema references.
- **mcp-builder**: **Highly recommended**. Comprehensive guide for creating high-quality MCP servers (Python FastMCP or Node/TypeScript SDK). Follow the four phases: deep research/planning (agent-centric design, workflow tools), implementation, evaluation, and iteration. Emphasizes consolidating operations into high-impact tools rather than 1:1 API wrappers.
- **skill-creator**: Guide for developing new reusable Claude skills (structure, examples, evaluation).
- **webapp-testing**: Playwright-based scripts and examples for testing local web applications.

When using a skill, follow its `SKILL.md` exactly, including the YAML frontmatter. Combine skills with MCP tools (e.g., use artifacts-builder to visualize DICOM QA results).

## General Best Practices for Claude

- **Provider Agnostic**: Even though this is `CLAUDE.md`, avoid Claude-only phrasing in code, docs, or outputs. Reference the shared `CONTEXT.md` and `README.md` for neutral language. Mention Grok CLI compatibility where relevant (e.g., its built-in `mcp_*` tools and sub-agents).
- **Workflow Priorities**:
  1. Understand the request thoroughly.
  2. Explore first (use MCP tools, `read_file`, or equivalent research).
  3. Plan with skills (`mcp-builder` or `skill-creator` patterns).
  4. Implement surgically (prefer targeted changes; verify with tests/re-reads).
  5. Use artifacts for rich outputs (HTML with React where appropriate).
  6. Validate rigorously (pytest for MCPs, visual confirmation for renders, cross-platform notes).
- **Context Management**: Keep context lean. Claude Desktop has no direct shell/filesystem access — that's why MCPs exist. Use `.gitignore`, `.grokignore`, and Claude's ignore patterns to exclude large binaries (DICOMs, images, node_modules, PDFs, etc.).
- **DICOM QA Specifics** (common use case):
  - Start with `dicom_summarize_directory` or `dicom_list_files` (use `count_only` for large dirs).
  - Detect Dixon with `dicom_find_dixon_series`.
  - Compare headers, validate parameters, analyze series consistency.
  - For pixels: Render first (`dicom_render_image` with auto_window or manual WL), identify ROIs, then compute stats/SNR.
  - Handle Philips private tags via `dicom_query_philips_private` or `dicom_get_metadata`.
  - Use `dicom_analyze_ti` for MOLLI/T1 mapping.
- **Commands**:
  ```bash
  # Python MCP setup (e.g. dicom)
  cd mcps/dicom_mcp
  poetry install --with dev
  poetry run pytest -v --tb=short

  # Run specific test
  poetry run pytest test_dicom_mcp.py::TestToolRegistration::test_all_tools_registered -v

  # Launch MCP server
  poetry run python -m dicom_mcp
  # With PII filtering
  DICOM_MCP_PII_FILTER=true poetry run python -m dicom_mcp

  # Other MCPs: Use the launch_*.sh scripts in each mcps/ subdir
  ```
- **Artifact & Output Guidelines**: When generating UIs or reports, follow artifacts-builder rules to produce clean, professional results. For QA outputs, use consistent markdown tables, include confidence scores where appropriate, and offer both summary and detailed views.

## Platform Notes & Cross-Compatibility

- **Claude Desktop/Code**: Full native MCP + Skills support. Use this `CLAUDE.md`, the shared `CONTEXT.md`, and skills heavily.
- **Grok CLI**: See `.grok/context.md` for its sub-agent system (`task` with `general`/`explore`/`verify`/`computer`, `delegate` for background work). Many of our MCPs are exposed as built-in `mcp_*` tools. Adapt Grok's workflow priorities here when switching contexts.
- **Other LLMs**: Use the shared `CONTEXT.md` as the base. MCP spec: https://modelcontextprotocol.info/docs/.

**Always start sessions with**: "Follow the guidance in CLAUDE.md (and CONTEXT.md), the main README.md, relevant SKILL.md files, and any active MCP tool descriptions. Keep all outputs, documentation, and new code model-provider agnostic."

Update this file, the shared `CONTEXT.md`, `README.md`, or subproject docs as the repository evolves. For new MCP servers or skills, begin with the `mcp-builder` and `skill-creator` guides. This ensures high-quality, consistent, and portable tools.