AI导哈

OpenAPI转MCP工具服务器

一个将OpenAPI规范转换为MCP工具的服务器，提供对3DSpace工程Web服务API的访问。

  • by pgupta1795
  • Python
  • 混合部署
  • 9 星标
  • 更新于
在 GitHub 查看 pgupta1795/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执行。

相关 MCP