pgupta1795/3dspace-mcp-server

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 update_openapi_paths.py
2. Start the server: python mcp_server.py --sse
3. Configure your MCP client with the JSON configuration above
4. Load prompt_3dspace.md as system prompt in your client
5. Begin interacting with 3DSpace APIs through natural language

The AI will guide you through authentication, parameter collection, and API execution following the established workflow patterns.