llm-tools/CLAUDE.md

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:

  # Python MCP setup (e.g. dicom)
  cd ~/Projects/local/mcp_servers/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.