@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:
- Node.js: Version 16.x or higher is recommended. You can download it from nodejs.org.
- Asymptote: This is a critical dependency. The
asycommand-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
bindirectory is added to your PATH.
- macOS (via Homebrew):
- The server will attempt to check for
asy -versionon 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:
- Clone the repository.
- Install dependencies:
npm install - 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
CallToolResultcontaining an array of content parts.- If successful, it includes an
ImageContentpart with:type: "image"mimeType: "image/svg+xml"or"image/png"data: "<base64_encoded_image_data>"
- It may also include a
TextContentpart with logs from Asymptote. - If an error occurs, it throws an
McpError.
- If successful, it includes an
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 thepngformat by including"outputParams": { "format": "png" }in your tool call arguments. The server defaults tosvgif no format is specified.
Author
luorivergoddess
License
ISC