让 AI Agent 不只是理解科研数据，还能真正调用工具完成科研绘图。在使用 AI Agent 处理科研任务时，我们经常遇到一个问题：AI 可以解释数据，也能编写绘图代码，但当我们希望它真正完成数据读取、参数校验、图表生成以及结果保存时，往往还需要手动执行一系列操作。如果能够让 Agent 直接调用科研绘图工具，整个过程就可以更加自然。这正是 Research Draw MCP Server 想要解决的问题。
本文将基于开源项目 Research Draw v0.1.4，介绍如何通过 MCP 将科研绘图能力接入柯影智航（Koying Pilot），以及其他支持 MCP 的 Agent。教程包括两种部署方案：
本地部署： 使用 Python + uv，通过 stdio 协议接入。
Docker 部署： 使用容器运行 MCP Server，通过 Streamable HTTP 接入。
两种方案都可以提供科研绘图工具，但适用场景、工作区管理方式和部署复杂度有所不同。
一、Research Draw 是什么？
Research Draw 是一个面向科研场景的可视化工具项目。它提供从数据输入、字段映射、图表渲染到结果管理的完整工作流程。项目目前包含三种主要使用入口：
1. Python CLI
通过命令行执行绘图任务，适合脚本调用、批处理和自动化流程。
2. Web 应用
采用 FastAPI + Vue3 构建，通过可视化界面完成数据上传、参数配置、图表生成与结果管理。
3. MCP Server
将绘图能力封装为标准 MCP 工具，使 AI Agent 能够通过工具调用完成绘图任务。
本教程主要介绍第三种方式。
1.1 支持哪些科研图表？
Research Draw v0.1.4 支持 50 多种图表类型，覆盖以下场景。
| 图表类别 | 代表性图表 |
|---|---|
| 统计二维图 | 箱线图、小提琴图、散点图、火山图、森林图 |
| 生物信息学 | MA 图、富集气泡图、GSEA 图、UpSet 图 |
| 临床医学 | KM 生存曲线、ROC 曲线、校准曲线、DCA |
| 材料科学 | 应力应变曲线、XRD、拉曼光谱、相图 |
| 遥感分析 | 光谱特征、指数时间序列、混淆矩阵 |
| 金融分析 | K 线图、累计收益、滚动统计 |
| 心理学 | Likert 图、雨云图、因子载荷图 |
| 三维可视化 | 三维散点图、曲面图、等值面图 |
| 地理空间 | 世界地图、中国地图、分级设色图 |
不同图表依赖的 Python 扩展包有所区别，安装时应根据实际需求选择。
1.2 MCP Server 提供什么能力？
Research Draw MCP Server 不只是简单调用绘图函数，而是提供了一套完整的工具接口。当前主要工具包括：
| MCP 工具 | 功能 |
|---|---|
| get_version | 查询服务版本 |
| list_plot_groups | 获取图表分类 |
| list_plots | 列出支持的图表 |
| get_plot_schema | 查询图表参数规范 |
| import_data_file | 导入工作区中的数据文件 |
| upload_data_file | 通过 Base64 上传数据文件 |
| list_workspace_files | 查询工作区数据文件 |
| inspect_data_file | 检查数据字段、类型与缺失值 |
| validate_plot_config | 校验绘图参数 |
| render_plot | 执行绘图 |
| list_render_outputs | 查询绘图结果 |
这些工具可以组合形成完整的绘图工作流。例如：
用户提出绘图需求
↓
Agent 理解任务
↓
list_plots
查询可用图表
↓
get_plot_schema
获取参数规范
↓
inspect_data_file
分析数据结构
↓
validate_plot_config
校验绘图参数
↓
render_plot
执行科研绘图
↓
返回图片与保存路径二、部署前：理解两种 MCP 连接方式
Research Draw MCP Server 支持两种主要接入模式。
2.1 本地 stdio 模式
stdio 是 MCP 常见的本地通信方式。它通过标准输入和标准输出在 Agent 客户端与 MCP Server 之间传递消息。
柯影智航 / 其他 Agent
│
│ 启动本地命令
▼
uv run
│
▼
research-draw-mcp
│
│ MCP stdio
▼
Research Draw
│
▼
本地工作区这种方式不需要额外开放网络端口，也不需要配置 HTTP 服务地址。适合个人电脑、本地开发和单机科研任务。
2.2 Docker + Streamable HTTP 模式
另一种方式是将 MCP Server 部署到 Docker 容器中。服务通过 HTTP 提供 MCP 接口，Agent 使用服务地址进行连接。
柯影智航 / 其他 Agent
│
│ HTTPS
▼
反向代理
│
▼
Docker MCP Server
│
│ Streamable HTTP
▼
Research Draw
│
▼
宿主机工作区这种模式适合需要长期运行、集中部署或供多个会话接入的场景。两种模式的主要区别如下。
| 对比项 | 本地部署 | Docker 部署 |
|---|---|---|
| 通信协议 | stdio | Streamable HTTP |
| 是否需要 Docker | 否 | 是 |
| 是否需要端口 | 否 | 是 |
| 是否需要 HTTP 认证 | 通常不需要 | 需要 |
| 工作区位置 | 本机目录 | Docker 宿主机目录 |
| 配置复杂度 | 较低 | 较高 |
| Windows | 推荐 | 不推荐 |
| Linux 服务器 | 支持 | 推荐 |
| 多客户端接入 | 通常独立启动 | 可共享服务实例 |
对于第一次接触 Research Draw MCP 的用户，建议先从本地部署开始。
三、方案一：本地部署 MCP Server
本地部署适合 macOS、Windows 和 Linux 用户。本文主要以 macOS 为例介绍操作流程。Windows 用户可以参考相同的安装思路，但需要使用对应操作系统的执行文件路径。
3.1 安装基础环境
Research Draw v0.1.4 要求使用：
Python 3.13.15项目统一采用 uv 管理 Python 环境和依赖。首先检查 Git 是否可用：
git --version然后安装 uv。macOS 使用 Homebrew：
brew install uv
# 验证：
uv --versionWindows 可以按照 uv 官方安装文档，使用适合 Windows 的安装方式。安装完成后，在终端验证：
uv --version3.2 克隆项目仓库
打开终端，进入准备存放项目的目录。
git clone https://github.com/keyingshuzhi-2025/keying-research-draw.git
cd keying-research-draw建议使用独立目录管理项目，避免与其他 Python 工程混合。如果希望固定使用本文对应版本，可以检出：
git checkout v0.1.4前提是仓库已经发布对应 Git Tag。
3.3 安装 Python 环境和依赖
项目根目录已经提供：
.python-version
pyproject.toml
uv.lock可以通过 uv 安装项目要求的 Python 版本：
uv python install 3.13.15接着安装 MCP 所需依赖：
uv sync --extra mcp如果还需要使用更多专业绘图功能，可以安装完整依赖：
uv sync --extra all两者区别在于：
--extra mcp：安装基础绘图及 MCP 相关依赖。
--extra all：额外安装统计、机器学习、地图及其他扩展依赖。
对于需要使用完整科研绘图功能的用户，建议采用第二种方式。安装完成后，uv 会在项目目录中创建和管理虚拟环境。不需要手动激活虚拟环境，也可以直接使用 uv run 启动服务。
3.4 创建 MCP 工作区
Research Draw 使用工作区管理输入文件及绘图结果。
建议在项目目录之外创建独立目录，例如：
mkdir -p ~/ResearchDrawWorkspaces
# 然后创建具体的科研项目目录：
mkdir -p ~/ResearchDrawWorkspaces/project-a
# 最终目录结构可以是：
ResearchDrawWorkspaces/
└── project-a/
├── inputs/
│ └── mcp/
└── outputs/
└── mcp/文件导入后，Research Draw 会将受管理的输入副本保存到：
<workspace_path>/inputs/mcp/
# 绘图结果保存到：
<workspace_path>/outputs/mcp/
# 这里还涉及一个重要的工作区参数：
workspace_path在当前版本中，文件相关 MCP 工具以每次调用传入的绝对 workspace_path 为准。因此，Agent 在执行导入、数据检查或绘图任务时，需要正确传入当前会话的工作区路径。
3.5 配置工作区访问边界
为了限制 MCP Server 能够访问的工作区范围，可以设置：
RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT
# 例如：
export RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT="$HOME/ResearchDrawWorkspaces"
# 这个变量表示允许访问的工作区共同根目录。假设存在：
ResearchDrawWorkspaces/
├── project-a/
├── project-b/
└── project-c/
那么 Agent 可以针对不同会话传入对应的绝对工作区路径。但不应该访问这个根目录之外的其他位置。建议将共同根目录设置为实际需要使用的最小范围，而不是整个用户目录或磁盘根目录。
3.6 测试 MCP Server 启动
进入项目根目录：
cd keying-research-draw
# 执行：
RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT="$HOME/ResearchDrawWorkspaces" \
uv run research-draw-mcp如果服务正常启动，它将进入 stdio 模式，等待 MCP 客户端发送协议消息。
四、在柯影智航中配置本地 MCP
完成 Research Draw 的本地安装后，就可以将它注册到柯影智航。柯影智航（Koying Pilot）是一款面向 macOS 与 Windows 的桌面 AI 助手。通过 MCP 服务注册功能，可以将外部工具接入 Agent 的执行环境。
4.1 打开 MCP 服务注册界面
进入柯影智航的 MCP 服务管理功能，新增一个服务。按照以下内容填写。
基本信息
| 配置项 | 填写内容 |
|---|---|
| 服务标识 | research-draw |
| 显示名称 | Research Draw 科研绘图 |
| 描述 | 专业科研可视化工具，支持统计图、领域专业图、3D 图及离线地图渲染 |
| 连接方式 | 本地命令（stdio） |
启动配置
以通过 Homebrew 安装 uv 的 Apple Silicon Mac 为例。
# 启动命令：
/opt/homebrew/bin/uv
# 启动参数：
run
research-draw-mcp
# 工作目录：
/Users/yourname/development/keying-research-draw
# 这里的工作目录必须替换成实际克隆的项目根目录。可以通过：
pwd
# 查看当前项目的绝对路径。此外，使用：
which uv检查 uv 的真实路径。不同设备的 uv 安装路径可能不同，不应该直接照搬其他电脑上的配置。
环境变量
# 建议设置：
PYTHONPATH=.
MPLBACKEND=Agg
PLOT_BACKEND=Agg
HEADLESS=1
RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT=/Users/yourname/ResearchDrawWorkspaces各环境变量的含义如下。
| 变量 | 作用 |
|---|---|
| PYTHONPATH | 设置 Python 模块搜索路径 |
| MPLBACKEND | 指定 Matplotlib 后端 |
| PLOT_BACKEND | 指定项目绘图后端 |
| HEADLESS | 开启无图形界面模式 |
| RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT | 限制允许访问的工作区根目录 |
其中：
MPLBACKEND=Agg用于让 Matplotlib 在不依赖桌面图形窗口的情况下完成渲染。这对于 Agent 调用尤其重要。因为 MCP 绘图服务通常不需要弹出传统 Python 绘图窗口。
4.2 JSON 配置示例
对于支持标准 MCP JSON 配置的客户端，可以参考：
{
"mcpServers": {
"research-draw": {
"command": "/opt/homebrew/bin/uv",
"args": [
"run",
"research-draw-mcp"
],
"cwd": "/Users/yourname/development/keying-research-draw",
"env": {
"PYTHONPATH": ".",
"MPLBACKEND": "Agg",
"PLOT_BACKEND": "Agg",
"HEADLESS": "1",
"RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT": "/Users/yourname/ResearchDrawWorkspaces"
}
}
}
}例如：
{
"mcpServers": {
"research-draw": {
"command": "/opt/homebrew/bin/uv",
"args": [
"--directory",
"/Users/yourname/development/keying-research-draw",
"run",
"research-draw-mcp"
],
"env": {
"MPLBACKEND": "Agg",
"PLOT_BACKEND": "Agg",
"HEADLESS": "1",
"RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT": "/Users/yourname/ResearchDrawWorkspaces"
}
}
}
}以上两种写法应根据客户端的实际配置规范选择，不需要同时使用。对于柯影智航，推荐优先使用内置 MCP 注册表单。
4.3 验证是否接入成功
保存 MCP 配置后，重新加载服务。随后可以向 Agent 输入：
请通过 Research Draw MCP 查询当前科研绘图工具的版本，并列出支持的图表分类。
正常情况下，Agent 应能够调用：
get_version
list_plot_groups并返回服务版本和图表分类信息。接着可以进行绘图测试：
请使用 Research Draw MCP，在当前工作区生成一张演示箱线图，标题为“科研绘图 MCP 测试”，并告诉我图片保存的位置。
这里需要确保 Agent 将当前会话的绝对工作区路径作为 workspace_path 传给绘图工具。测试时可以使用：
/Users/yourname/ResearchDrawWorkspaces/project-a如果工具调用成功，应能够生成图片，并返回相应的保存路径或图像结果。至此，本地 MCP 接入完成。
五、Windows 本地部署说明
Windows 用户可以使用同样的项目代码和 MCP 服务。与 macOS 不同，Windows 需要注意命令路径和文件路径格式。推荐流程如下：
第一步： 安装 Git 和 uv。
第二步： 克隆 Research Draw 仓库。
git clone https://github.com/keyingshuzhi-2025/keying-research-draw.git
cd keying-research-draw第三步： 安装 Python 和 MCP 依赖。
uv python install 3.13.15
uv sync --extra mcp第四步： 创建工作区。
New-Item -ItemType Directory -Force "D:\ResearchDrawWorkspaces"第五步： 在柯影智航中配置 MCP 服务。
启动命令填写 uv 的实际执行文件路径。可以通过以下命令查看：
where.exe uv# 参数仍然可以使用：
run
research-draw-mcp
# 工作目录填写 Windows 项目根目录，例如：
D:\development\keying-research-draw
# 环境变量配置示例：
MPLBACKEND=Agg
PLOT_BACKEND=Agg
HEADLESS=1
RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT=D:\ResearchDrawWorkspaces
# 在 JSON 配置中，Windows 路径建议使用正斜杠：
D:/ResearchDrawWorkspaces
# 或者对反斜杠进行转义：
D:\\ResearchDrawWorkspaces这样可以避免 JSON 路径解析错误。
为什么不推荐 Windows Docker？
Research Draw 当前提供的是 Linux amd64 MCP 容器镜像。Windows Docker Desktop 运行 Linux 容器通常需要经过 WSL2 等虚拟化环境。对于 Research Draw 这种依赖宿主机工作区路径的工具，额外的文件系统转换可能带来：
Windows 与 Linux 路径格式不一致。
Docker bind mount 目录映射配置更复杂。
文件访问权限与属主映射需要额外处理。
Agent 传入的工作区路径可能无法被容器直接识别。
故障排查涉及 Windows、WSL2 和 Docker 多个层次。
因此，Windows 用户建议直接使用 uv 本地部署，不推荐采用 Docker 方案。这不是说 Windows 无法运行 Linux 容器，而是对于当前项目而言，本地部署更加直接，维护成本也更低。
六、方案二：Docker 部署 MCP Server
对于 Linux 服务器或者有长期运行需求的用户，可以考虑 Docker 部署。Research Draw v0.1.4 提供独立的 MCP 容器部署方案。镜像仅包含 MCP Server 所需内容，不包含 Web 前端。当前容器目标平台为：
linux/amd64
# 并使用：
Python 3.13.156.1 Docker 部署架构
当前项目采用以下结构：
Agent 客户端
│
│ HTTPS + Bearer Token
▼
Nginx / 其他反向代理
│
│ HTTP
▼
127.0.0.1:8000
│
▼
Research Draw MCP Container
│
├── /mcp
│
├── 图表查询
├── 数据检查
├── 绘图执行
│
▼
/host-workspaces
│
│ Bind Mount
▼
Linux 宿主机工作区# Docker 部署采用：
Streamable HTTP
# MCP 接口路径为：
/mcp与本地 stdio 方式不同，HTTP 服务需要配置认证。当前项目采用 Bearer Token 进行访问控制。
6.2 准备部署环境
首先确保 Linux 服务器已经安装 Docker Engine 和 Docker Compose 插件。检查版本：
docker --version
docker compose version
# 然后克隆项目：
git clone https://github.com/keyingshuzhi-2025/keying-research-draw.git
cd keying-research-draw
# 项目提供：
Dockerfile.mcp
compose.mcp.yaml
.env.mcp.example其中：
Dockerfile.mcp 定义 MCP 服务镜像。compose.mcp.yaml 定义容器运行方式、挂载目录、端口和 Secret。.env.mcp.example 提供环境变量示例。
6.3 创建宿主机工作区
Docker MCP 不应将科研数据持久化在容器的可写层中。当前项目采用宿主机目录映射方式保存数据。例如：
sudo mkdir -p /srv/koying/workspaces
# 然后创建一个科研会话目录：
sudo mkdir -p /srv/koying/workspaces/project-aLinux 上需要确保容器运行用户具有工作区读写权限。默认情况下，容器使用：
UID=10001
GID=10001对于由该用户管理的专用工作区，可以根据部署环境配置属主和权限。例如：
sudo chown -R 10001:10001 /srv/koying/workspaces不要直接对共享服务器上的广泛目录执行递归属主修改。工作区应当是专门为 MCP 服务创建的受控目录。
6.4 创建 MCP 认证令牌
Docker HTTP 模式使用独立令牌。为了避免将密钥直接写入镜像或 Compose 文件，项目使用 Docker Secret。在 Linux 服务器上执行：
sudo install -d -m 700 /etc/research-draw
# 创建令牌文件：
sudo install -o root -g 10001 -m 440 \
/dev/null /etc/research-draw/mcp-token
# 生成随机令牌：
openssl rand -hex 32 | \
sudo tee /etc/research-draw/mcp-token >/dev/null这里生成的是 64 个十六进制字符组成的随机令牌。当前项目要求令牌至少包含 32 个可见 ASCII 字符。令牌文件位于：
/etc/research-draw/mcp-token它不会被直接复制进 Docker 镜像。Compose 启动时会将其作为 Secret 挂载到容器内。
6.5 配置 Docker 环境变量
首先复制示例文件：
cp .env.mcp.example .env
# 编辑：
nano .env参考配置：
RESEARCH_DRAW_MCP_IMAGE=ghcr.io/keyingshuzhi-2025/keying-research-draw-mcp:0.1.4
RESEARCH_DRAW_MCP_TOKEN_FILE_HOST=/etc/research-draw/mcp-token
RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT=/srv/koying/workspaces
RESEARCH_DRAW_MCP_UID=10001
RESEARCH_DRAW_MCP_GID=10001
RESEARCH_DRAW_MCP_ALLOWED_HOSTS=mcp.example.com,mcp.example.com:*
RESEARCH_DRAW_MCP_ALLOWED_ORIGINS=https://mcp.example.com
RESEARCH_DRAW_MCP_HOST_PORT=8000
RESEARCH_DRAW_MCP_MAX_IMPORT_MB=200
RESEARCH_DRAW_MCP_MAX_UPLOAD_MB=32
RESEARCH_DRAW_MCP_MAX_REQUEST_BODY_MB=48
RESEARCH_DRAW_MCP_LOG_LEVEL=info注意将：
mcp.example.com替换为实际使用的域名。镜像地址应以 GitHub Packages 中实际发布的版本为准。当前仓库 MCP 文档列出的 GHCR 发布地址为：
ghcr.io/keyingshuzhi-2025/keying-research-draw-mcp如果部署时镜像尚未发布或无法拉取，可以使用仓库提供的 Dockerfile 构建镜像。
工作区变量说明
其中最重要的变量之一是：
RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT
# 例如：
/srv/koying/workspaces
# 它表示 Docker MCP 服务允许访问的宿主机共同工作区根目录。Compose 会将它映射为容器中的：
/host-workspaces6.6 启动 Docker MCP 服务
确保 .env 配置正确后，执行：
docker compose -f compose.mcp.yaml pull
# 然后启动：
docker compose -f compose.mcp.yaml up -d --no-build
# 查看容器：
docker compose -f compose.mcp.yaml ps
# 查看日志：
docker compose -f compose.mcp.yaml logs -f
# 如果使用本地构建镜像，可以执行：
docker compose -f compose.mcp.yaml build
# 随后：
docker compose -f compose.mcp.yaml up -d6.7 Docker 端口配置
当前 Compose 默认将容器端口映射到：
127.0.0.1:8000
# 也就是说：
宿主机 127.0.0.1:8000
↓
容器 8000这意味着 MCP 服务默认仅监听宿主机回环地址。外部设备不能直接通过服务器公网 IP 访问这个端口。对于远程接入，推荐通过 Nginx 等反向代理提供 HTTPS 服务。
Nginx 反向代理示例
下面是一个基础配置示例：
server {
listen 443 ssl;
server_name mcp.example.com;
ssl_certificate /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;
client_max_body_size 48m;
location /mcp {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Authorization $http_authorization;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_read_timeout 300s;
}
}以上是基础示例，不是完整的生产安全配置。实际生产部署还应考虑请求速率限制、访问日志、超时策略，以及反向代理与 MCP 服务的安全边界。当前配置也要求正确设置允许的 Host 和 Origin。如果客户端发送 Origin 请求头，需要确保它与服务端配置一致。同时，不建议将未经 TLS 保护的 HTTP MCP 接口直接暴露到公网。完成配置后，客户端可使用类似地址：
https://mcp.example.com/mcp访问 MCP Server。
七、在柯影智航中配置 Docker MCP
当 Docker MCP Server 正常运行，并且已经通过 HTTPS 对外提供服务后，就可以在柯影智航中注册远程 MCP 服务。
7.1 基本信息
| 配置项 | 内容 |
|---|---|
| 服务标识 | research-draw-remote |
| 显示名称 | Research Draw 远程科研绘图 |
| 连接方式 | Streamable HTTP |
| 服务地址 | https://mcp.example.com/mcp |
与本地配置不同，HTTP 模式不需要填写 uv 启动命令或项目源码目录。因为 MCP Server 已经在远程服务器上运行。
7.2 配置认证请求头
当前服务采用 Bearer Token 认证。请求头格式：
Authorization: Bearer YOUR_MCP_TOKEN例如，在支持自定义 Headers 的客户端中，可以填写：
{
"Authorization": "Bearer YOUR_MCP_TOKEN"
}其中：
YOUR_MCP_TOKEN需要替换为服务器管理员签发的真实令牌。建议将令牌保存在客户端提供的凭据管理位置，而不是提交到项目配置仓库。
远程 MCP JSON 配置示例
对于支持 HTTP MCP 的客户端，可参考：
{
"mcpServers": {
"research-draw-remote": {
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_TOKEN"
}
}
}
}部分客户端还需要指定：
type: http也有客户端使用 streamable-http 作为类型名称。应以目标客户端文档为准。
7.3 测试远程连接
完成配置后，可以先执行不涉及文件操作的工具调用。例如：
请通过远程 Research Draw MCP 查询服务版本，并列出支持的图表类型。
如果成功返回版本和图表信息，说明 MCP 服务已经建立基础连接。接下来再测试数据上传和绘图。建议按照以下顺序验证：
查询服务版本
↓
查询图表列表
↓
检查工作区
↓
导入或上传数据
↓
校验绘图参数
↓
执行绘图
↓
获取渲染结果这种测试方式更容易定位问题。
八、远程 MCP 的关键：工作区路径
这是 Docker 部署中最容易被忽略的问题。在本地模式中，柯影智航与 MCP Server 通常运行在同一台电脑上。因此，两者能够访问相同的本地文件系统。但是远程 Docker 模式不同。例如：
Mac 客户端
│
│ 访问远程 MCP
▼
阿里云 Linux 服务器
│
▼
Docker Container# 假设 Mac 上的工作区为：
/Users/yourname/research/project-a
# 而云服务器上的工作区为：
/srv/koying/workspaces/project-a这两个路径并不相同。更重要的是：远程 Docker 容器不能直接读取 Mac 本地文件。即使在 MCP 工具参数中传入 Mac 的绝对路径，远程服务器也不会自动拥有访问权限。
8.1 正确的远程工作区
Docker MCP 需要使用 Docker 宿主机上真实存在的工作区路径。例如：
/srv/koying/workspaces/project-a在调用相关工具时，应传入：
{
"workspace_path": "/srv/koying/workspaces/project-a"
}这样服务才能定位到对应工作区。
8.2 多会话工作区
当前 MCP Server 支持不同会话使用不同工作区。例如：
/srv/koying/workspaces/
├── project-a/
│ ├── inputs/mcp/
│ └── outputs/mcp/
│
├── project-b/
│ ├── inputs/mcp/
│ └── outputs/mcp/
│
└── project-c/
├── inputs/mcp/
└── outputs/mcp/当 Agent 处理 project-a 时，工具调用使用：
workspace_path=/srv/koying/workspaces/project-a
# 当切换到 project-b 时，应改为：
workspace_path=/srv/koying/workspaces/project-b不要在不同会话之间复用已经失效的工作区路径。同时需要理解：工作区路径限制主要用于约束文件访问范围，并不等同于完整的多用户身份认证与权限隔离。对于多团队或多租户生产环境，还需要在接入层设计更细粒度的身份验证和授权机制。
8.3 如何上传远程数据？
当前 MCP Server 提供：
upload_data_file用于远程数据上传。工具接收文件名、Base64 编码内容以及工作区路径。主要参数为：
filename
content_base64
workspace_path它支持的常见文件格式包括：
CSV
TSV
TXT
XLSX
XLS远程上传默认大小限制为：
32 MBHTTP 请求体默认限制为：
48 MiB九、如何在其他 AI Agent 中配置？
Research Draw MCP Server 不依赖于某一个特定 Agent。只要客户端支持对应的 MCP Transport，就可以按照其配置规范接入。一般流程可以归纳为：
确认客户端支持 MCP
↓
选择部署方式
↓
本地 stdio / 远程 HTTP
↓
填写连接配置
↓
加载 MCP 服务
↓
查询可用工具
↓
授权 Agent 调用工具
↓
执行功能测试9.1 本地 MCP 通用配置
对于支持 mcpServers 格式的客户端：
{
"mcpServers": {
"research-draw": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/keying-research-draw",
"run",
"research-draw-mcp"
],
"env": {
"MPLBACKEND": "Agg",
"PLOT_BACKEND": "Agg",
"HEADLESS": "1",
"RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT": "/absolute/path/to/workspaces"
}
}
}
}这个配置的核心是：
command + args + env客户端负责启动 MCP Server，并通过 stdio 与其通信。其中：
command 指定启动程序。
args 指定启动参数。
env 指定运行环境变量。
具体字段是否支持，需要参考客户端文档。
9.2 远程 MCP 通用配置
对于支持 Streamable HTTP 的客户端：
{
"mcpServers": {
"research-draw": {
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_TOKEN"
}
}
}
}核心是：
URL + Authorization客户端无需启动本地 Python 进程，只需要连接已经运行的 MCP Server。
9.3 不同客户端需要注意什么？
Claude Desktop、Claude Code、Cursor、VS Code 等工具均存在各自的 MCP 配置机制。但并不是所有客户端都使用完全相同的 JSON 结构。例如：
有些客户端将配置保存在全局文件中。
有些客户端支持项目级 MCP 配置。
有些客户端通过图形界面注册服务。
有些客户端需要显式指定 HTTP Transport。
有些客户端需要单独启用或批准 MCP 工具。
因此，迁移配置时不要机械复制整个 JSON 文件。应该保留必要的连接信息，再按照目标客户端的配置格式填写。
十、部署常见问题与排查
10.1 MCP 服务注册成功，但无法连接
首先检查启动命令是否存在。
macOS：
which uvWindows：
where.exe uv确认客户端填写的是实际执行路径。然后检查项目依赖：
uv sync --extra mcp
# 如果使用本地 stdio，检查启动工作目录是否正确。如果使用 Docker HTTP，检查：
docker compose -f compose.mcp.yaml ps
# 以及：
docker compose -f compose.mcp.yaml logs --tail=10010.2 Docker 提示 bind source path does not exist
可能出现：
invalid mount config for type "bind"
bind source path does not exist这通常表示 Compose 配置的宿主机目录不存在。例如：
RESEARCH_DRAW_MCP_HOST_WORKSPACES_ROOT=/srv/koying/workspaces但实际没有创建对应目录。解决办法是先检查：
ls -ld /srv/koying/workspaces
# 如果确实不存在，再创建：
sudo mkdir -p /srv/koying/workspaces还需要确认 .env 中的路径与实际目录完全一致。不要直接修改容器内部的 /host-workspaces 来解决宿主机路径不存在的问题。
10.3 Docker 提示 Secret 文件不存在
# 如果出现：
secret file does not exist
# 应检查：
RESEARCH_DRAW_MCP_TOKEN_FILE_HOST
# 是否指向真实存在的令牌文件。例如：
sudo ls -l /etc/research-draw/mcp-token如果文件不存在，应按照前面的令牌创建步骤生成。此外，需要确保容器运行身份能够读取 Secret。
10.4 HTTP 返回 401
HTTP 401 通常意味着认证失败。检查客户端是否发送：
Authorization: Bearer YOUR_MCP_TOKEN并确认令牌与服务器令牌文件中的值一致。对于当前项目，令牌在 MCP 服务进程启动时读取。轮换令牌后，需要重新创建容器：
docker compose -f compose.mcp.yaml up -d --force-recreate10.5 工具可见，但无法读取文件
重点检查：
workspace_path确认它满足：
使用绝对路径。
位于允许的共同工作区根目录内。
目录在执行服务的宿主机上真实存在。
MCP 服务进程对其具有所需权限。
当前调用使用的是正确会话的工作区。
尤其需要区分：客户端文件路径不等于远程服务器文件路径。
10.6 有些图表无法生成
Research Draw 不同图表使用的依赖不同。例如：
地理空间图可能需要 maps 或 raster 扩展。
机器学习相关图表可能需要 ml 扩展。
特定文件类型需要对应的数据处理依赖。
本地部署时，可以安装：
uv sync --extra allDocker 部署则应检查镜像是否包含目标图表所需依赖。此外，绘图前建议先使用：
get_plot_schema
validate_plot_config确认参数结构及数据列是否正确。
10.7 MCP 工具调用超时
科研绘图任务可能涉及较大的数据文件或复杂计算。可以根据客户端配置调整 MCP 工具调用超时。如果使用 Nginx，还需要检查：
proxy_read_timeout是否满足实际任务需求。同时通过服务器日志确认问题发生在：
Agent 客户端；
MCP 通信层；
数据加载阶段；
图表渲染阶段。
不要一出现超时就直接扩大所有超时参数，应先定位具体瓶颈。
十一、两种部署方式应该怎么选？
如果只是希望在自己的电脑上，通过柯影智航完成科研绘图，那么本地 stdio 已经能够满足大部分基础需求。它不需要 Docker，不需要 Nginx，也不需要配置公网域名。如果需要将 Research Draw MCP 部署到 Linux 服务器，并希望多个客户端通过统一地址访问，则可以考虑 Docker + Streamable HTTP。但远程部署必须额外解决工作区路径、数据上传、认证和网络安全问题。最终建议如下：
| 使用场景 | 推荐方案 |
|---|---|
| macOS 个人科研 | 本地 stdio |
| Windows 个人科研 | 本地 stdio |
| Linux 本地开发 | 本地 stdio |
| Linux 服务器长期运行 | Docker HTTP |
| 多客户端共享 MCP 服务 | Docker HTTP |
| 初次体验 Research Draw | 本地 stdio |
| Windows Docker Desktop | 不推荐 |
对于 Windows 用户，本项目更建议优先采用本地 Python + uv 方式。对于生产环境，推荐使用 Linux amd64 服务器承载 Docker MCP。