CONNECT YOUR AI AGENT

Connect

连接你的 AI Agent，让井身结构图绘制融入日常工作。选择命令行工具、专业技能或 MCP 服务，即可开始。

COMMAND LINE

从终端开始绘图

wellbore-cli 是井身结构图服务的轻量客户端。通过命令行获取模板、校验井数据、提交渲染并下载结果，也方便 AI Agent 在脚本中调用。

安装与使用

需要 Python 3.11 或更新版本；无需安装绘图库、字体或服务端代码。

uv tool install --python 3.11 wellbore-cli
wellbore --help

先到 API Key 页面生成密钥，再在终端完成认证。

wellbore auth set
wellbore template straight -o well.yaml
wellbore validate well.yaml
wellbore render well.yaml -o output

编辑 well.yaml，替换为实际井数据后再校验和渲染。结果保存到 output 下，包含图片、数据表与规范化输入。

AGENT SKILL

让 Agent 理解绘图流程

drilling-agent-skills 提供随 CLI 打包的 wellbore 技能，按任务需要加载命令、领域知识与操作指南，帮助 Agent 准备井数据、校验输入并完成绘图。

查看 Skill 仓库 ↗阅读 SKILL.md ↗

安装技能

先安装 CLI，再将技能安装到本机技能目录；也可指定你的 Agent 使用的目录。

uv tool install --python 3.11 wellbore-cli
wellbore skill install
wellbore skill path

自定义技能目录：

wellbore skill install --dir /path/to/skills

重新加载技能后，在 Codex 中调用 $wellbore，并提供实际井数据。渲染前需通过 CLI 配置 API Key。

使用 $wellbore，根据我提供的井数据生成井身结构图，先校验输入，再保存绘图结果。

MODEL CONTEXT PROTOCOL

连接远程绘图工具

通过 Streamable HTTP，让 Claude Code 或 Codex 直接提交井数据、等待渲染并读取结构图。

查看 MCP 仓库 ↗生成 API Key

服务地址https://ccqwell.vip.cpolar.cn/mcp

客户端配置指南

生成 API Key

登录后前往 API Key 页面生成密钥。明文只显示一次，请立即保存。

选择认证方式

客户端必须随每个 MCP 请求发送 Bearer Token。环境变量更安全；项目配置中的固定请求头更适合无法继承终端环境的桌面客户端。

新建会话验证

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

ANTHROPIC

Claude Code

使用 CLI 添加

export WELLBORE_API_KEY='粘贴你的 API Key'
# PowerShell：$env:WELLBORE_API_KEY='粘贴你的 API Key'

claude mcp add --transport http --scope user wellbore \
  https://ccqwell.vip.cpolar.cn/mcp \
  --header 'Authorization: Bearer ${WELLBORE_API_KEY}'

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

配置文件

使用 .mcp.json

在项目根目录创建 .mcp.json。可以提交配置，但不要提交密钥；运行 Claude Code 前设置环境变量。

{
  "mcpServers": {
    "wellbore": {
      "type": "http",
      "url": "https://ccqwell.vip.cpolar.cn/mcp",
      "headers": {
        "Authorization": "Bearer ${WELLBORE_API_KEY}"
      }
    }
  }
}

作用域

选择配置范围

local: 默认值；仅当前项目，配置保存在 ~/.claude.json。
project: 仅当前项目，配置写入项目根目录的 .mcp.json，可与团队共享。
user: 本机所有项目，配置保存在 ~/.claude.json。

检查与管理

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

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

OPENAI

Codex

项目级推荐

使用 .codex/config.toml

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

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

此文件含明文密钥，必须加入 .gitignore，不要提交或分享。项目未被 Codex 信任时，项目级配置不会加载。

更安全

使用环境变量与 CLI

export WELLBORE_API_KEY='粘贴你的 API Key'
codex mcp add wellbore \
  --url https://ccqwell.vip.cpolar.cn/mcp \
  --bearer-token-env-var WELLBORE_API_KEY

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

加载规则

作用域与会话

.codex/config.toml 只影响当前受信任仓库；~/.codex/config.toml 是当前用户的全局配置。
CLI 与 IDE 使用相同的配置层，但环境变量仍以各自会话实际继承到的值为准。
保存或修改配置后新建会话；已有会话不会动态增加新工具。

检查与管理

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

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

VERIFY

做一次端到端检查

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

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

保护你的 API Key

不要把密钥放进 URL、提交到版本库或发给他人。每个客户端建议使用独立密钥；停用设备时，到 API Key 页面单独撤销即可。