BRL MCP

BRL-CAD MCP试剂

一个自然语言界面 BRL-CAD 实体建模，由 模型上下文协议（MCP）, LangGraph，以及 开放人工智能该项目允许用户通过英语会话在BRL-CAD中创建和操作3D几何体，而不是记忆MGED命令语法。

______________________________________________________________________

目录

• 概述
• 建筑
• 先决条件
• 安装
• 配置
• 用法
• 可用工具
• 添加新工具
• 项目结构
• 许可证

______________________________________________________________________

概述

BRL-CAD是一个强大的开源构造性实体几何（CSG）建模系统，但其基于Tcl的MGED接口具有陡峭的学习曲线。该项目通过在BRL-CAD前面放置一个会话式AI代理来弥合这一差距。用户用简单的英语描述几何图形，GPT-4o支持的代理将这些描述转换为精确的MGED命令，对实时BRL-CAD实例执行这些命令，并报告结果。

该系统基于三层构建：

1. Tcl套接字侦听器 --在BRL-CAD的MGED中运行，并通过持久TCP套接字接受命令，返回带分隔符的响应 SUCCESS:/ERROR: 前缀。
2. MCP工具服务器 --Python FastMCP服务器，向任何兼容MCP的客户端公开类型化、验证的工具函数（球体创建、布尔运算、动态命令发现和通用命令执行）。
3. LangGraph代理客户端 --ReAct代理，对用户请求进行推理，选择适当的工具，并通过实时工具调用可见性协调多步建模操作。

______________________________________________________________________

建筑

该系统由三层组成，以链的形式进行通信：

• 客户 (client/agent.py)--一个LangGraph ReAct代理，它从用户那里获取自然语言输入，对请求进行推理，并决定调用哪个MCP工具。它保持着 持续MCP会话 服务器子流程结束 标准，因此所有工具调用共享相同的服务器进程和到MGED的TCP连接。

• 服务器 (server/app.py + server/tools/*)--一个FastMCP工具服务器，它公开了8个经过验证的类型化工具：4个专用几何工具（球体、圆柱体、长方体、布尔值）和4个用于动态命令发现和执行的元工具。当调用工具时，它会构建相应的MGED命令，并通过某种方式将其发送到BRL-CAD 持久TCP 通过传输层连接（端口5555）(transport/socket_bridge.py).所有响应都使用解析 SUCCESS:/ERROR: 来自监听器的前缀。

• 桥 (scripts/listener.tcl)--一个轻量级的Tcl脚本，来源于BRL-CAD的MGED会话。它监听TCP套接字，使用以下命令在全局MGED范围内评估传入命令 uplevel #0，将结果包装为 SUCCESS:/ERROR: 前缀，并用 > 分隔符，以便Python客户端可以可靠地读取多行输出。

请求生命周期： 用户提示→ 代理选择工具→ MCP服务器构建MGED命令→ 套接字→ Tcl监听器在MGED中进行评估→ 结果通过同一条链返回。

______________________________________________________________________

先决条件

• Python 3.10+
• BRL-CAD （使用MGED）已安装并可在您的系统上访问
• OpenAI API密钥 可以访问GPT-4o型号（或其他受支持的型号）
• Tcl公司 （与BRL-CAD的MGED捆绑在一起）

______________________________________________________________________

安装

1. 克隆存储库：

   git clone https://github.com/your-username/brlcad-mcp.git
   cd brlcad-mcp

1. 创建并激活虚拟环境：

   python -m venv .venv
   source .venv/bin/activate

1. 安装软件包（建议使用可编辑模式进行开发）：

   pip install -e ".[dev]"

这将安装中定义的所有运行时和开发依赖关系 pyproject.toml.

1. 配置环境变量：

   cp .env.example .env

编辑 .env 并设置您的OpenAI API密钥（请参阅 配置).

______________________________________________________________________

配置

所有配置均通过 .env 项目根目录中的文件。中提供了一个模板 .env.example.

重要提示： 永远不要承诺你的 .env 文件。它已经包含在 .gitignore.

______________________________________________________________________

用法

步骤1：使用Tcl侦听器启动BRL-CAD

打开MGED并创建（或打开）数据库，然后获取侦听器脚本：

mged my_model.g

MGED控制台内部：

source /path/to/brlcad-mcp/scripts/listener.tcl

您应该看到：

=================================================
 BRL-CAD AI Bridge active.
 Listening for MCP commands on localhost:5555...
=================================================

步骤2：运行代理客户端

在单独的终端中，激活虚拟环境并启动客户端：

source .venv/bin/activate
brlcad-mcp chat

或者等效地：

python -m brlcad_mcp chat

您应该看到：

Starting local MCP Client...
Successfully loaded 8 tool(s) from BRL-CAD!

=================================================
 BRL-CAD Terminal Agent Active. Type 'exit' to quit.
=================================================

第三步：用简明英语描述几何

You: Create a sphere named ball.s at the origin with radius 10

AI is calculating geometry...

AI: Created sphere ball.s at (0.0, 0.0, 0.0) with radius 10.0. The sphere is now visible in the MGED viewer.

类型 exit 或 quit 以终止会话。

______________________________________________________________________

可用工具

MCP服务器当前公开 8工具 分为两组：

专用几何工具

这些控件自动处理绘图/自动查看，并具有严格的参数验证。

create_sphere

在BRL-CAD中创建实心球体基本体。

create_cylinder

在BRL-CAD中创建右圆柱体（RCC）。

create_box

在BRL-CAD中创建轴对齐框（RPP）。

boolean_combination

执行CSG布尔运算以组合两个现有对象。

元工具（动态命令发现和执行）

这些工具允许代理发现、学习和执行 任何 MGED命令——不仅仅是具有专用工具包装器的命令。

list_commands

使用单行描述浏览所有可用的MGED命令。， creation, editing, display).

get_command_help

获取特定MGED命令的完整帮助/手册页文本，以了解其确切的参数语法。

execute_command

执行任意MGED命令字符串。支持 auto_draw 和 object_name 几何图形更改后自动刷新视图的参数。

analyze_command_error

诊断失败的MGED命令：获取帮助文本，检查对象是否存在，并执行更正的命令。最多支持5次重试尝试，以防止无限循环。

______________________________________________________________________

添加新工具

该系统的设计使代理客户端在添加新工具时永远不需要修改。工具在启动时通过MCP协议动态发现。

要添加新工具，请执行以下操作：

1. 在下面选择适当的文件 src/brlcad_mcp/server/tools/ （或为新类别创建新模块）。
2. 定义一个新功能，用 @mcp.tool().
3. 使用Pydantic Field 所有参数的注释，为LLM提供类型安全的描述。
4. 构造适当的MGED命令字符串并将其发送通过 send_command().

示例--向以下对象添加圆锥体工具 primitives.py:

from pydantic import Field

from brlcad_mcp.server.app import mcp
from brlcad_mcp.server.tools.helpers import check_mged_result, parse_response
from brlcad_mcp.transport import send_command

@mcp.tool()
def create_cone(
    name: str = Field(..., description="Name of the cone, e.g., 'cone.s'"),
    base_x: float = Field(..., description="X coordinate of the base center"),
    base_y: float = Field(..., description="Y coordinate of the base center"),
    base_z: float = Field(..., description="Z coordinate of the base center"),
    height_x: float = Field(..., description="X component of the height vector"),
    height_y: float = Field(..., description="Y component of the height vector"),
    height_z: float = Field(..., description="Z component of the height vector"),
    base_radius: float = Field(..., description="Radius at the base"),
    top_radius: float = Field(..., description="Radius at the top"),
) -> str:
    """Creates a truncated general cone (TGC) in BRL-CAD."""
    cmd = f"in {name} tgc {base_x} {base_y} {base_z} {height_x} {height_y} {height_z} {base_radius} {top_radius}"
    result = send_command(cmd)
    error = check_mged_result(result, command=cmd)
    if error:
        return error
    send_command(f"draw {name}")
    send_command("autoview")
    return f"Created cone '{name}'. Output: {parse_response(result)}"

如果你创建了一个新的工具模块（例如。， transforms.py)，将其导入 src/brlcad_mcp/server/tools/__init__.py 以确保它被注册。

______________________________________________________________________

项目结构

brlcad-mcp/
├── src/
│   └── brlcad_mcp/
│       ├── __init__.py              # Package metadata and version
│       ├── __main__.py              # python -m brlcad_mcp entry point
│       ├── cli.py                   # CLI argument parsing (serve / chat)
│       ├── config.py                # Centralised settings from env / .env
│       ├── client/
│       │   ├── __init__.py
│       │   └── agent.py             # LangGraph ReAct agent + chat loop
│       ├── server/
│       │   ├── __init__.py
│       │   ├── app.py               # FastMCP application instance
│       │   └── tools/
│       │       ├── __init__.py      # Auto-imports tool modules
│       │       ├── catalog.py       # MGED command catalog (categories + descriptions)
│       │       ├── helpers.py       # Shared error detection + response parsing
│       │       ├── primitives.py    # Sphere, cylinder, box creation tools
│       │       ├── boolean.py       # CSG boolean operations
│       │       ├── discovery.py     # list_commands + get_command_help tools
│       │       └── execution.py     # execute_command + analyze_command_error tools
│       └── transport/
│           ├── __init__.py
│           └── socket_bridge.py     # Persistent TCP connection to BRL-CAD
├── scripts/
│   └── listener.tcl                 # Tcl socket bridge for BRL-CAD MGED
├── tests/
│   ├── __init__.py
│   ├── test_config.py
│   ├── test_transport.py
│   └── test_tools.py
├── .env.example                     # Template for environment variables
├── .gitignore
├── pyproject.toml                   # PEP 621 packaging + tool config
├── LICENSE
└── README.md

______________________________________________________________________

许可证

该项目根据 MIT许可证.

BRL-CAD本身根据LGPL 2.1单独获得许可——请参阅 BRL-CAD项目 了解详情。