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服务器从swagger_files/文件夹读取所有OpenAPI格式的JSON文件，并将其转换为MCP工具。目前包括45多个3DSpace服务规范，涵盖：

• 工程项目（dseng）
• 制造项目（dsmfg）
• 变更管理（dslc_*）
• 项目管理（dsproject）
• 文档管理（dsdoc, dscdoc）
• 需求管理（dsreq_*）
• 许多其他专业服务

可用工具

服务器通过list_available_tools提供这些核心MCP工具：

🔧 核心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.CollabSpace）
• 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

它做什么：

• 从包含{3DSpace}占位符的服务器URL中提取基本路径
• 将所有API路径前缀为提取的基本路径
• 更新服务器URL，使其仅包含{3DSpace}基础URL
• 确保所有OpenAPI文件中的URL结构一致

示例转换：

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

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

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

项目结构

├── mcp_server.py           # 主MCP服务器实现
├── update_openapi_paths.py # OpenAPI路径规范化实用程序
├── swagger_files/          # OpenAPI规范文件（45+服务）
├── prompt_3dspace.md       # 客户端AI交互指南
├── requirements.txt        # Python依赖项
└── README.md              # 本文件

使用示例

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操作。