# MCP Server Integration

The Kumiho Python SDK includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
server that enables AI assistants like GitHub Copilot, Claude, and other MCP-compatible
clients to interact with Kumiho Cloud directly.

## What is MCP?

The Model Context Protocol is an open standard that allows AI assistants to connect
to external data sources and tools. By exposing Kumiho's functionality through MCP,
AI assistants can:

- Query and navigate your asset graphs
- Analyze dependencies and impact of changes
- Search for items across projects
- Track AI lineage and provenance
- Create, update, and manage revisions and artifacts
- Build and manage bundles

## Installation

Install the Kumiho SDK with MCP support:

```bash
pip install kumiho[mcp]
```

Or if you already have kumiho installed:

```bash
pip install mcp httpx
```

## Authentication

Before running the MCP server, authenticate with Kumiho Cloud:

```bash
kumiho-auth login
```

This caches your credentials which the MCP server will use automatically.

## Running the MCP Server

### Standalone Mode

Run the MCP server directly:

```bash
kumiho-mcp
```

Or using Python module:

```bash
python -m kumiho.mcp_server
```

### VS Code / GitHub Copilot Integration

Add the following to your VS Code `settings.json`:

```json
{
    "mcp": {
        "servers": {
            "kumiho": {
                "command": "kumiho-mcp",
                "args": []
            }
        }
    }
}
```

Alternatively, if using a virtual environment:

```json
{
    "mcp": {
        "servers": {
            "kumiho": {
                "command": "python",
                "args": ["-m", "kumiho.mcp_server"],
                "env": {
                    "PATH": "/path/to/your/venv/bin:${env:PATH}"
                }
            }
        }
    }
}
```

### Claude Desktop Integration

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
    "mcpServers": {
        "kumiho": {
            "command": "kumiho-mcp"
        }
    }
}
```

## Available Tools

The MCP server exposes 39 tools organized by category:

### Read Operations (14 tools)

| Tool | Description |
|------|-------------|
| `kumiho_list_projects` | List all accessible projects |
| `kumiho_get_project` | Get project details by name |
| `kumiho_get_spaces` | Get spaces within a project |
| `kumiho_get_space` | Get a space by path |
| `kumiho_get_item` | Get an item by kref URI |
| `kumiho_search_items` | Search items with filters |
| `kumiho_get_item_revisions` | Get all revisions for an item |
| `kumiho_get_revision` | Get a revision by kref |
| `kumiho_get_revision_by_tag` | Get revision by tag (latest, published, etc.) |
| `kumiho_get_artifacts` | Get all artifacts for a revision |
| `kumiho_get_artifact` | Get a single artifact by kref |
| `kumiho_get_bundle` | Get a bundle by kref |
| `kumiho_resolve_kref` | Resolve kref to file location |
| `kumiho_get_artifacts_by_location` | Reverse lookup artifacts by file path |

### Graph Traversal (5 tools)

| Tool | Description |
|------|-------------|
| `kumiho_get_dependencies` | Get what a revision depends on |
| `kumiho_get_dependents` | Get what depends on a revision |
| `kumiho_analyze_impact` | Analyze downstream impact of changes |
| `kumiho_find_path` | Find shortest path between revisions |
| `kumiho_get_edges` | Get edges (relationships) for a revision |

### Create Operations (8 tools)

| Tool | Description |
|------|-------------|
| `kumiho_create_project` | Create a new project |
| `kumiho_create_space` | Create a space within a project |
| `kumiho_create_item` | Create an item within a space |
| `kumiho_create_revision` | Create a new revision for an item |
| `kumiho_create_artifact` | Create an artifact for a revision |
| `kumiho_create_bundle` | Create a bundle to group items |
| `kumiho_create_edge` | Create relationship between revisions |
| `kumiho_tag_revision` | Apply a tag to a revision |

### Delete Operations (6 tools)

| Tool | Description |
|------|-------------|
| `kumiho_delete_project` | Delete a project |
| `kumiho_delete_space` | Delete a space |
| `kumiho_delete_item` | Delete an item |
| `kumiho_delete_revision` | Delete a revision |
| `kumiho_delete_artifact` | Delete an artifact |
| `kumiho_delete_edge` | Delete a relationship |

### Update Operations (6 tools)

| Tool | Description |
|------|-------------|
| `kumiho_untag_revision` | Remove a tag from a revision |
| `kumiho_set_metadata` | Set metadata on item or revision |
| `kumiho_deprecate_item` | Mark an item as deprecated |
| `kumiho_add_bundle_member` | Add an item to a bundle |
| `kumiho_remove_bundle_member` | Remove an item from a bundle |
| `kumiho_get_bundle_members` | List all items in a bundle |

## Example Conversations

Once configured, you can ask your AI assistant questions like:

### Exploring Assets

> "List all projects I have access to"

> "What items are in the 'characters' space of project 'film-2024'?"

> "Show me all revisions for kref://film-2024/characters/hero.model"

### Dependency Analysis

> "What does the hero model depend on?"

> "If I change this texture, what assets will be affected?"

> "Find the path between the hero rig and the final render"

### Asset Management

> "Create a new revision for kref://film-2024/props/sword.model with metadata artist='john'"

> "Tag revision kref://film-2024/characters/hero.model?r=5 as 'approved'"

> "Add the hero model to the 'main-characters' bundle"

### AI Lineage Tracking

> "What training data was used to generate this AI asset?"

> "Show me all assets derived from this base model"

## Kref URI Format

Tools use Kref URIs to reference Kumiho objects:

```
kref://project/space/item.kind           # Item
kref://project/space/item.kind?r=1       # Revision (r=revision number)
kref://project/space/item.kind?r=1&a=mesh  # Artifact (a=artifact name)
```

Examples:
- `kref://film-2024/characters/hero.model` - Hero model item
- `kref://film-2024/characters/hero.model?r=3` - Revision 3
- `kref://film-2024/characters/hero.model?r=3&a=mesh.fbx` - Mesh artifact

## Edge Types

When creating or querying edges, use these relationship types:

| Edge Type | Description |
|-----------|-------------|
| `DEPENDS_ON` | Asset depends on another asset |
| `DERIVED_FROM` | Asset was derived from another |
| `REFERENCED` | Asset references another |
| `CONTAINS` | Asset contains another |
| `CREATED_FROM` | AI asset created from training data |
| `BELONGS_TO` | Asset belongs to a bundle |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `KUMIHO_MCP_LOG_LEVEL` | Log level (DEBUG, INFO, WARNING, ERROR) | INFO |

## MCP Resources and Prompts

The server also exposes:

### Resources

Projects are exposed as MCP resources with URI format `kumiho://project/{name}`.

### Prompts

| Prompt | Description |
|--------|-------------|
| `analyze_asset` | Guided workflow to analyze an asset's dependencies and impact |
| `find_assets` | Guided workflow to search for assets by kind and project |

## Troubleshooting

### Server won't start

1. Ensure MCP dependencies are installed:
   ```bash
   pip install kumiho[mcp]
   ```

2. Check authentication:
   ```bash
   kumiho-auth status
   ```

3. Enable debug logging:
   ```bash
   KUMIHO_MCP_LOG_LEVEL=DEBUG kumiho-mcp
   ```

### Tools not appearing in AI assistant

1. Verify the MCP configuration in your settings
2. Restart your AI assistant/editor
3. Check the MCP server logs for connection errors

### Authentication errors

Refresh your credentials:
```bash
kumiho-auth refresh
```

Or re-authenticate:
```bash
kumiho-auth login
```

## API Reference

For detailed API documentation of the MCP server module, see the
[MCP Server API Reference](api/mcp_server.rst).