Asymptote Geometry Renderer

@luorivergoddess/mcp-geo

An MCP (Model Context Protocol) server for generating precise geometric images using Asymptote. This server allows AI models compatible with MCP to request image generation by providing Asymptote code.

Prerequisites

Before using this server, please ensure you have the following installed:

1. Node.js: Version 16.x or higher is recommended. You can download it from nodejs.org.
2. Asymptote: This is a critical dependency. The asy command-line tool must be installed and accessible in your system's PATH.
   • Visit the Asymptote official website for download and detailed installation instructions.
   • Common installation methods:
     • macOS (via Homebrew): brew install asymptote
     • Debian/Ubuntu Linux: sudo apt-get install asymptote
     • Windows: Often installed as part of TeX distributions like MiKTeX or TeX Live. Ensure the Asymptote bin directory is added to your PATH.
   • The server will attempt to check for asy -version on startup and print an error if it's not found.

Installation

To install this package globally (if you intend to run connect command directly) or as a dependency in another project:

npm install @luorivergoddess/mcp-geo

If you've cloned the repository and want to run it locally for development:

1. Clone the repository.
2. Install dependencies: npm install
3. Build the project: npm run build

Usage

Starting the Server

Once the package is installed (e.g., globally or linked locally), you can start the MCP server using the connect command provided by this package. This command is intended to be invoked by an MCP client.

npx @luorivergoddess/mcp-geo connect

Or, if you have cloned the repository and built it:

node dist/cli.js

The server will start and listen for JSON-RPC messages on stdin/stdout, using the @modelcontextprotocol/sdk.

MCP Client Integration

Configure your MCP-compatible client (e.g., VS Code with Copilot Agent Mode, Claude Desktop) to use this server. This usually involves telling the client how to start the server, which would be the npx @luorivergoddess/mcp-geo connect command.

Available Tool: renderGeometricImage

The server exposes one primary tool:

• Name: renderGeometricImage
• Description: Renders an image from Asymptote code.
• Input Schema:

  {
    "type": "object",
    "properties": {
      "asyCode": {
        "type": "string",
        "description": "A string containing complete and valid Asymptote code to be compiled. The server executes this code directly. Ensure necessary `import` statements (e.g., `import graph;`) and settings (e.g., `unitsize(1cm);`) are included within this code block if needed."
      },
      "outputParams": {
        "type": "object",
        "description": "Optional parameters to control the output image.",
        "properties": {
          "format": {
            "type": "string",
            "enum": ["svg", "png"],
            "description": "The desired output image format. \"svg\" for scalable vector graphics (recommended for diagrams and plots), \"png\" for raster graphics. Defaults to \"svg\" if not specified."
          },
          "renderLevel": {
            "type": "number",
            "description": "For PNG output only. Specifies the rendering quality (supersampling level for antialiasing). Higher values (e.g., 4 or 8) produce smoother images but take longer to render and result in larger files. Asymptote default is 2. This server defaults to 4 if not specified and format is \"png\". Ignored for SVG output."
          }
        }
      }
    },
    "required": ["asyCode"]
  }
  

• Output: The tool returns a CallToolResult containing an array of content parts.
  • If successful, it includes an ImageContent part with:
    • type: "image"
    • mimeType: "image/svg+xml" or "image/png"
    • data: "<base64_encoded_image_data>"
  • It may also include a TextContent part with logs from Asymptote.
  • If an error occurs, it throws an McpError.

Example renderGeometricImage call (JSON for arguments field):

{
  "asyCode": "draw(unitsquare); fill(unitsquare, lightblue);",
  "outputParams": {
    "format": "png",
    "renderLevel": 4
  }
}

Client Compatibility Notes:

• Some MCP clients may have limitations on supported image MIME types.
• For instance, if you are using this server with a client that does not support image/svg+xml (e.g., certain versions or configurations of "Cherry Studio" as reported), please ensure you request the png format by including "outputParams": { "format": "png" } in your tool call arguments. The server defaults to svg if no format is specified.

Author

luorivergoddess

License

ISC