fwip/unison-mcp-demo

Unison MCP Server

A Model Context Protocol (MCP) server for interacting with Unison codebase manager.

Overview

This MCP server provides an interface for LLMs to interact with a Unison codebase through the Unison API. It exposes resources that allow models to query information about the Unison codebase - mostly retrieving definitions.

MCP Features

• Browse the namespaces in the project
• Retrieve definitions of terms and types
• Find terms and types via substring-matching
• List all projects/branches in a Unison codebase
• Project/branch selection (automatic to the current UCM context, but can be set 'manually')

Possible future work:

• Dependency graph retrieval - see what terms/functions depend on which
• 'Eject' a namespace into a scratch file
• Safe REPL for arbitrary Unison expressions - might require a 'captive' UCM instance
• Auto doc retrieval
• Automatic extraction of examples from documentation
• Search by type signatures
• Hints to help LLM navigate the codebase more effectively - e.g: recommending starting with README
• The ability to search Unison Share, to help identify possible libraries to use

Setup

Prerequisites

• Python 3.12 or higher
• Unison (ucm).

Usage

Installation

You need to make this MCP server available to your LLM. I'm not sure on the best way to do this, but here is my setup:

I use VSCode, so I set two settings to true:

"chat.mcp.discovery.enabled": true,
"chat.mcp.enabled": true

I then ran uv run mcp install main.py - this put the following info in my Claude Desktop config file:

{
  "mcpServers": {
    "unison": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/absolute/path/to/unison_mcp/main.py"
      ]
    }
  }
}

Reference used: [https://code.visualstudio.com/docs/copilot/chat/mcp-servers]

Development

To add new resources, create additional resource handlers using the @mcp.resource() decorator.

Development Tools

This project is set up to use uv, ruff, pre-commit, and mypy.

Setup Development Environment

Run the setup script to install development dependencies and pre-commit hooks:

./setup_dev.sh

Code Quality Tools - quickstart

• Formatting & Linting: We use Ruff for both formatting and linting

  # Check code style
  uvx ruff check .
  
  # Apply automatic fixes
  uvx ruff check --fix .
  
  # Format code
  uvx ruff format .
  

• Type Checking: MyPy is used for static type checking

  uvx mypy .
  

• Pre-commit Hooks: All checks run automatically on commit

  # Run all checks manually
  pre-commit run --all-files
  

The configuration for these tools is in pyproject.toml and pre-commit-config.yaml.

License

MIT