Generate well structure diagrams and related reports from well data via an MCP tool.
Accepts well data including well name, total depth, well type (straight/deviated/horizontal), deviation data, stratigraphy, drilling fluid/pressure, and wellbore structure.
Validates the data and calls an external generator to produce a well structure schematic (PNG), an info diagram (PNG), and a detailed Markdown report.
Archives generated files in a timestamped folder and returns success/error status, report content, image paths, archive folder, and well info.
Supports optional legend and style configuration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Awesome Well Structure MCP Generate well structure for vertical well depth 2500m"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
基于 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
项 | 值 |
MCP 端点 |
|
传输方式 | Streamable HTTP |
认证 | Bearer Token（每个请求都必须携带） |
输入契约 | YAML（不接受 JSON） |
输出格式 | PNG / SVG |
配置说明的在线版本见 https://ccqwell.vip.cpolar.cn/mcp-setup。
登录后前往 https://ccqwell.vip.cpolar.cn/keys 生成密钥。
明文只显示一次，请立即保存。
客户端必须随每个 MCP 请求发送 Bearer Token。两种做法：
环境变量（更安全，推荐）—— 密钥不落盘到仓库，也不会被 git commit 带走。
项目配置中的固定请求头 —— 适合无法继承终端环境的桌面客户端。
保存配置后新建客户端会话。已有会话不会重新加载 MCP 工具；仅看到配置显示为 enabled 也不代表连接成功。
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。仓库内提供了 .mcp.json.example 可直接复制：
{
"mcpServers": {
"wellbore": {
"type": "http",
"url": "https://ccqwell.vip.cpolar.cn/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/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，不要提交或分享。 本仓库的.gitignore已默认忽略该路径。
项目未被 Codex 信任时，项目级配置不会加载。
export WELLBORE_API_KEY='粘贴你的 API Key'
codex mcp add wellbore \
--url https://ccqwell.vip.cpolar.cn/mcp \
--bearer-token-env-var WELLBORE_API_KEYCLI 将服务器写入用户级 ~/.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 wellborelist 与 get 用于核对配置；最终仍需在新会话中成功发现并调用工具，才能确认连接可用。
工具 | 用途 |
| 提交井身结构图 YAML，同步校验后进入渲染队列 |
| 等待 job 发生一次状态变化或到达终态 |
| 读取主图（PNG 返回图片内容，SVG 返回原图字节） |
| 查询 job 当前状态，成功时返回规范 JSON 与主图 Resource URI |
| 列出当前账户最近提交的 job |
| 取消自己的 queued job |
| 查询主图 sha256、ETag、字节数、PNG 宽高与生成时间（不返回图片字节） |
| 列出已落盘的规范 JSON 与主图资源 |
| 断连续传：按字节偏移分块读取主图 |
| 读取 YAML 指南／示例／模板（供不支持 Resources 的客户端） |
| 读取成功 job 的规范 JSON（供不支持 Resources 的客户端） |
典型链路：submit_job → wait_for_job → get_structure_diagram。
完整工具清单以新会话中客户端实际发现的结果为准（也可读取
wellbore://meta）。
URI | 内容 |
| YAML 输入指南（权威契约说明） |
| 按目标画面组织的最小输入示例 |
| 可直接修改的完整 YAML 模板 |
| 服务元信息 |
| 该 job 的规范 JSON |
| 该 job 的主图（PNG） |
| 该 job 的主图（SVG） |
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 井身结构图。
现象 | 原因与处理 |
401 | API Key 缺失、错误或已撤销 |
403 / 421 | 服务端 Host 或 Origin 白名单未包含当前公网域名 |
连接正常但等待超时 | Codex 保留 |
配置后看不到工具 | 确认项目已受信任并新建会话；使用环境变量认证时，还要确认该会话确实继承了密钥 |
显示 |
|
提交返回 422 | YAML 校验未通过，按返回的 |
不要把密钥放进 URL、提交到版本库或发给他人。
每个客户端建议使用独立密钥；停用设备时，到 https://ccqwell.vip.cpolar.cn/keys 单独撤销即可。
本仓库的 .gitignore 已默认忽略 .mcp.json 与 .codex/config.toml，避免误提交。
联系：1873475824@qq.com —— 陈春钱 · 博士
非商业许可（Non-Commercial） —— 详见 LICENSE。
✅ 允许：个人学习、研究、实验；高校与科研机构的非营利教学与学术研究。可复制、修改、再分发，需保留版权声明。
❌ 禁止：任何商业用途，包括集成进营利性产品/服务、商业项目交付、企业内部生产经营使用、收费分发等。
本许可同样约束托管服务及其生成的成果：通过本服务生成的井身结构图等，仅限非商业用途。
商业授权请联系：1873475824@qq.com
生成井身结构示意图及相关报告。
基于提供的井数据（JSON格式），调用井身结构生成器生成井身结构示意图（PNG）、 井身结构信息图（PNG）和详细的Markdown格式报告。支持直井、定向井、水平井等 多种井型，可配置地层、钻井液压力、井身结构等详细参数。
功能描述: 1. 接收并验证井数据的完整性和合法性 2. 调用外部生成器程序生成井身结构可视化图表 3. 创建带时间戳的归档文件夹保存所有生成文件 4. 返回图片路径和详细报告内容
Args: well_data (Dict[str, Any]): 井数据字典，必需。包含以下字段：
必填字段：
wellName (str): 井名
totalDepth_m (float): 井深，单位：米，必须大于0。若用户未明确指出，则采用最大钻头深度(wellboreStructure下的 bottomDepth_m)减去1米。
wellType (str): 井型，可选值：
- "straight well": 直井
- "deviated well": 定向井
- "horizontal well": 水平井
deviationData (Dict): 井眼轨迹参数（直井时，至少包含 "kickoffPoint_m"，或deviationAngle_deg 字段）
- kickoffPoint_m (float): 绘图造斜点，单位：米 （默认null）
- REAL_kickoffPoint_m (float): 显示造斜点，单位：米 （默认null）
- targetPointA_m (float): A靶点井深，单位：米 （默认null）
- targetPointA_verticalDepth_m (float): A靶点垂深，单位：米 （默认null）
- targetPointB_m (float): B靶点井深，单位：米 （默认null）
- deviationAngle_deg (float): 井斜角，单位：度，（默认为null，直井为0）
- DistanceAB_m (float): A、B靶点距离，单位：米 （默认null）
stratigraphy (List[Dict]): 地层分层信息数组
- name (str): 地层名称
- topDepth_m (float): 顶深，单位：米
- bottomDepth_m (float): 底深，单位：米
注意：相邻地层的bottomDepth_m必须等于下一地层的topDepth_m
drillingFluidAndPressure (List[Dict]): 钻井液密度和压力剖面数组
- topDepth_m (float): 区间顶深，单位：米
- bottomDepth_m (float): 区间底深，单位：米
- porePressure_gcm3 (float): 孔隙压力当量密度，单位：g/cm³
- pressureWindow_gcm3 (Dict): 安全密度窗口
- min (float): 最小安全密度，单位：g/cm³
- max (float): 最大安全密度，单位：g/cm³
wellboreStructure (Dict): 井身物理结构
- holeSections (List[Dict]): 裸眼井段数组
- topDepth_m (float): 井段顶深，单位：米
- bottomDepth_m (float): 井段底深，单位：米
- diameter_mm (float): 钻头直径，单位：毫米
- note_in (str, 可选): 备注说明
- casingSections (List[Dict]): 套管程序数组
- topDepth_m (float): 套管悬挂点深度，单位：米
- bottomDepth_m (float): 套管鞋深度，单位：米
- od_mm (float): 套管外径，单位：毫米
- note_in (str, 可选): 备注说明
可选字段：
legendConfig (Dict): 图例和样式配置
- casingLegend (bool): 是否显示套管图例
- holeLegend (bool): 是否显示井筒图例
- kickoffLegend (bool): 是否显示造斜点图例
- targetPointsLegend (bool): 是否显示靶点图例
- fill (bool): 是否填充套管-井筒环空
- simpleinfo (bool): 是否使用简化信息图
pilotHoleGuideLine (Dict): 导眼井辅助线配置，放置在wellboreStructure内。
- display (bool): 是否显示辅助线
- highlight (bool): 是否高亮显示
- side_tracking (bool): 是否标记为侧钻点Returns: Dict[str, Any]: 生成结果字典，包含以下字段：
成功时 (success=True)：
success (bool): True，表示生成成功
report_content (str): Markdown格式的详细报告内容
response (str): 包含图片路径的格式化响应文本
notice (str): 使用提示信息
well_info (Dict): 井基本信息
- well_name (str): 井名
- well_type (str): 井型
- total_depth (float): 井深
archive_folder (str): 归档文件夹相对路径
structure_image_path (str): 井身结构图绝对路径
info_image_path (str): 井身信息图绝对路径
失败时 (success=False)：
success (bool): False，表示生成失败
error (str): 错误描述信息
error_code (str): 错误代码，可能的值：
- "VALIDATION_ERROR": 数据验证失败
- "FILE_UPDATE_ERROR": 文件更新失败
- "GENERATOR_ERROR": 生成器启动或运行失败
- "FOLDER_CREATION_ERROR": 文件夹创建失败
- "FILE_ARCHIVE_ERROR": 文件归档失败
- "FOLDER_PATH_ERROR": 路径获取失败
- "UNKNOWN_ERROR": 未知错误
details (str): 详细错误信息Raises: 本函数不会主动抛出异常，所有错误均通过返回字典中的success字段和error信息表示。
Notes: - 服务端具有较强容错性，部分数据缺失时会自动生成默认值 - 所有生成的文件会自动归档到以时间戳命名的文件夹中 - 不要向用户复述或展示原始JSON数据，直接使用工具生成结果 - 进行任何数据修改操作前必须提醒用户
Examples: >>> well_data = { ... "wellName": "Well_Z101", ... "totalDepth_m": 6900, ... "wellType": "deviated well", ... "deviationData": { ... "kickoffPoint_m": 3060, ... "deviationAngle_deg": 30, ... "targetPointA_m": 5090, ... "targetPointA_verticalDepth_m": 4825, ... "targetPointB_m": 6890, ... "DistanceAB_m": 1800, ... "REAL_kickoffPoint_m": 3060 ... }, ... "stratigraphy": [ ... {"name": "遂宁组", "topDepth_m": 0, "bottomDepth_m": 150}, ... {"name": "沙溪庙组", "topDepth_m": 150, "bottomDepth_m": 1112}, ... ...... ... ], ... "drillingFluidAndPressure": [ ... {"topDepth_m": 0, "bottomDepth_m": 150, ... "porePressure_gcm3": 1.085, ... "pressureWindow_gcm3": {"min": 1.05, "max": 1.10}}, ... ...... ... ], ... "wellboreStructure": { ... "holeSections": [ ... {"topDepth_m": 0, "bottomDepth_m": 152, ... "diameter_mm": 660.4, "note_in": "26""}, ... ...... ... ], ... "casingSections": [ ... {"topDepth_m": 0, "bottomDepth_m": 150.62, ... "od_mm": 508, "note_in": "20"导管"}, ... ...... ... ], ... "pilotHoleGuideLine": { ... "topDepth_m": 3060, ... "bottomDepth_m": 6900, ... "diameter_mm": 215.9, ... "display": true, ... "highlight": true, ... "side_tracking": true ... } ... }, ... "legendConfig": { ... "casingLegend": false, ... "holeLegend": false, ... "kickoffLegend": true, ... "targetPointsLegend": true, ... "fill": false, ... "simpleinfo": true ... } ... } >>> result = generate_well_structure(well_data) >>> if result["success"]: ... print(f"生成成功！图片路径：{result['structure_image_path']}") ... else: ... print(f"生成失败：{result['error']}")
| Name | Required | Description | Default |
|---|---|---|---|
| well_data | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description fully discloses behavior: no exceptions thrown, errors returned via dict, server fault tolerance, timestamped folder creation, and external generator invocation. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with headings (功能描述, Args, Returns, Raises, Notes, Examples). It is front-loaded with a summary. Some redundancy exists, but complexity justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (nested objects, many fields), the description is complete: covers all parameters, return values (success and failure), error codes, notes, and provides a full example. Output schema is detailed in the Returns section.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage with a generic object. The description compensates by providing a full breakdown of required and optional fields, types, units, defaults, and nested structures, adding immense value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb '生成' (generate) and the resource '井身结构示意图及相关报告' (well structure diagram and related reports). It is specific and distinguishes the tool from any potential siblings, though none are listed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes functional steps, notes on usage (e.g., not to show raw JSON, to remind users before modification), and a detailed example. However, it does not explicitly state when to use this tool over alternatives, but that is mitigated by the lack of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v3.0.0generate_well_structureScored across 1 tool
With only one tool, there is no possibility of confusion or overlap. The tool's purpose is clearly defined.
Single tool named 'generate_well_structure' follows a clear verb_noun pattern, consistent with its function.
A single tool for generating well structure diagrams is borderline. It fits a very narrow scope, but most servers offer a broader range of operations.
The tool only handles generation; there are no companion tools for listing, updating, or managing well data, leaving obvious gaps.
Generate, edit, and export data-architecture diagrams from your AI. Column lineage, PNG in chat.
AI agent draws editable hand-drawn diagrams (flowchart, ER, architecture) via MCP, not static images
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
Visual AI for strategic thinking — SWOT, flowcharts, mindmaps, Gantt diagrams as polished SVG.
