OpenAPI to MCP Server

A Model Context Protocol (MCP) server that converts OpenAPI specifications to MCP tools, providing access to 3DSpace Engineering Web Services APIs.

Quick Start

Prerequisites

• Python 3.8+
• Install dependencies: pip install -r requirements.txt

Start the Server

SSE Mode:

python mcp_server.py --sse

STDIO Mode:

python mcp_server.py --stdio

MCP Client Configuration

Configure your MCP client (Cursor, Claude, or custom client) with these JSON formats:

SSE Configuration

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

STDIO Configuration

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

How It Works

The MCP server reads all OpenAPI format JSON files from the swagger_files/ folder and converts them into MCP tools. Currently includes 45+ 3DSpace service specifications covering:

• Engineering Items (dseng)
• Manufacturing Items (dsmfg)
• Change Management (dslc_*)
• Project Management (dsproject)
• Document Management (dsdoc, dscdoc)
• Requirements Management (dsreq_*)
• And many more specialized services

Available Tools

The server provides these core MCP tools via list_available_tools:

🔧 Core API Tools

• api_request - Execute API operations using OpenAPI operation IDs
• generic_api_call - Make direct HTTP calls to any API endpoint
• search_operations - Find relevant API operations by search query

🔐 Authentication & Security

• set_3dspace_url - Configure the 3DSpace base URL for API calls
• get_security_context - Retrieve available security contexts (Role.Organization.CollabSpace)
• get_csrf_token - Get CSRF tokens required for state-changing operations

📋 Discovery Tools

• list_available_tools - Show all available MCP tools and their descriptions

Testing with MCP Clients

For optimal results when testing in MCP clients, use the included prompt_3dspace.md file as a system prompt. This file provides:

• Interaction Guidelines - Step-by-step workflow for API operations
• Authentication Handling - Proper credential and token management
• Parameter Precision - Exact parameter naming requirements (including $ prefixes)
• Security Best Practices - Safe handling of sensitive information
• Error Prevention - Common pitfalls and how to avoid them

The prompt ensures the AI follows proper protocols for:

• 3DSpace URL configuration
• Basic Authentication setup
• Security context selection
• CSRF token handling for state changes
• Proper JSON request body formatting

OpenAPI Path Normalization

Before using the MCP server, run the path normalization utility to ensure consistent server URLs:

python update_openapi_paths.py

What it does:

• Extracts base paths from server URLs containing {3DSpace} placeholders
• Prefixes all API paths with the extracted base path
• Updates server URLs to contain only the {3DSpace} base URL
• Ensures consistent URL structure across all OpenAPI files

Example transformation:

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

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

This ensures all API calls use the same 3DSpace base URL with properly prefixed paths.

Project Structure

├── 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

Usage Example

1. Normalize OpenAPI paths: `python u

... View full README on GitHub