星战科技xingzhan.cloud
返回市场
TikzHTTP服务端

TikzHTTP服务端

作者：JoeChen2me3 星标更新：2025-07-16
安装使用来源：spider==github.com

项目介绍

技术文档摘要

TikZ HTTP MCP 服务器

说明

该项目源自一个现有的开源项目：tikz-mcp-server

  • 在此基础上添加了一个HTTP流接口，支持远程部署。
  • 添加了一键部署脚本，以实现自定义的一键部署。

这是一个基于模型上下文协议（MCP）的HTTP服务器，专门设计用于将TikZ/LaTeX代码渲染成高质量的PNG图像。它提供了一个render_tikz工具，允许客户端通过HTTP请求提交TikZ代码，并接收渲染后的图像。

兼容Cherry Studio客户端

特性

  • TikZ渲染：将TikZ/LaTeX代码编译成PNG图像，并支持直接返回base64编码的图像数据或可访问的图像URL。
  • MCP兼容：作为MCP服务器运行，提供render_tikz_base64、render_tikz_url和install_tex_package三种工具。
  • 自动清理图像：生成的图像将定期自动清理，默认为1天。
  • 最小化镜像：提供仅包含必要TeX包的最小Docker镜像，显著减小镜像大小。
  • Docker部署：提供deploy.sh脚本以简化Docker环境中的部署。
  • 错误处理：捕获LaTeX编译和图像转换过程中的错误，并提供详细的错误信息。

启动方法

前提条件

在启动服务器之前，请确保您的系统已安装以下软件：

  • Docker：用于容器化部署。
  • Docker Compose：用于管理多容器Docker应用程序。

环境变量配置

项目使用.env文件来配置环境变量。您可以复制.env.example文件并重命名为.env，然后根据需要修改值。

cp .env.example .env

.env文件包含以下示例变量：

  • SERVICE_NAME：Docker Compose服务的名称，默认为tikz-mcp-server。
  • CONTAINER_NAME：Docker容器的显式名称，默认为tikz-mcp-server-container。
  • PORT：服务监听的外部端口，默认为3000。
  • PUBLIC_IP：公共IP地址，用于生成图像URL，默认为localhost。
  • PUBLIC_PORT：公共网络端口，用于生成图像URL，默认为3000。
  • DOMAIN：（可选）域名，如果设置，则优先使用HTTPS域名生成图像URL，例如https://tikz.yourdomain.com

部署步骤

完整镜像部署（包括所有TeX包，体积较大）

  1. 克隆仓库（如果尚未克隆）：

    git clone git@github.com:JoeChen2me/tikz-http-mcp-server.git
cd tikz-http-mcp-server

  2. 运行部署脚本： 首先，确保deploy.sh脚本具有执行权限：

    chmod +x deploy.sh

    然后，执行deploy.sh脚本来构建Docker镜像并启动服务：

    ./deploy.sh

最小化镜像部署（仅包含必要的TeX包，体积较小）

  1. 运行最小化部署脚本： 首先，确保deploy-minimal.sh脚本具有执行权限：

    chmod +x deploy-minimal.sh

    然后，执行该脚本来构建最小化的Docker镜像：

    ./deploy-minimal.sh

镜像大小比较

  • 完整镜像：约2-3GB（包括完整的TeX Live）
  • 最小化镜像：约500-800MB（仅包含必需的包）

本地测试运行

前提条件

要本地运行Python脚本，需要安装以下依赖项：

系统依赖项（macOS/Linux）

# macOS
brew install imagemagick mactex

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y texlive-xetex texlive-latex-recommended texlive-pictures imagemagick fonts-noto-cjk

# CentOS/RHEL
sudo yum install -y texlive-xetex texlive-latex-recommended texlive-pictures ImageMagick fonts-noto-cjk

Python依赖项

pip install mcp starlette uvicorn click anyio

本地启动测试

  1. 创建图像目录

    mkdir -p images

  2. 启动服务器

    python3 tikz_http_server.py --port 3000 --log-level INFO

  3. 工具列表

    curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/list","params":{}}'

  4. 测试TikZ渲染

    curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method":"tools/call",
    "params":{
      "name":"render_tikz_base64",
      "arguments":{"tikz_code":"\\begin{tikzpicture}\\draw (0,0) circle (1cm);\\end{tikzpicture}"}
    }
  }'

  5. 测试并安装TeX包（仅当需要时）

    curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method":"tools/call",
    "params":{
      "name":"install_tex_package",
      "arguments":{"package_name":"pgfplots"}
    }
  }'

环境变量

本地运行时可以使用以下环境变量：

  • PUBLIC_IP：公共IP地址（默认：localhost）
  • PUBLIC_PORT：公共网络端口（默认：3000）
  • LOG_LEVEL：日志级别（默认：INFO）

示例：

PUBLIC_IP=localhost PUBLIC_PORT=3000 python3 tikz_http_server.py

脚本将执行以下操作：
*   检查Docker和Docker Compose是否已安装。
*   如果Docker Compose未安装，将尝试自动安装。
*   从`.env`文件加载环境变量（如果存在）。
*   **检查容器是否已在运行，如果存在则停止并删除。**
*   构建名为`tikz-mcp-server:latest`的Docker镜像（`docker-compose.simple.yml`已明确指定使用项目根目录下的`Dockerfile`进行构建）。镜像名称基于`SERVICE_NAME`。
*   启动名为`tikz-mcp-server-container`的Docker容器（容器名称基于`CONTAINER_NAME`），并将容器内部的`3000`端口映射到外部的`${PORT}`端口。
*   等待服务启动并进行健康检查。

服务地址

服务成功启动后，可以通过以下地址访问MCP服务器：

  • MCP服务端点：http://localhost:${PORT}/mcp/

MCP工具使用说明

服务器提供了以下三个工具：

  1. render_tikz_base64：将TikZ代码渲染成PNG并返回base64编码
  2. render_tikz_url：将TikZ代码渲染成PNG并返回可访问的URL
  3. install_tex_package：安装额外的TeX包（最小化镜像特别有用）

安装TeX包示例

在使用最小化镜像时，如果缺少特定的TeX包，可以使用install_tex_package工具：

{
  "package_name": "pgfplots"
}

支持的包名示例：

  • pgfplots - 用于绘制函数图表
  • tikz-cd - 用于交换图
  • tkz-euclide - 用于欧几里得几何
  • circuitikz - 用于电路图

MCP客户端配置

在项目的根目录下，mcp_server_configs.json文件包含了不同MCP客户端（如Claude Desktop、VSCode、Windsurf、Cline、Cursor）的服务器配置示例。您可以参考此文档并根据所使用的客户端类型进行相应配置。

例如，以下是一般的MCP客户端配置示例：

{
  "type": "http",
  "url": "http://localhost:${PORT}/mcp/",
  "transport": "streamable-http"
}

常用Docker命令

完整镜像命令

服务部署后，可以使用以下docker-compose命令来管理服务：

  • 查看日志： 
    docker-compose -f docker-compose.simple.yml logs -f
  • 重启服务： 
    docker-compose -f docker-compose.simple.yml restart
  • 终止服务： 
    docker-compose -f docker-compose.simple.yml stop
  • 删除服务容器： 
    docker-compose -f docker-compose.simple.yml down

最小化镜像命令

  • 查看日志： 
    docker-compose -f docker-compose.minimal.yml logs -f
  • 重启服务： 
    docker-compose -f docker-compose.minimal.yml restart
  • 终止服务： 
    docker-compose -f docker-compose.minimal.yml stop
  • 删除服务容器： 
    docker-compose -f docker-compose.minimal.yml down

域名配置与开发指南

域名配置

使用反向代理（如nginx）时，通过设置域名可以生成HTTPS格式的图像URL：

  1. 配置域名：在.env文件中设置域名

    DOMAIN=https://tikz.yourdomain.com

  2. 重启服务：

    docker-compose -f docker-compose.minimal.yml restart

开发热更新

为了方便开发，所有脚本文件都已通过卷映射到容器：

  • 映射：

    • tikz_http_server.py → /app/tikz_http_server.py
    • clean_images.py → /app/clean_images.py
    • run.sh → /app/run.sh

  • 热更新流程：

    1. 直接修改本地文件
    2. 运行docker-compose -f docker-compose.minimal.yml restart
    3. 不需重新构建镜像即可生效

CORS支持

增加了全面的CORS头部支持，允许所有来源访问图像资源，并解决跨域加载问题。