# 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.