Awesome Well Structure MCP 服务

基于 MCP (Model Context Protocol) 协议 的井身结构图生成服务：提交井数据，等待渲染，读取生成的井身结构图。

服务以 Streamable HTTP 方式托管，客户端直接连接公网地址即可，无需在本地安装任何程序。由西南石油大学钻井所，何世明——汤明实验室团体提供技术支持。

This service, powered by the Model Context Protocol (MCP), automatically generates borehole structure diagrams from well data. It is technically supported by the He Shiming and Tang Ming research group at the Drilling Research Institute of Southwest Petroleum University.

问题反馈：1873475824@qq.com（陈春钱）

示例图片

井身结构示意图绘制：

Related MCP server: Plotting MCP Server

服务地址

配置说明的在线版本见 https://wellbore.ichunqian.top/mcp-setup。

服务地址是这台实例的运行期配置：不确定当前实例自己认为的公网地址时，读公开只读的 https://wellbore.ichunqian.top/api/config（返回 {"publicBaseUrl": "..."}）核对。换域名时运维只改服务端一行配置，客户端把上面的地址替换成新地址即可。

快速开始

第一步：生成 API Key

登录后前往 https://wellbore.ichunqian.top/keys 生成密钥。

明文只显示一次，请立即保存。

第二步：选择认证方式

客户端必须随每个 MCP 请求发送 Bearer Token。两种做法：

• 环境变量（更安全，推荐）—— 密钥不落盘到仓库，也不会被 git commit 带走。

• 项目配置中的固定请求头 —— 适合无法继承终端环境的桌面客户端。

第三步：新建会话验证

保存配置后新建客户端会话。已有会话不会重新加载 MCP 工具；仅看到配置显示为 enabled 也不代表连接成功。

Claude Code 配置

推荐（macOS / Linux）：密钥存成独立文件，由 shell 读取

不要把明文 Key 直接写进 ~/.zshrc，也不要在命令行里 export——前者会被 dotfile 同步带走，后者会留在 shell 历史里。推荐把密钥单独存成一个只有当前用户可读的文件：

mkdir -p ~/.config/wellbore
chmod 700 ~/.config/wellbore
printf '%s' '粘贴你的 API Key' > ~/.config/wellbore/api-key
chmod 600 ~/.config/wellbore/api-key

然后在 shell 启动文件末尾追加一行（macOS 默认 zsh 用 ~/.zshrc，bash 用 ~/.bashrc）：

[ -r "$HOME/.config/wellbore/api-key" ] && export WELLBORE_API_KEY="$(<"$HOME/.config/wellbore/api-key")"

开一个新终端验证变量已就位。只回显长度，不要把密钥本身打印到屏幕或日志里：

printf 'len=%s\n' "${#WELLBORE_API_KEY}"

正常应输出一个非零长度（与 ~/.config/wellbore/api-key 的字符数一致）。len=0 说明启动文件那行没生效。

这样做的理由：

• 密钥只存在于一个 600 权限的文件里，不进 dotfile、不进 shell 历史。

• dotfile 常被多机同步或误提交；密钥与 ~/.zshrc 分离后，同步 dotfile 不会带走它。

• 轮换密钥只需覆写这一个文件，无需改动客户端配置。

从 Dock / Spotlight 启动的桌面应用不会执行 ~/.zshrc，拿不到这个变量。终端里启动的 claude / codex CLI 不受影响；桌面客户端请改用固定请求头（见下文「配置文件」一节）。

使用 CLI 添加

密钥按上一节的做法放进环境变量后（Windows 可先执行 $env:WELLBORE_API_KEY='粘贴你的 API Key' 临时设置），添加服务器：

claude mcp add --transport http --scope user wellbore \
  https://wellbore.ichunqian.top/mcp \
  --header 'Authorization: Bearer ${WELLBORE_API_KEY}'

user 作用域会在本机所有项目中启用。只想给当前项目使用时改成 local；团队共享配置时使用 project。

配置文件：使用 .mcp.json

在项目根目录创建 .mcp.json。仓库内提供了 .mcp.json.example 可直接复制：

{
  "mcpServers": {
    "wellbore": {
      "type": "http",
      "url": "https://wellbore.ichunqian.top/mcp",
      "headers": {
        "Authorization": "Bearer ${WELLBORE_API_KEY}"
      }
    }
  }
}

配置可以提交，但不要提交密钥；运行 Claude Code 前设置好环境变量。

作用域

检查与管理

claude mcp list
claude mcp get wellbore
# 进入 Claude Code 后也可运行 /mcp
claude mcp remove wellbore --scope user

若使用了其他作用域，移除时把 user 换成对应的 local 或 project。

Codex 配置

项目级：使用 .codex/config.toml

在受信任仓库的根目录创建 .codex/config.toml。固定请求头不依赖桌面应用是否继承终端环境。

[mcp_servers.wellbore]
url = "https://wellbore.ichunqian.top/mcp"
http_headers = { Authorization = "Bearer 粘贴你的 API Key" }
tool_timeout_sec = 180

此文件含明文密钥，必须加入 .gitignore，不要提交或分享。 本仓库的 .gitignore 已默认忽略该路径。

项目未被 Codex 信任时，项目级配置不会加载。

更安全：使用环境变量与 CLI

macOS / Linux 上密钥的存放方式与上文「推荐（macOS / Linux）：密钥存成独立文件，由 shell 读取」一致，不要把明文写进 ~/.zshrc。变量就位后：

codex mcp add wellbore \
  --url https://wellbore.ichunqian.top/mcp \
  --bearer-token-env-var WELLBORE_API_KEY

Windows 临时设置：$env:WELLBORE_API_KEY='粘贴你的 API Key'。

CLI 将服务器写入用户级 ~/.codex/config.toml，适用于所有项目。密钥必须存在于启动该 Codex 会话的环境中；macOS 终端里的 export 不会自动传给从 Dock 启动的桌面应用。

加载规则

1. .codex/config.toml 只影响当前受信任仓库；~/.codex/config.toml 是当前用户的全局配置。

2. CLI 与 IDE 使用相同的配置层，但环境变量仍以各自会话实际继承到的值为准。

3. 保存或修改配置后新建会话；已有会话不会动态增加新工具。

检查与管理

codex mcp list
codex mcp get wellbore --json
# 进入 Codex TUI 后也可运行 /mcp
codex mcp remove wellbore

list 与 get 用于核对配置；最终仍需在新会话中成功发现并调用工具，才能确认连接可用。

工具与资源

工具

典型链路：submit_job → wait_for_job → get_structure_diagram。

完整工具清单以新会话中客户端实际发现的结果为准（也可读取 wellbore://meta）。

Resources

输入契约：只写 YAML

submit_job 只接收 YAML，不要提交 JSON。字段规范以服务端提供的 wellbore://yaml/guide 为准——该文档随服务版本更新（当前 YAML_SCHEMA_VERSION = 2026-09-28），本仓库不再复制一份，以避免二次过期。

核心原则：只写这张图真正需要的块。YAML 顶层没有写出的块会被编译成"不在场"，因此不要为了"完整"补无关块——块一旦在场，就会启用它自己的必填字段与跨块校验。

六个绘图块：

最小示例（只画地层）：

stratigraphy:
  遂宁组: 150
  沙溪庙组: 1112

提交时同步校验，错误直接返回带 path/line 的 422；合法输入才进入渲染队列。建议提供 idempotency_key 并在超时重试时复用：同账户同键同输入返回原 job，换 YAML 或格式返回 409。

端到端检查

新开一个客户端会话，然后发送下面这句话。服务应完成"读取指南 → 提交 → 等待 → 返回结构图"的完整链路：

请读取 wellbore://yaml/guide，然后用模板生成一张 PNG 井身结构图。

故障排查

保护你的 API Key

• 不要把密钥放进 URL、提交到版本库或发给他人。

• 密钥存放文件权限设为 600（chmod 600 ~/.config/wellbore/api-key），目录 700；不要用 echo 追加到会被同步的 dotfile 里。

• 每个客户端建议使用独立密钥；停用设备时，到 https://wellbore.ichunqian.top/keys 单独撤销即可。

• 本仓库的 .gitignore 已默认忽略 .mcp.json 与 .codex/config.toml，避免误提交。

获取内测资格或提交反馈

联系：1873475824@qq.com —— 陈春钱 · 博士

License

非商业许可（Non-Commercial） —— 详见 LICENSE。

• ✅ 允许：个人学习、研究、实验；高校与科研机构的非营利教学与学术研究。可复制、修改、再分发，需保留版权声明。

• ❌ 禁止：任何商业用途，包括集成进营利性产品/服务、商业项目交付、企业内部生产经营使用、收费分发等。

本许可同样约束托管服务及其生成的成果：通过本服务生成的井身结构图等，仅限非商业用途。

商业授权请联系：1873475824@qq.com