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:** ```bash python mcp_server.py --sse ``` **STDIO Mode:** ```bash python mcp_server.py --stdio ``` ## MCP Client Configuration Configure your MCP client (Cursor, Claude, or custom client) with these JSON formats: ### SSE Configuration ```json { "mcpServers": { "3dspace-mcp-server": { "url": "http://localhost:8000/sse" } } } ``` ### STDIO Configuration ```json { "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: ```bash 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:** ```json // 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.