Civil 3D MCP Server — 动态 Roslyn 分支

一个 MCP 服务器，使 AI 助手能够直接在 Autodesk Civil 3D 内部编写和执行 C# 代码。与大量固定工具不同，AI 生成特定于任务的代码，并通过 Civil 3D API 访问运行。

项目范围与传承

此分支保留了动态 Roslyn/C# 执行模型，并刻意保持三个 MCP 工具的较小公共表面。其当前兼容性基线为 Autodesk Civil 3D 2025，本地工作侧重于可靠性、安全性、可衡量的效率以及可复用的 Civil 3D 技能。其他 Civil 3D 版本可通过单独验证的兼容性工作稍后添加。

本项目源自 barbosaihan/civil3d-mcp。SantosSjba/mcp-to-c3d 被评估用于选定的、有测试支持的想法，而 Sacred-G/Civil3D-mcp 仅用作架构参考。有关详细的归属和许可边界，请参阅 PROVENANCE.md。

此独立项目与 Autodesk 无关联，也未获得 Autodesk 认可。不包含 Autodesk 程序集和其他专有的 Civil 3D 文件。

架构

┌─────────────────┐     stdio      ┌──────────────────┐     TCP/JSON-RPC    ┌──────────────────┐
│   AI Assistant   │ ◄────────────► │  MCP Server (TS) │ ◄──────────────────► │  Civil 3D Plugin │
│ (Claude, Cline)  │               │   3 meta-tools    │     port 8080       │  Roslyn Engine   │
└─────────────────┘               └──────────────────┘                      └──────────────────┘
                                         │                                         │
                                    Skills Library                           C# Code Execution
                                   (.skill.md files)                      (full Civil 3D API)

3 个元工具

工作原理

1. AI 读取技能 → 获取带文档的 C# 代码模板

2. AI 调整代码 → 填充参数、组合模式

3. AI 发送代码 → 通过 civil3d_execute 或 civil3d_query

4. Roslyn 编译并运行 → 在 Civil 3D 内部，具有完整的 API 访问权限

5. 结果以 JSON 返回 → 返回给 AI

交互示例

User: "What surfaces are in my drawing?"

AI: Uses civil3d_query with:
  var surfaces = new List<object>();
  foreach (ObjectId id in CivilDoc.GetSurfaceIds()) {
    var s = Transaction.GetObject(id, OpenMode.ForRead) as TinSurface;
    surfaces.Add(new { s.Name, s.Layer });
  }
  return surfaces;

Result: [{ "Name": "EG", "Layer": "C-TOPO-EG" }, ...]

技能库

civil3d_skills 还支持 action: "api_lookup"，用于对已加载的列入白名单的 Civil 3D 宿主程序集中的公共类型和成员名称/签名进行有界的只读搜索。它不会加载程序集、运行 C# 代码或访问活动图形。提供查询，并可选择提供程序集、命名空间前缀和结果限制。

技能是 skills/ 中带文档的 C# 代码模板：

skills/
├── surfaces/           # Surface operations
├── alignments/         # Alignment + station/offset
├── points/             # COGO points
├── geometry/           # Lines, polylines, text
├── drawing/            # Drawing info
└── workflows/          # Complex multi-object operations

脚本全局变量

通过 civil3d_execute 或 civil3d_query 执行的代码可以访问：

所有 Civil 3D 命名空间都会自动导入。

设置

1. 构建 MCP 服务器

npm install && npm run build

2. 构建插件

# Copy DLLs from Civil 3D to C_References/ (see C_References/README.md)
cd plugin/Civil3dMcpPlugin
dotnet build

3. 在 Civil 3D 中加载

NETLOAD → select Civil3dMcpPlugin.dll
C3DMCPSTATUS → verify running

4. 配置 AI

{
  "mcpServers": {
    "civil3d": {
      "command": "node",
      "args": ["/path/to/civil3d-mcp/build/index.js"]
    }
  }
}

环境变量

基准测试

阶段 2A 的与主机无关的记录器、阶段 2A.1 的可选内部实时跟踪契约以及阶段 2A.2 的只读实时运行器记录在 benchmark/README.md 中。它们都不会添加 MCP 工具、队列或重试；2A.2 运行器仅在显式启动时可以调用其固定的只读查询。

结构化错误（阶段 2B.1）

civil3d_query 和 civil3d_execute 保留其现有的文本错误内容和 isError: true，同时返回带有模式 civil3d-mcp-error/v1 的 structuredContent。稳定的错误字段为 code、category、message、source、outcome 和 retryable。命令超时或发送后连接丢失具有 outcome: "unknown" 和 retryable: false；服务器永远不会自动重试。成功的响应和三个工具的公共表面保持不变。

私有 TCP 帧格式（阶段 2C.1）

每个 localhost TCP 连接承载一个 UTF-8 JSON-RPC 请求和一个响应。每个 JSON 主体后跟 LF，并限制为 8 MiB，以不含 LF 的 UTF-8 字节数衡量。当完整的 JSON 主体后跟有序的连接关闭时，Node 客户端仍接受先前插件的无帧响应。过大的请求在写入之前被拒绝；过大或格式错误的响应以及中断的连接会产生不可重试的结构化传输错误。如果执行已完成但插件无法返回过大的结果，则报告的结果为 unknown。

操作审计日志和写入幂等性（阶段 2I.1 / 2I.2）

在默认的 info 日志级别下，每个被接受的 civil3d_query 和 civil3d_execute 操作都会发出一个有界的 stderr 审计事件。它包含一个新的不透明操作 ID、工具名称、C# 源代码的 SHA-256 和 UTF-8 字节长度、成功/错误状态以及经过的毫秒数；错误仅添加稳定的 code/category/source/outcome 字段。审计事件从不包含调用方代码、描述、图形标识、结果或错误消息。

civil3d_execute 还接受一个可选的不透明 idempotencyKey（1–128 个 ASCII 字母、数字、.、_、:、-）。在一个插件会话中，它将键绑定到 UTF-8 C# SHA-256 和规范化的 expectedDrawing 标识。重复项会被拒绝为进行中、冲突或已提交；已提交的条目不保留结果，调用方必须通过只读查询进行核对。会话最多保留 256 个已完成的键，并确定性地逐出最旧的键。这既不增加持久性，也不增加自动重试或恰好一次语义。

安全性

Roslyn 沙箱阻止：

• 进程执行（Process.Start）

• 文件删除（File.Delete）

• 网络请求（HttpClient、Sockets）

• 注册表访问

• 动态程序集加载

所有 Civil 3D API 操作都允许。

此正则表达式沙箱是纵深防御，而非信任边界。两个代码工具都会接收可变的 Civil 3D 和 AutoCAD API 对象；civil3d_query 跳过主机的提交事务，但无法保证任意动态 C# 代码无副作用。仅运行受信任的、经审批门控的代码。回环 TCP 可防止远程网络访问，但不会对其他本地进程进行身份验证。

许可证

MIT