README.md•4.99 kB
# @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](https://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](https://asymptote.sourceforge.io/) 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:
```bash
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.
```bash
npx @luorivergoddess/mcp-geo connect
```
Or, if you have cloned the repository and built it:
```bash
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:**
```json
{
"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):**
```json
{
"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