inkscape-mcp

# Inkscape MCP — LLM full manifest

Version **2.6.0** (see `pyproject.toml`). Stack: **Python 3.12+**, **FastMCP ≥3.1**, **Inkscape** with CLI.

---

## Tools

### inkscape_file

Operations: **load**, **save**, **convert**, **info**, **validate**, **list_formats**.

Typical args: `operation`, `input_path`, `output_path`, `format` (for convert).

### inkscape_vector

Operations:

`trace_image`, `generate_barcode_qr`, `create_mesh_gradient`, `text_to_path`, `construct_svg`, `apply_boolean`, `path_inset_outset`, `path_simplify`, `path_clean`, `path_combine`, `path_break_apart`, `object_to_path`, `optimize_svg`, `scour_svg`, `measure_object`, `query_document`, `count_nodes`, `export_dxf`, `layers_to_files`, `fit_canvas_to_drawing`, `render_preview`, `generate_laser_dot`, `object_raise`, `object_lower`, `set_document_units`.

Many operations accept extra kwargs (e.g. barcode data, DPI, boolean `operation_type`); see tool docstrings and `docs/USAGE.md`.

### inkscape_analysis

Operations: **quality**, **statistics**, **validate**, **objects**, **dimensions**, **structure**.

### inkscape_system

Operations: **status**, **help**, **diagnostics**, **version**, **config**, **list_extensions**, **execute_extension** (when enabled).

### list_local_models

No required args — returns discovered local LLM endpoints (Ollama / LM Studio) when reachable.

### generate_heraldry

Args: `operation` (`trumponia` | `custom`), `output_path`, optional `ctx` for future sampling hooks. **custom** may return not-implemented.

### Agentic / sampling (optional)

Registered when `agentic` imports succeed and the host supports MCP sampling:

- **generate_svg** — multi-step SVG generation via `ctx.sample()` / SEP-1577 loop
- **agentic_inkscape_workflow** — orchestrated workflows
- **intelligent_vector_processing** — vector-focused agentic path
- **conversational_inkscape_assistant** — dialog-style assistance

If sampling is unavailable, these tools return structured errors; use non-agentic `inkscape_*` tools instead. Details: `docs/AI_SAMPLING.md`.

---

## MCP prompts (registered)

| URI | Purpose |
|-----|---------|
| `prompt://inkscape/svg-file-workflow` | load / convert / validate flows |
| `prompt://inkscape/vector-editing-workflow` | vector ops and booleans |
| `prompt://inkscape/analysis-workflow` | inspect before edit |
| `prompt://inkscape/sampling-agentic-workflow` | when to use agentic tools |
| `prompt://inkscape/heraldry-workflow` | heraldry generation |

---

## MCP resources (registered)

| URI | Purpose |
|-----|---------|
| `resource://inkscape/capabilities` | short capability summary |
| `resource://inkscape/skills` | operation cheat sheet for LLMs |

---

## Environment

| Variable | Role |
|----------|------|
| `MCP_TRANSPORT` | `stdio` (default for many clients) or `http` |
| `MCP_HOST` | HTTP bind (default `127.0.0.1`) |
| `MCP_PORT` | HTTP port (default **11028** in this project) |
| `MCP_PATH` | HTTP MCP path (default `/mcp`) |
| `INKSCAPE_PATH` / config | Override Inkscape executable |
| `INKSCAPE_MCP_CONFIG_PATH` | Optional YAML config path |
| `OLLAMA_BASE_URL`, `OLLAMA_MODEL` | REST `/api/generate-svg` and health |
| `GEMINI_API_KEY`, `ANTHROPIC_API_KEY` | Optional cloud fallbacks in REST SVG pipeline |
| `INKSCAPE_SAVE_DIR` | Default output dir for REST-generated SVGs (see `app.py`) |

Config file fields (YAML) commonly include: `inkscape_executable`, `process_timeout`, `max_concurrent_processes`, `allowed_directories`, `temp_directory` — see `docs/` and sample config in repo.

---

## Run

### Obtain source first (fleet bar)

```text
git clone https://github.com/sandraschi/inkscape-mcp.git
cd inkscape-mcp
uv sync
```

### MCP stdio (typical IDE)

```text
uv run inkscape-mcp --mode stdio
```

Or with explicit transport via env:

```text
set MCP_TRANSPORT=stdio
uv run inkscape-mcp
```

(PowerShell: `$env:MCP_TRANSPORT="stdio"` then `uv run inkscape-mcp`.)

### HTTP (MCP + REST + dashboard backend)

```text
uv run inkscape-mcp --mode http --port 11028
```

### Web dashboard (separate terminal, from `web_sota`)

Follow project webapp docs; Vite dev server uses **11029** and proxies to **11028**.

### PyPI / uvx (consumers)

```text
uvx inkscape-mcp --help
```

---

## Architecture (sketch)

- **Entry:** `inkscape_mcp.main` → `InkscapeMCPServer` → `FastMCP` instance
- **Tools:** `tools/file_operations.py`, `vector_operations.py`, `analysis.py`, `system.py`, `heraldry.py`, `llm_discovery.py`; wrappers in `main.py` for dependency injection (`cli_wrapper`, `config`)
- **Agentic:** `agentic.py` (sampling)
- **Prompts/resources:** `prompts_resources.py`
- **Transport:** `transport.py` (stdio / HTTP / env bridge)
- **REST:** `app.py` mounts on FastMCP HTTP (`/api/health`, `/api/help`, `/api/logs`, …)
- **MCPB:** `mcp-server/` tree, `tools/sync_mcpb_src.py`, `tools/pack_mcpb.py`

---

## MCP client snippets

### uv (recommended, repo root)

```json
{
  "mcpServers": {
    "inkscape-mcp": {
      "command": "uv",
      "args": ["--directory", "${workspaceFolder}", "run", "inkscape-mcp", "--mode", "stdio"]
    }
  }
}
```

### python module (when package on `PYTHONPATH`)

```json
{
  "command": "python",
  "args": ["-m", "inkscape_mcp.main", "--mode", "stdio"],
  "env": { "PYTHONPATH": "${workspaceFolder}/src" }
}
```

See also `cursor-mcp-config.json` and `glama.json` in the repo root.

---

## Troubleshooting (top issues)

1. **Inkscape not found** — Install Inkscape; set `INKSCAPE_PATH` or PATH; run `inkscape --version` locally.
2. **Permission / path denied** — Configure `allowed_directories` and use paths inside it.
3. **Agentic tools fail** — Host does not support sampling; use `inkscape_*` tools manually.
4. **HTTP / dashboard empty** — Start server with `--mode http` and matching `MCP_PORT`; start Vite on **11029**.
5. **MCPB out of date** — Run `just mcpb-pack` after code changes; reinstall bundle in Claude Desktop.

---

## Fleet / related docs

Central standards: **mcp-central-docs** (`DOCUMENTATION_STANDARDS.md`, `PACKAGING_STANDARDS.md` §5, `SOTA_REQUIREMENTS.md`).

This file should be updated in the same PR as tool or operation renames.