llm-tools/README.md

# LLM Tools (MCP & Skills)

## Overview

A collection of Model Context Protocol (MCP) servers and reusable agent skills/toolkits. These enable LLMs (such as Claude, Grok, and others supporting MCP) to perform specialized tasks including medical imaging QA (DICOM), browser automation, filesystem operations, weather queries, document manipulation, artifact generation, webapp testing, MCP development, and more.

MCP provides a standardized way for models to access external tools and data. Skills are structured guides, prompts, and examples for agentic workflows that can be adapted across platforms.

This repository originated with a focus on Claude but has been updated to be model-provider agnostic. It works with:
- Claude Desktop / Claude Code (via `.mcp.json`, config files, and `.claude/settings.local.json`)
- Grok CLI Agent mode (via built-in `mcp_*` tools, `task`/`delegate` sub-agents, and direct MCP support)
- Other platforms supporting the MCP specification or equivalent skill/prompt libraries

## Requirements

* Python 3.10+
* Node.js (for filesystem, Playwright, and Selenium MCPs)
* Poetry (for Python-based MCPs)
* Platform that supports MCP (Claude Desktop/Code, Grok CLI with MCP tools, or compatible clients)

## Structure

```
llm-tools/
     |-- .claude/            Platform-specific settings (Claude Code)
     |-- .mcp.json           MCP server registration (for compatible clients like Claude Code)
     |-- config/             Example configs (Claude Desktop; update paths for your environment)
     |-- mcps/               MCP servers
     |     |-- dicom_mcp/        DICOM medical imaging inspection and QA (17+ read-only tools for MRI/body composition)
     |     |-- filesystem_mcp/   Filesystem operations (read/write/list/delete/move/copy via @cyanheads/filesystem-mcp-server)
     |     |-- open_meteo_mcp/   Global weather data via Open-Meteo API (current + forecast)
     |     |-- playwright_mcp/   Browser automation via Playwright (navigation, clicks, snapshots, JS execution, etc.)
     |     |-- selenium_mcp/     Browser automation via Selenium WebDriver (multi-session, forms, waits, screenshots)
     |-- skills/              Reusable agent skills and guides (adaptable across platforms)
           |-- artifacts-builder/       Build complex React + Tailwind + shadcn/ui HTML artifacts
           |-- document-skills/         Document creation, editing, analysis (DOCX, PDF, PPTX, XLSX)
           |     |-- docx/                  Word documents
           |     |-- pdf/                   PDF extraction, creation, merging, forms
           |     |-- pptx/                  PowerPoint
           |     |-- xlsx/                  Spreadsheets with formulas
           |-- mcp-builder/             Comprehensive guide for building high-quality MCP servers (Python FastMCP or Node)
           |-- skill-creator/           Guide for creating new reusable agent skills
           |-- webapp-testing/          Playwright-based local web application testing examples
```

## Setup

### MCP Servers

The root `.mcp.json` registers all MCP servers for clients that support it (e.g., Claude Code). Launch scripts (`mcps/*/launch_*.sh` or `run_*.sh`) handle stdio or HTTP transport.

- **For Claude Code**: Open the project; `.claude/settings.local.json` enables servers and skills. The `.mcp.json` makes tools available.
- **For Claude Desktop**: Update `config/claude_desktop_config.json` (it currently contains absolute user-specific paths — replace with your own or use `~` equivalents), then copy/symlink to your config directory (typically `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS).
- **For Grok CLI Agent mode**: Many MCPs are available as pre-registered tools (prefixed `mcp_dicom-mcp__*`, `mcp_filesystem-mcp__*`, `mcp_playwright-mcp__*`, `mcp_selenium-mcp__*`, `mcp_us-weather-mcp__*`, etc.). Use them directly via function calls, or leverage `task` (for sub-agents like `general`, `explore`, `verify`, `computer`), `delegate`, and built-in tools like `computer_*` for desktop interaction. No extra registration needed in most cases.
- **General**: See individual MCP READMEs for Poetry setup, launch commands (stdio vs HTTP), and platform-specific config examples. Most support the official MCP spec (https://modelcontextprotocol.info/docs/).

**Note on paths**: The `config/claude_desktop_config.json` has hardcoded absolute paths from a previous location (`/Users/.../pd/claude-tools`). Update these to match your current directory (`/Users/gregory.gauthier/Projects/local/llm-tools`) or generalize with environment variables/`~`.

### Skills

Skills are loaded via platform-specific mechanisms:
- Claude: Via `.claude/settings.local.json` (already configured) or the Skills API.
- Grok / others: Use as prompt libraries, copy relevant sections from `SKILL.md` files into your context, or adapt the structured YAML + instructions for your agent's tool/skill system.
- See `skills/*/SKILL.md` for detailed usage, guidelines, and examples. They originated for Claude but emphasize portable best practices (e.g., agent-centric design, workflow-focused tools).

## MCP Servers

### dicom-mcp
Advanced DICOM inspection for QA workflows (MRI, body composition, liver imaging, T1 mapping, Dixon sequences, Philips private tags, pixel statistics, SNR, image rendering, segmentation verification, series consistency, UID comparison, etc.). 17+ tools focused on reducing boilerplate while enabling natural language QA. Ideal for both non-coders (via MCP) and developers. See `mcps/dicom_mcp/README.md` and `docs/` for full capabilities, guidelines, and examples. (Note: Some sub-docs like `CLAUDE.md` and `CAPABILITIES.md` retain legacy Claude framing — consider generalizing further if needed.)

### filesystem-mcp
Full filesystem operations (read, write, update with search/replace, list, delete, create/move/copy directories). Supports relative/absolute paths and session defaults. Based on `@cyanheads/filesystem-mcp-server`. See launch scripts and tool descriptions.

### open-meteo-mcp
Current weather and multi-day forecasts (temperature, precipitation, wind, WMO codes, units support) via Open-Meteo API (no key required). Supports stdio and HTTP. See `mcps/open_meteo_mcp/README.md`.

### playwright-mcp
Powerful browser automation with Playwright: navigation, clicks, typing, form filling, screenshots, accessibility snapshots, JS evaluation, tabs, waits, console/network inspection, drag/drop, etc. Excellent for testing and scraping. See `mcps/playwright_mcp/README.md` (minimal; primary docs in bundled MCP).

### selenium-mcp
Alternative browser automation via Selenium WebDriver (multi-session support, smart waits, actionable errors, full page/content extraction). Streamable HTTP transport. See `mcps/selenium_mcp/README.md` for full tool list.

Additional MCP support (e.g., GitHub, US/UK weather) appears in some environments like Grok CLI.

## Skills

- **artifacts-builder**: Creates high-quality, multi-component HTML artifacts with React, TypeScript, Tailwind, shadcn/ui. Includes init/bundle scripts and anti-"slop" guidelines. See `SKILL.md`.
- **document-skills**: Comprehensive tools for DOCX, PDF, PPTX, XLSX — creation, editing, analysis, forms, merging, schema references. Subdirectories contain dedicated `SKILL.md` and references.
- **mcp-builder**: In-depth guide for building robust MCP servers (Python FastMCP or Node SDK). Covers research/planning, implementation, evaluation, best practices, agent-centric design. Highly recommended. See `SKILL.md`.
- **skill-creator**: Instructions for developing new reusable agent skills (structured prompts, examples, evaluation).
- **webapp-testing**: Playwright scripts and examples for testing local web applications.

## Compatibility & Documentation

- **MCP Specification**: https://github.com/modelcontextprotocol/modelcontextprotocol and https://modelcontextprotocol.info/docs/
- **Platform Notes**: 
  - Claude: Full native support; legacy docs in `skills/` and some MCP subfolders reference `claude.ai`, `platform.claude.com`, etc.
  - Grok: Leverages built-in MCP tool exposure and sub-agent system (`task`, `delegate`, `verify`, `computer_*` tools for desktop). Use `search_web`, `generate_image`, scheduling, wallet tools, etc., alongside these.
  - Others: Follow the MCP spec; adapt skills as context or custom tools.
- Individual MCP/skill folders contain detailed READMEs, `SKILL.md`, and references. Update legacy Claude-specific links/docs as you expand (e.g., replace Anthropic skill links with general MCP/agent guides).

## Grok CLI Configuration & Context

**Grok-Specific Setup** (in addition to the general MCP setup above):
- **.grokignore**: Controls what is automatically loaded into Grok CLI context (excludes binaries, node_modules, large DICOM/image dirs, build artifacts, legacy Claude folders, and this README to avoid bloat). Similar to .gitignore but focused on context efficiency.
- **.grok/context.md**: Persistent context document automatically referenced by Grok CLI. It includes:
  - Core principles for provider-agnostic workflows.
  - Sub-agent and tool preferences (e.g., proactive use of `task` with `explore`/`general`/`verify`/`computer`, `edit_file` over broad edits).
  - Directory guidance, best practices for MCP usage, DICOM QA, browser automation, and extending the repo.
  - Quick examples for common `mcp_*` tool calls.
- Usage: Grok CLI will include `.grok/context.md` by default. Reference it explicitly in prompts: "Follow the Grok CLI context in .grok/context.md, the updated README.md, and relevant SKILL.md files. Keep all outputs and changes provider-agnostic."

These files make Grok CLI Agent mode first-class in this repository alongside Claude support. See `.grok/context.md` for detailed best practices, workflow priorities, and MCP examples.

## Contributing

Update individual `README.md` / `SKILL.md` files (and `.grok/context.md` as needed) to remain provider-agnostic. Generalize hardcoded paths, Claude-centric examples, and titles where possible (e.g., `CLAUDE.md` → general guidelines). Test MCPs across platforms (Claude Desktop/Code, Grok CLI, others).

For questions or new MCP/skills, explore the `mcp-builder` and `skill-creator` guides first.