MCP Harmony Context

An MCP (Model Context Protocol) server that provides context about Toon Boom Harmony and its scripting API. This server allows AI assistants to access Harmony's API documentation and help developers work with Harmony's scripting capabilities.

---

Author

Jorge Hernandez Ibañez Copyright (c) 2025

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Overview

The MCP Harmony Context server exposes Harmony's API documentation through the Model Context Protocol, making it easy for AI assistants to provide accurate information about Harmony's scripting API. The server reads from your local Harmony installation's help documentation and provides it in a clean, accessible format.

Features

• API Class Discovery: Browse all available Harmony API classes with descriptions
• Class Documentation: Get detailed documentation for any Harmony API class
• Demo Scripts Access: Access to Harmony's Script API demo files
• Clean Markdown Output: HTML documentation converted to readable markdown format

---

Requirements

• Python 3.12 or higher
• Toon Boom Harmony installed locally (for access to API documentation)
• uv package manager (recommended) or pip

Dependencies

The following Python packages are required:

• mcp[cli]>=1.18.0 - Model Context Protocol framework with CLI support
• python-dotenv>=1.0.0 - Environment variable management
• beautifulsoup4>=4.12.0 - HTML parsing
• html2text>=2024.2.26 - HTML to markdown conversion

---

Installation

1. Install uv (recomended)

We recommend using uv to manage the mcp project.

2. Clone the repository

git clone https://github.com/yourusername/mcp-harmony-context.git
cd mcp-harmony-context

3. Install dependencies

uv sync

Alternatively, using pip:

pip install -r requirements.txt
# Or install dependencies directly:
pip install "mcp[cli]>=1.18.0" python-dotenv beautifulsoup4 html2text

4. Configure Harmony help path

The server needs to know where your Harmony help documentation is located.

Option 1: .env File (recomended)

Create a .env file in the project root:

HARMONY_HELP_PATH=C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 25 Essentials\help

Default Path: If not configured, the server defaults to: C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 25 Essentials\help

---

Option 2: Environment Variable

Set the HARMONY_HELP_PATH environment variable:

# Windows (Command Prompt)
set HARMONY_HELP_PATH=C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 25 Essentials\help

# Windows (PowerShell)
$env:HARMONY_HELP_PATH="C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 25 Essentials\help"

# macOS/Linux
export HARMONY_HELP_PATH="/Applications/Toon Boom Harmony/help"

Usage

Running the MCP Server

Start the server using uv:

uv run main.py

Or with Python directly:

python main.py

Testing with MCP Inspector

You can test the server interactively using the MCP inspector:

mcp dev main.py

This will open an interactive interface where you can explore available resources and tools.

Integrating with Claude Desktop

To use this MCP server with Claude Desktop, add it to your Claude configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "harmony-context": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-harmony-context",
        "run",
        "main.py"
      ],
      "env": {
        "HARMONY_HELP_PATH": "C:\\Program Files (x86)\\Toon Boom Animation\\Toon Boom Harmony 25 Essentials\\help"
      }
    }
  }
}

Replace /path/to/mcp-harmony-context with the actual path to your cloned repository.

Using with Other MCP Clients

This server follows the standard MCP protocol and can be integrated with any MCP-compatible client. Refer to your client's documentation for specific integration instructions.

---

Available Resources

Once the server is running, the following resources are available:

harmony://api/classes

Returns a list of all available Harmony API classes with their descriptions.

Example Response:

# Available Harmony API Classes (150+ total)

## Action
The Action class provides methods for manipulating actions in Harmony...

## Color
The Color class provides methods for working with colors...

harmony://api/class/{class_name}

Returns detailed documentation for a specific API class.

Example: harmony://api/class/scene

Example Response:

# scene Class Documentation

Detailed documentation including:
- Class description
- Methods and their signatures
- Method parameters and return types
- Usage examples

harmony://config/scripts-demo-path

Returns the configured path to Harmony's Script API demo files.

---

Project Structure

mcp-harmony-context/
├── main.py              # Main MCP server implementation
├── pyproject.toml       # Project dependencies and metadata
├── uv.lock              # Locked dependency versions
├── LICENSE              # MIT License
├── README.md            # This file
├── CLAUDE.md            # Development guidance for Claude Code
└── .env                 # Environment configuration (create from .env.example)

---

Development

Prerequisites

• Python 3.12+
• uv package manager
• Toon Boom Harmony installed

Setup for Development

1. Clone the repository
2. Run uv sync to install dependencies
3. Configure your HARMONY_HELP_PATH
4. Run mcp dev main.py to test interactively

Code Structure

The server is built using FastMCP and follows these conventions:

• Resources: Defined with @mcp.resource() decorator
• Tools: Defined with @mcp.tool() decorator (extensible)
• URI Pattern: Resources use harmony:// scheme with hierarchical paths

---

Troubleshooting

"Script path does not exist" Error

Problem: The server can't find your Harmony help documentation.

Solution:

1. Verify your Harmony installation path
2. Check that the help folder exists at that location
3. Update your HARMONY_HELP_PATH environment variable or .env file

"No classes found" Error

Problem: The server can't parse the API class list.

Solution:

1. Ensure your Harmony installation includes the script documentation
2. Check that annotated.html exists in the script folder
3. Verify you have read permissions for the help folder

Import Errors

Problem: Missing Python dependencies.

Solution:

uv sync
# Or
pip install -r requirements.txt

---

Contributing

Contributions are welcome! Please feel free to submit issues, fork the repository, and create pull requests.

---

Acknowledgments

• Built with FastMCP - A framework for building MCP servers
• Uses BeautifulSoup for HTML parsing
• Uses html2text for markdown conversion

---

Support

For issues, questions, or contributions, please visit the GitHub repository. Developer contact: info@jorgehi.com

---

Related Links

• Model Context Protocol
• Toon Boom Harmony
• Harmony Scripting Documentation