llm-tools/CONTEXT.md

# LLM Context Guide (llm-tools Repository)

This document serves as a **provider-agnostic project brief** for any LLM agent or coding assistant (Claude, Grok, Cursor, Continue.dev, Windsurf, etc.) working in this repository. It is designed to be included in context automatically or explicitly.

Copy, rename, or adapt it as needed:
- **Claude Code / Desktop**: Rename to `CLAUDE.md` (or keep as `CONTEXT.md` — Claude often detects common context files).
- **Grok CLI**: Use `.grok/context.md` (already present and optimized for Grok's sub-agents and built-in MCP tools).
- **Other tools**: Place in root, `.cursor/rules/`, `.continue/rules/`, or equivalent.

## Project Overview

A collection of **Model Context Protocol (MCP)** servers and reusable **agent skills/toolkits**. These enable 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. Skills are structured Markdown/YAML guides with best practices that can be adapted across platforms. All documentation and contributions should remain **model-provider agnostic** while noting platform-specific configuration (Claude Desktop/Code, Grok CLI Agent mode, etc.).

See `README.md` for full structure, setup, MCP descriptions, skills list, and Grok-specific files (`.grokignore`, `.grok/context.md`).

## MCP Servers (in ./mcps/)

Use the corresponding built-in `mcp_*` tools where available, or launch via the provided shell scripts (stdio or HTTP transport).

- **dicom-mcp** (primary focus): 17+ read-only tools for DICOM QA. Key capabilities: directory summarization, Dixon detection, header comparison, sequence validation, pixel statistics/SNR, image rendering (with windowing/ROIs), Philips private tag queries, UID/segmentation verification, T1 mapping analysis. 
  - Launch: `mcps/dicom_mcp/run_dicom_mcp_server.sh` (or with `DICOM_MCP_PII_FILTER=true` for redaction).
  - Best for non-coders (plain-language QA) and developers (consistent outputs). See `mcps/dicom_mcp/README.md`, `docs/`, and individual tool descriptions.
- **filesystem-mcp**: Read/write/update/list/delete/move/copy with session defaults. Based on `@cyanheads/filesystem-mcp-server`.
- **open-meteo-mcp**: Current weather + multi-day forecasts (no API key). Supports units and decoded WMO codes.
- **playwright-mcp**: Modern browser automation (navigate, click, type, snapshots, JS eval, tabs, waits, screenshots, network/console). Excellent for accessibility and full-page interactions.
- **selenium-mcp**: Alternative multi-session browser automation (forms, smart waits, actionable errors, content extraction).

Additional MCPs (GitHub, US/UK weather, etc.) appear in some environments.

**Configuration Examples**:
- **Claude Code**: Use root `.mcp.json` + `.claude/settings.local.json` (already configured to enable all servers and skills).
- **Claude Desktop**: Copy/update `config/claude_desktop_config.json` (fix absolute paths to your machine) to `~/Library/Application Support/Claude/claude_desktop_config.json`.
- **Grok CLI Agent mode**: MCP tools are pre-registered (e.g., `mcp_dicom-mcp__dicom_summarize_directory`). Use `task` (sub-agents: `general`, `explore`, `verify`, `computer`), `delegate`, and built-in tools. See `.grok/context.md` for detailed Grok-specific workflows, priorities, and examples.
- General: Follow https://modelcontextprotocol.info/docs/. Most servers support Poetry (`poetry install`) and launch scripts.

## Skills (in ./skills/)

Structured guides (`SKILL.md` files with YAML frontmatter) for agentic tasks. Load via platform mechanisms or copy relevant sections into context/prompts.

- **artifacts-builder**: High-quality React + Tailwind + shadcn/ui HTML artifacts (init/bundle scripts, anti-"AI slop" guidelines).
- **document-skills/** (docx, pdf, pptx, xlsx): Creation, editing, analysis, forms, OOXML references.
- **mcp-builder**: Comprehensive guide for building robust MCP servers (Python FastMCP or Node SDK). Phases: deep research/planning, implementation, evaluation. **Highly recommended** for extending this repo. Emphasizes agent-centric, workflow-focused tools.
- **skill-creator**: Instructions for new reusable agent skills.
- **webapp-testing**: Playwright examples for local web apps.

Adapt these for any LLM — they originated with Claude but focus on portable best practices (agent-centric design, avoid boilerplate, evaluate quality).

## General Best Practices (All Providers)

- **Provider Agnostic**: Keep outputs, docs, and code free of platform-specific jargon. Prefer MCP tools; treat skills as prompt libraries.
- **Workflow**:
  1. Understand the request and explore with read-only tools first.
  2. Use sub-agents or equivalent (Grok: `task` with `explore`/`general`/`verify`; Claude: built-in reasoning/skills).
  3. For code changes: Surgical edits first (`edit_file` equivalent), then verify (tests, re-reads, builds).
  4. Launch long-running processes (MCP servers, dev watchers) in background where supported.
  5. For research: Parallel exploration; use web/search tools for up-to-date info.
- **Context Management**: Use ignore files (`.grokignore`, `.gitignore`, Claude equivalents) to exclude binaries, large dirs (DICOMs, node_modules, images), logs, and vendor code. Explicitly load only necessary files (README.md, specific SKILL.md, MCP docs).
- **Testing & Validation**: Run pytest for Python MCPs, verify MCP registration, test browser flows, validate DICOM outputs against expected QA protocols.
- **Extending the Repo**: Follow `skills/mcp-builder/SKILL.md` (research → plan → implement → evaluate). Add new MCPs to `.mcp.json`, update configs, and keep docs agnostic. Use GitHub MCP tools for PRs/commits where available.
- **DICOM QA Specifics**: Start with `dicom_summarize_directory` or `dicom_list_files`. Use `dicom_render_image` to identify ROIs before `dicom_read_pixels` or `dicom_compute_snr`. Handle manufacturer differences (Siemens/GE/Philips private tags).
- **Commands (common)**:
  ```bash
  # MCP setup (Python-based)
  cd mcps/dicom_mcp && poetry install --with dev
  poetry run pytest -v

  # Launch servers
  ./mcps/dicom_mcp/run_dicom_mcp_server.sh
  # (or with PII filter: DICOM_MCP_PII_FILTER=true ...)

  # Grok CLI specific: Use built-in mcp_* tools directly
  # Claude: Rely on .mcp.json + settings
  ```

## Platform-Specific Notes

- **Claude**: Full support via `.mcp.json`, `config/claude_desktop_config.json`, `.claude/settings.local.json`, and skills. Legacy files like `CLAUDE.md` (in subdirs) or Anthropic links can be generalized.
- **Grok CLI**: Leverages pre-registered MCP tools + sub-agent system. See dedicated `.grok/context.md` and `.grokignore` for optimized workflows (proactive `task`/`delegate`, `edit_file` preference, background processes, etc.).
- **Others** (Cursor, Continue, etc.): Load this `CONTEXT.md`, relevant `SKILL.md`, and MCP docs. Configure MCP servers per their docs.

Refer to this file in every session: "Follow the LLM Context Guide in CONTEXT.md (or .grok/context.md / CLAUDE.md), the main README.md, and relevant SKILL.md files. Maintain provider-agnostic outputs and documentation."

Update this file, `README.md`, or platform-specific variants as the repository evolves. For new MCPs or skills, start with the `mcp-builder` and `skill-creator` guides.