Flywheel Gear Dev

Give Claude expert knowledge of Flywheel gear development while you code.

The Problem

Developing gears for Flywheel means wrestling with documentation scattered across 10+ sources—many deprecated, conflicting, or redundant. You're constantly switching between browser tabs, searching for the right API reference, and wondering if what you're reading is still current.

The Solution

This MCP (Model Context Protocol) server gives Claude Code direct access to all of the Flywheel and DICOM documentation on command. Now when you ask Claude "What's the correct way to write a DICOM secondary?", it can reference the actual current specs—no hallucination or without loading all of the DICOM standard docs into memory and clogging up your context.

What's MCP? It's a protocol that lets Claude Code access external tools and data. This server runs locally on your machine (started and stopped by claude only in the directory that you are developing a Flywheel gear) and feeds fresh Flywheel docs to Claude on demand.

Who is this for? Flywheel developers using Claude Code CLI to build gears.

Quick Start

# 1. Clone and install the MCP server
git clone https://github.com/wzkariampuzha/flywheel-gear-dev-mcp.git
cd flywheel-gear-dev-mcp
uv sync

# 2. Navigate to your gear project
cd /path/to/your/gear-project

# 3. Add the MCP server
claude mcp add flywheel-gear-dev \
  --scope local \
  -- uv run --directory /full/path/to/flywheel-gear-dev-mcp flywheel-gear-mcp

# 4. Start Claude Code and ask:
# "Show me the gear manifest schema requirements"

Configuration

Two ways to configure the server in your gear project:

Option 1: CLI (Recommended)

From your gear project directory:

claude mcp add flywheel-gear-dev \
  --scope local \
  -- uv run --directory /absolute/path/to/flywheel-gear-dev-mcp flywheel-gear-mcp

Option 2: .mcp.json file

Create .mcp.json in your gear project:

{
  "mcpServers": {
    "flywheel-gear-dev": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/flywheel-gear-dev-mcp", "flywheel-gear-mcp"]
    }
  }
}

Usage

Starting the server

The server is automatically started by Claude Code when you launch a session.

Using the tools in Claude Code

Once configured, you can ask Claude to use the documentation tools:

"Can you get the fw-gear documentation?"
"Show me the DICOM standard data dictionary"
"What are the gear manifest schema requirements?"

Features

• Fresh documentation on startup: Fetches latest docs every time the server starts
• 10 curated documentation sources: Flywheel gear libraries, APIs, DICOM standard, and guides that you can add/remove/edit in config
• Deprecation filtering: Automatically removes deprecated content to keep LLMs focused on current APIs

Available tools

• get_fw_gear_docs - fw-gear library documentation
• get_fw_classification_docs - fw-classification library
• get_fw_file_docs - fw-file library
• get_flywheel_api_docs - Flywheel platform Python API
• get_dicom_standard - DICOM standard (filtered to data dictionary and transfer syntaxes)
• get_file_types_guide - Flywheel file types guide
• get_bids_guide - BIDS in Flywheel guide
• get_batch_gears_guide - Batch gear execution guide
• get_gear_specs - Gear specifications
• get_manifest_schema - Gear manifest JSON schema
• list_available_docs - List all cached documentation sources

Customizing documentation sources

Edit config.yaml to add, remove, or modify documentation sources:

documentation_sources:
  - tool_name: get_my_custom_docs
    display_name: "My Custom Documentation"
    description: "Description here"
    urls:
      - https://example.com/docs
    type: html  # or xml, json, gitlab_repo
    strip_deprecated: true

Supported types

• html - HTML documentation (auto-converts to markdown)
• xml - XML documentation (for DICOM standard)
• json - JSON schemas
• gitlab_repo - GitLab repository markdown files

How It Works

1. One-time setup: Install the MCP server code once, configure it in your gear projects
2. Automatic startup: When you run claude in your gear project, Claude Code automatically starts this MCP server in the background
3. On-demand docs: When Claude needs Flywheel documentation, it calls this server via MCP protocol
4. Fresh data: The server fetches latest docs from URLs on first request, caches them for the session
5. Automatic shutdown: Server stops when you exit Claude Code

The server runs locally—no data leaves your machine.

Troubleshooting

Server won't start

1. Check Python version: Requires Python 3.13+
2. Check dependencies: Run uv sync again
3. Check log files: Review logs/flywheel-gear-mcp.log for detailed error messages

Documentation not loading

1. Check network: Ensure you can access Flywheel documentation URLs
2. Check logs: Review logs/flywheel-gear-mcp.log or run with verbose flag: flywheel-gear-mcp --verbose
3. Test URLs: Verify URLs in config.yaml are accessible

Tools not appearing in Claude Code

1. Restart Claude Code after configuration changes
2. Check config.json syntax: Ensure valid JSON
3. Check server status: Look for MCP server errors in Claude Code logs

Contributing

Contributions welcome! Please open an issue or PR.