Pcli2 MCP

pcli2-mcp

奥兰达文件：https://jchultarsky101.github.io/pcli2-mcp/

一个基于HTTP的轻量级模型上下文协议（MCP）服务器，封装了PCLI2 CLI。 它将PCLI2功能作为MCP工具公开，以便LLM客户端可以列出资产/文件夹 并通过单个JSON-RPC端点运行几何匹配查询。

项目链接：

• pcli2-mcp: https://github.com/jchultarsky101/pcli2-mcp
• pcli2: https://github.com/jchultarsky101/pcli2

状态： 早期发育（v0.1.15）。

主要概念

PCLI2（Physna命令行界面v2）是Physna公共API的官方CLI，专注于3D几何搜索和资产/文件夹操作。这个项目是一个围绕PCLI2的MCP包装器：它在MCP JSON-RPC接口后面运行PCLI2命令，这样像Claude或Qwen这样的客户端就可以通过编程调用相同的功能。有关PCLI2文档和使用方法，请参阅PCLI2文档网站：https://jchultarsky101.github.io/pcli2/以及存储库：https://github.com/jchultarsky101/pcli2.

简而言之，流程如下：

1. LLM客户端（Claude、Qwen或其他支持MCP的应用程序）发送工具请求。
2. pcli2-mcp 将该请求转换为PCLI2 CLI调用。
3. PCLI2与Physna API对话并返回结果。
4. pcli2-mcp 将结构化响应返回给LLM客户端。

这使LLM集成保持稳定（MCP over HTTP），而底层CLI（PCLI2）仍然是Physna API行为的唯一真相来源。

flowchart LR
  LLM["LLM Client (Claude, Qwen, etc.)"]
  MCP[pcli2-mcp MCP Server]
  CLI[PCLI2 CLI]
  API[Physna Public API]

  LLM -- MCP tools/list, tools/call --> MCP
  MCP -- spawn CLI commands --> CLI
  CLI -- HTTPS requests --> API
  API -- responses --> CLI
  CLI -- stdout/stderr --> MCP
  MCP -- JSON-RPC response --> LLM

快速开始

1. 安装PCLI2并进行身份验证。

遵循PCLI2文档并确保 pcli2 在你的 PATH: https://jchultarsky101.github.io/pcli2/

1. 安装 pcli2-mcp （见下面的安装）。

1. 运行服务器：

   pcli2-mcp serve --host localhost --port 8080 --log-level info

1. 验证服务器是否正常：

   curl -s http://localhost:8080/health

1. 验证MCP是否响应（列出工具）：

   curl -s http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/list",
       "params": {}
     }'

1. 生成客户端配置代码段：

   pcli2-mcp config --client claude --host localhost --port 8080

1. 将代码片段粘贴到您的客户端（请参阅以下部分）。

安装

推荐（预构建二进制文件）：

1. 从以下网址下载适用于您平台的最新版本：

https://github.com/jchultarsky101/pcli2-mcp/releases

1. 放 pcli2-mcp 二进制文件在你的某处 PATH.

从源代码构建：

1. 安装Rust工具链（2024版）。

1. 构建：

   cargo build --release

二进制文件将位于 target/release/pcli2-mcp.

文件网站（Oranda）

此存储库使用Oranda来呈现更好的README托管版本。

本地构建：

oranda build

本地预览（更改后自动重建）：

oranda dev

GitHub Pages工作流程(.github/workflows/docs.yml)从发布网站 public/.

特性

• 基于HTTP的MCP(/mcp)使用JSON-RPC 2.0
• 30多种MCP工具，涵盖租户、环境、用户、文件夹、资产、元数据和匹配操作
• 缩略图缓存：缩略图缓存在磁盘上，并通过HTTP URL提供，避免了MCP响应中的大型base64有效载荷
• 缩略图清理工具：删除过期的缩略图以释放磁盘空间
• 简单的单二进制Rust服务器
• 综合测试套件（51个单元测试，10个集成测试）
• 模块化代码架构（cli、error、mcp、pcli2、服务器）

客户端设置（使用 config)

这 config 命令打印一个带有MCP服务器定义的可粘贴JSON代码段：

pcli2-mcp config --client claude --host localhost --port 8080

使用以下部分中的输出。

命令行界面

运行服务器：

pcli2-mcp serve --host localhost --port 8080 --log-level info

使用 --host 0.0.0.0 在所有界面上监听。

打印客户端配置（漂亮的JSON）：

pcli2-mcp config --client claude --host localhost --port 8080

命令特定帮助：

pcli2-mcp help serve

克劳德桌面版

1. 打开Claude Desktop，进入“设置”>“开发人员”>“编辑配置”（或直接打开配置文件）。
2. 将JSON输出粘贴到 mcpServers.
3. 重新启动克劳德桌面。

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

通义代码

Qwen代码从以下位置读取MCP服务器 mcpServers 在 settings.json。您可以通过以下方式进行配置：

1. 编辑 .qwen/settings.json 在您的项目中，或 ~/.qwen/settings.json 对于用户范围。
2. 将JSON输出粘贴到 mcpServers.
3. 重新启动Qwen Code以加载设置。

或者，您可以使用CLI添加服务器：

qwen mcp add --transport http pcli2 http://localhost:8080/mcp

Qwen代理（Python）

传递MCP配置字典（包括 mcpServers)创建代理时：

from qwen_agent.agents import Assistant

mcp_config = {
    "mcpServers": {
        "pcli2": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "http://localhost:8080/mcp"]
        }
    }
}

agent = Assistant(
    llm=llm_cfg,
    function_list=[mcp_config],
)

MCPHost（当地Ollama）

MCPHost可以使用本地Ollama模型，并通过HTTP连接到此MCP服务器。

1. 安装Ollama，拉取一个模型，并确保守护进程正在运行：

   ollama pull mistral
   ollama serve

1. 安装MCPHost：

   go install github.com/mark3labs/mcphost@latest

1. 创建配置文件（首选位置包括 ~/.mcphost.yml 或 ~/.mcphost.json)并将其指向您的本地MCP服务器：

   # ~/.mcphost.yml
   mcpServers:
     pcli2:
       type: "remote"
       url: "http://localhost:8080/mcp"

   # Use a local model with function-calling support
   model: "ollama:mistral"

1. 运行MCPHost：

   mcphost -m ollama:qwen3 --config ./mcphost.yml

其他MCP客户端

大多数MCP兼容客户端都接受相同的 mcpServers JSON块。使用以下输出 pcli2-mcp config 按照服务器定义，并遵循客户的MCP文档。

MCP API

服务器通过JSON-RPC 2.0接口在HTTP上实现MCP。

• POST /mcp
• 方法： initialize, tools/list, tools/call

示例 tools/list:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

示例 tools/call （在下面列出资产 /Julian CSV格式）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "pcli2",
    "arguments": {
      "resource": "asset",
      "folder_path": "/Julian",
      "format": "csv",
      "headers": true
    }
  }
}

工具

笔记：

• 大多数资产工具需要 uuid 或 path.
• 大多数文件夹工具都需要 folder_uuid 或 folder_path （或列表 folder_path).

例子：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "pcli2_geometric_match",
    "arguments": {
      "path": "/Root/Folder/Part.stl",
      "threshold": 85,
      "format": "csv",
      "headers": true
    }
  }
}

缩略图缓存

这 pcli2_asset_thumbnail 该工具使用基于磁盘的缓存来高效地提供缩略图。它通过以下方式支持两种响应模式 response_mode 参数。

⚠️ 推荐：使用 response_mode="url" （默认） 对于LLM工作流， 总是喜欢 url 模式它返回一个简短的HTTP URL（约200个令牌），客户端会自动获取该URL。这 data_url 模式返回约50K个base64数据令牌，LLM经常对其进行错误的篡改、截断或重新编码。

响应模式

使用示例

高效模式（默认，推荐）：

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "pcli2_asset_thumbnail",
    "arguments": {
      "path": "/Root/Folder/Part.stl"
    }
  }
}

自包含模式（不建议用于LLM）：

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "pcli2_asset_thumbnail",
    "arguments": {
      "path": "/Root/Folder/Part.stl",
      "response_mode": "data_url"
    }
  }
}

运作原理

当你打电话的时候 pcli2_asset_thumbnail:

1. 服务器使用PCLI2生成缩略图
2. 将其与元数据一起保存到缓存目录
3. 返回一个HTML代码段，其中包含 `` 标签指向：

- 缓存的HTTP URL(response_mode="url") - 推荐 - 嵌入式base64数据URI(response_mode="data_url") - 不建议用于LLM

缓存详细信息

• 缓存位置: ~/.pcli2-mcp/thumbnails/
• 默认TTL：24小时
• HTTP端点: http://localhost:PORT/thumbnail/:cache_key

清理过期的缩略图

使用 pcli2_thumbnail_cache_cleanup 删除过期缩略图并释放磁盘空间的工具：

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "pcli2_thumbnail_cache_cleanup",
    "arguments": {}
  }
}

配置

• --port：侦听端口（默认值： 8080)
• --log-level：服务器的日志记录级别（默认值： info)
• RUST_LOG：日志级别（例如。 info, debug)

故障排除

• 确保 pcli2 已安装，可通过以下方式访问 PATH.
• 如果服务器返回非零错误，请检查嵌入式 pcli2 响应中的stdout/stderr。
• 为了在故障排除过程中进行详细的日志记录，请设置 RUST_LOG=debug.

贡献

欢迎问题和拉取请求。如果您计划进行重大更改，请先打开一个问题 因此，我们可以讨论范围和方法。

获取帮助

用清晰的报告、预期行为和日志（设置 RUST_LOG=debug 如果需要）。

维护者

维护人员列在存储库的贡献者/维护人员名册中。

更新日志

看 CHANGELOG.md.

许可证

Apache许可证2.0。看 LICENSE 和 NOTICE.