3dspace MCP Server

OpenAPI到MCP服务器

一个模型上下文协议（MCP）服务器，将OpenAPI规范转换为MCP工具，提供对3DSpace工程Web服务API的访问。

快速开始

先决条件

• Python 3.8+
• 安装依赖项： pip install -r requirements.txt

启动服务器

SSE模式：

python mcp_server.py --sse

STDIO模式：

python mcp_server.py --stdio

MCP客户端配置

使用以下JSON格式配置您的MCP客户端（Cursor、Claude或自定义客户端）：

SSE配置

{
  "mcpServers": {
    "3dspace-mcp-server": {
      "url": "http://localhost:8000/sse"
    }
  }
}

STDIO配置

{
  "mcpServers": {
    "3dspace-mcp-server": {
      "command": "python",
      "args": ["mcp_server.py", "--stdio"],
      "env": {}
    }
  }
}

运作原理

MCP服务器从以下位置读取所有OpenAPI格式的JSON文件 swagger_files/ 文件夹并将其转换为MCP工具。目前包括45+3DSpace服务规范，涵盖：

• 工程项目（dseng）
• 制造项目（dsmfg）
• 变更管理（dslc\_\*）
• 项目管理（dsproject）
• 文档管理（dsdoc、dscdoc）
• 需求管理（dsreq\_\*）
• 以及更多的专业服务

可用工具

服务器通过以下方式提供这些核心MCP工具 list_available_tools:

🔧 核心API工具

• api_request -使用OpenAPI操作ID执行API操作
• generic_api_call -对任何API端点进行直接HTTP调用
• search_operations -通过搜索查询查找相关的API操作

🔐 身份验证和安全

• set_3dspace_url -为API调用配置3DSpace基本URL
• get_security_context -检索可用的安全上下文（Role.Organization.ColabSpace）
• get_csrf_token -获取状态更改操作所需的CSRF令牌

📋 发现工具

• list_available_tools -显示所有可用的MCP工具及其说明

使用MCP客户端进行测试

为了在MCP客户端中测试时获得最佳结果，请使用附带的 prompt_3dspace.md 文件作为系统提示。此文件提供：

• 互动指南 -API操作的分步工作流程
• 身份验证处理 -正确的凭证和令牌管理
• 参数精度 -精确的参数命名要求（包括 $ 前缀）
• 安全最佳实践 -敏感信息的安全处理
• 错误预防 -常见的陷阱以及如何避免它们

该提示确保AI遵循正确的协议：

• 3DSpace URL配置
• 基本身份验证设置
• 安全上下文选择
• 状态更改的CSRF令牌处理
• 正确的JSON请求体格式

OpenAPI路径规范化

在使用MCP服务器之前，请运行路径规范化实用程序以确保服务器URL的一致性：

python update_openapi_paths.py

它的作用：

• 从包含以下内容的服务器URL中提取基本路径 {3DSpace} 占位符
• 使用提取的基本路径为所有API路径加前缀
• 更新服务器URL以仅包含 {3DSpace} 基地址
• 确保所有OpenAPI文件的URL结构一致

转换示例：

// Before:
"servers": [{"url": "{3DSpace}/resources/v1/dsmfg"}],
"paths": {"/dsmfg:MfgItem": {...}}

// After:
"servers": [{"url": "{3DSpace}"}],
"paths": {"/resources/v1/dsmfg/dsmfg:MfgItem": {...}}

这确保了所有API调用都使用相同的3DSpace基URL和正确前缀的路径。

项目结构

├── mcp_server.py           # Main MCP server implementation
├── update_openapi_paths.py # OpenAPI path normalization utility
├── swagger_files/          # OpenAPI specification files (45+ services)
├── prompt_3dspace.md       # AI interaction guidelines for clients
├── requirements.txt        # Python dependencies
└── README.md              # This file

用法示例

1. 规范OpenAPI路径: python update_openapi_paths.py
2. 启动服务器: python mcp_server.py --sse
3. 配置您的MCP客户端 使用上面的JSON配置
4. 负载 prompt_3dspace.md 根据客户端的系统提示
5. 开始互动 通过自然语言使用3DSpace API

AI将指导您按照既定的工作流程模式完成身份验证、参数收集和API执行。