Content
# 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.
Connection Info
You Might Also Like
everything-claude-code
Complete Claude Code configuration collection - agents, skills, hooks,...
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
servers
Model Context Protocol Servers
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.