Metadata-Version: 2.4
Name: copick-mcp
Version: 0.3.0
Summary: MCP server for Copick.
Project-URL: Repository, https://github.com/copick/copick-mcp
Project-URL: Issues, https://github.com/copick/copick-mcp/issues
Project-URL: Documentation, https://github.com/copick/copick-mcp#readme
Author-email: Kyle Harrington <czi@kyleharrington.com>, "Utz H. Ermel" <utz@ermel.me>
License: MIT License
        
        Copyright (c) 2025 copick
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: annotation,copick,cryo-et,cryoet,mcp,model-context-protocol,tomography
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: copick-torch
Requires-Dist: copick-utils
Requires-Dist: copick>=1.15.0
Requires-Dist: fastmcp>=0.1.0
Provides-Extra: dev
Requires-Dist: black>=25.1.0; extra == 'dev'
Requires-Dist: hatch-vcs>=0.4.0; extra == 'dev'
Requires-Dist: hatchling>=1.25.0; extra == 'dev'
Requires-Dist: ipython>=8.18.1; extra == 'dev'
Requires-Dist: pre-commit>=4.2.0; extra == 'dev'
Requires-Dist: ruff>=0.12.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=6.2.1; extra == 'test'
Requires-Dist: pytest>=8.4.1; extra == 'test'
Description-Content-Type: text/markdown

# Copick MCP Server

A Model Context Protocol (MCP) server for Copick that provides two sets of tools:
1. **Data Exploration Tools** - Browse and query copick project contents (read-only)
2. **CLI Introspection Tools** - Discover and validate copick CLI commands for building processing pipelines

## Features

- **Read-only data exploration** - List and inspect runs, picks, segmentations, meshes, tomograms, and project metadata
- **CLI discovery** - Dynamically discover all available copick CLI commands with full documentation
- **Command validation** - Validate copick CLI command syntax using Click's native parsing
- **Smart caching** - Efficient caching of copick project roots
- **Easy setup** - Simple CLI for registering with Claude Desktop or Claude Code

## Installation

```bash
cd copick-mcp
pip install -e .
```

## Quick Setup

### Register with Claude Desktop

Use the copick CLI to register the MCP server with Claude Desktop:

```bash
# Basic setup (default settings)
copick setup mcp

# Setup with custom server name
copick setup mcp --server-name "my-copick-server"

# Setup with default config path (optional - can be provided per-request)
copick setup mcp --config-path "/path/to/default/config.json"

# Check registration status
copick setup mcp-status
```

After setup:
1. Restart Claude Desktop completely
2. The Copick MCP tools should now be available
3. The server starts automatically when Claude Desktop connects

### Register with Claude Code

The MCP server can also be registered with Claude Code, either globally or for a specific project:

```bash
# Global setup (available in all Claude Code sessions)
copick setup mcp --target code-global

# Project-specific setup (creates .mcp.json in current directory)
copick setup mcp --target code-project

# Project-specific setup for a different directory
copick setup mcp --target code-project --project-path /path/to/project

# Check status for Claude Code
copick setup mcp-status --target code-global
copick setup mcp-status --target code-project
```

**Target options:**
- `desktop` (default) - Claude Desktop application
- `code-global` - Claude Code global config (`~/.claude.json`)
- `code-project` - Claude Code project-specific config (`.mcp.json` in project root)

### Manual Configuration (Optional)

If you prefer manual setup, add the following configuration to the appropriate file:

**Claude Desktop:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Claude Code:**
- Global: `~/.claude.json`
- Project-specific: `.mcp.json` in your project root

```json
{
  "mcpServers": {
    "copick-mcp": {
      "command": "python",
      "args": ["-m", "copick_mcp.main"],
      "env": {}
    }
  }
}
```

## Available Tools

### Data Exploration Tools (Read-Only)

All data exploration tools require a `config_path` parameter pointing to your copick configuration file.

#### `list_runs`
List all runs in a Copick project.
- **Args**: `config_path` (str)
- **Returns**: List of run names

#### `get_run_details`
Get detailed information about a specific run including voxel spacings, picks, meshes, and segmentations.
- **Args**: `config_path` (str), `run_name` (str)
- **Returns**: Comprehensive run details

#### `list_objects`
List all pickable objects defined in the project.
- **Args**: `config_path` (str)
- **Returns**: List of objects with properties (name, type, label, color, radius, etc.)

#### `list_picks`
List picks for a run with optional filtering.
- **Args**: `config_path` (str), `run_name` (str), `object_name` (optional), `user_id` (optional), `session_id` (optional)
- **Returns**: List of picks with point counts and sample coordinates

#### `list_meshes`
List meshes for a run with optional filtering.
- **Args**: `config_path` (str), `run_name` (str), `object_name` (optional), `user_id` (optional), `session_id` (optional)
- **Returns**: List of meshes

#### `list_segmentations`
List segmentations for a run with optional filtering.
- **Args**: `config_path` (str), `run_name` (str), `voxel_size` (optional), `name` (optional), `user_id` (optional), `session_id` (optional), `is_multilabel` (optional)
- **Returns**: List of segmentations with metadata

#### `list_tomograms`
List tomograms for a specific run and voxel spacing.
- **Args**: `config_path` (str), `run_name` (str), `voxel_spacing` (float)
- **Returns**: List of tomograms with feature information

#### `list_voxel_spacings`
List all voxel spacings available for a run.
- **Args**: `config_path` (str), `run_name` (str)
- **Returns**: List of voxel spacings with tomogram counts

#### `get_project_info`
Get general project information and statistics.
- **Args**: `config_path` (str)
- **Returns**: Project metadata and entity counts

#### `get_json_config`
Get the raw JSON configuration of the project.
- **Args**: `config_path` (str)
- **Returns**: Complete configuration dictionary

### CLI Introspection Tools

These tools help LLMs discover and validate copick CLI commands for building processing pipelines.

#### `list_copick_cli_commands`
List all available copick CLI commands hierarchically organized by group.
- **Returns**: Complete command tree including:
  - `main`: Core commands (add, browse, config, deposit, info, new, stats, sync)
  - `inference`: Inference commands (e.g., membrain-seg)
  - `training`: Training commands
  - `evaluation`: Evaluation commands
  - `process`: Processing commands (downsample, fit-spline, hull, skeletonize, etc.)
  - `convert`: Conversion commands (picks2seg, mesh2seg, seg2picks, etc.)
  - `logical`: Logical operations (clipmesh, clippicks, meshop, segop, etc.)

#### `get_copick_cli_command_info`
Get detailed information about a specific command.
- **Args**: `command_path` (str) - e.g., "convert.picks2seg" or "add"
- **Returns**: Full command details including:
  - Help text and short description
  - All parameters with types, defaults, and help text
  - Required vs optional parameters
  - Usage examples (if present in help)
  - Command group

#### `validate_copick_cli_command`
Validate a copick CLI command string using Click's syntax validation.
- **Args**: `command_string` (str) - e.g., "copick convert picks2seg --config /path/to/config.json ..."
- **Returns**: Validation result including:
  - Valid/invalid status
  - Missing required parameters
  - Parameter type errors
  - Helpful error messages from Click

## Usage Examples

### Data Exploration Workflow

```
User: "Show me all runs in my copick project at /data/my_project/config.json"

Assistant uses: list_runs(config_path="/data/my_project/config.json")

User: "What picks are available for run TS_001?"

Assistant uses: list_picks(config_path="/data/my_project/config.json", run_name="TS_001")

User: "Show me only the ribosome picks from user 'annotator1'"

Assistant uses: list_picks(
    config_path="/data/my_project/config.json",
    run_name="TS_001",
    object_name="ribosome",
    user_id="annotator1"
)
```

### CLI Discovery Workflow

```
User: "I want to convert picks to a segmentation. What copick command can do that?"

Assistant uses: list_copick_cli_commands()
# Discovers convert.picks2seg command

Assistant uses: get_copick_cli_command_info(command_path="convert.picks2seg")
# Gets full documentation and parameters
Assistant explains:
"The picks2seg command converts picks to segmentation by painting spheres at pick locations.
It requires:
- --config: Path to copick config
- --input: Picks URI (format: object_name:user_id/session_id)
- --output: Segmentation URI (format: name:user_id/session_id@voxel_spacing)
- --radius: Sphere radius in angstroms (default: 10.0)"

User: "Can you validate this command for me: copick convert picks2seg --config /data/config.json --input 'ribosome:user1/manual-001' --output 'ribosome:picks2seg/painted-001@10.0'"

Assistant uses: validate_copick_cli_command(
    command_string="copick convert picks2seg --config /data/config.json --input 'ribosome:user1/manual-001' --output 'ribosome:picks2seg/painted-001@10.0'"
)# Returns validation result: valid=True if syntax is correct
```

### Pipeline Building Workflow

```
User: "I want to build a pipeline that:
1. Converts ribosome picks to meshes
2. Computes the convex hull of those meshes
3. Converts the hulls to segmentations"

Assistant uses: list_copick_cli_commands()
# Discovers relevant commands in convert and process groups

Assistant uses: get_copick_cli_command_info(command_path="convert.picks2mesh")
Assistant uses: get_copick_cli_command_info(command_path="process.hull")
Assistant uses: get_copick_cli_command_info(command_path="convert.mesh2seg")
# Gets documentation for each command

Assistant suggests the pipeline:
"Here's a three-step pipeline for your workflow:

Step 1: Convert picks to meshes
copick convert picks2mesh --config /path/to/config.json \
    --input 'ribosome:user1/manual-001' \
    --output 'ribosome:pipeline/step1-meshes' \
    --method convex_hull

Step 2: Compute convex hull (if not done in step 1)
copick process hull --config /path/to/config.json \
    --input-mesh 'ribosome:pipeline/step1-meshes' \
    --output-mesh 'ribosome:pipeline/step2-hulls'

Step 3: Convert meshes to segmentation
copick convert mesh2seg --config /path/to/config.json \
    --input 'ribosome:pipeline/step2-hulls' \
    --output 'ribosome:pipeline/final-seg@10.0'"
```

## Management Commands

```bash
# Check MCP server status (Claude Desktop)
copick setup mcp-status

# Check status for Claude Code
copick setup mcp-status --target code-global
copick setup mcp-status --target code-project

# Remove MCP server configuration (Claude Desktop)
copick setup mcp-remove --server-name "copick-mcp"

# Remove from Claude Code
copick setup mcp-remove --server-name "copick-mcp" --target code-global
copick setup mcp-remove --server-name "copick-mcp" --target code-project

# Force removal without confirmation
copick setup mcp-remove --server-name "copick-mcp" --force
```

## Troubleshooting

1. **"MCP server not found"**: Ensure you've restarted Claude Desktop completely after configuration
2. **"Python module not found"**: Verify the package is installed and the Python path is correct in the config
3. **"Permission denied"**: Check that the Claude config directory is writable
4. **"Invalid JSON"**: Use `copick setup mcp-status` to validate your configuration
5. **"Command not found" during CLI introspection**: Ensure copick and all plugin packages (copick-torch, copick-utils) are installed
6. **"setup command not found"**: Make sure copick-mcp is installed (`pip install -e .` from the copick-mcp directory)

## Development

```bash
# Install in development mode
cd copick-mcp
pip install -e ".[dev]"

# Format code
black src/

# Lint
ruff check --fix src/

# Run the server locally for testing
python -m copick_mcp.main
```

## License

MIT License - See LICENSE file for details.

## Links

- [Copick Documentation](https://copick.github.io/copick)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [FastMCP](https://github.com/jlowin/fastmcp)
