🛰 Hybrid SOAP→REST Gateway (Async + Cache + MCP + FastAPI)

A production‑grade gateway that:

• Converts SOAP WSDL services into a REST‑style interface.

• Runs FastAPI HTTP API and MCP server as separate processes in the different containers.

• Supports WS‑Security UsernameToken authentication from .env.

• Caches raw WSDL XML and fully processed WSDL (Zeep client, docs, examples).

• Allows manual cache clear and manual processed WSDL refresh via HTTP or MCP.

• Uses .env for environment‑specific configuration.

📂 Project Structure

.
├── soap_gateway.py      # Shared SOAP→REST logic
├── fastapi_app.py       # FastAPI HTTP API
├── mcp_server.py        # MCP server
├── requirements.txt     # Python dependencies
├── Dockerfile           # Container build instructions
├── docker-compose.yml   # docker compose file
├── .env                 # Environment variables
└── README.md            # This file

Related MCP server: mcp2ws

🚀 Features

• Dual‑process: FastAPI and MCP run independently — no blocking.

• Async‑ready: Core functions can be adapted for async.

• Caching:

  • Raw WSDL XML

  • Fully processed WSDL (Zeep client, operation docs, element docs)

• Clear cache: /clear_cache endpoint or MCP clear() tool.

• Refresh processed WSDL: /refresh_wsdl endpoint or MCP refresh_wsdl() tool.

• Dockerized: Minimal image with supervisord managing both processes.

• Configurable health check: WSDL URL set via HEALTHCHECK_WSDL_URL env var.

⚙️ Environment Variables

📄 Example .env

HEALTHCHECK_WSDL_URL=https://dev.example.com/service?wsdl
SOAP_USERNAME=myuser
SOAP_PASSWORD=supersecret
DEBUG=true
PORT=9000

🐳 Docker Deployment

docker compose up -d

🛠 Usage

1. HTTP API (FastAPI)

• http://localhost:9000/docs - FastAPI documentation

• POST /describe — List operations and input schema.

• POST /invoke — Call a SOAP operation.

• POST /clear_cache — Flush all caches.

• POST /refresh_wsdl — Force rebuild of processed WSDL cache.

2. MCP Server

Tools:

• describe(wsdl_url=None, operation=None, username=None, password=None)

• invoke(wsdl_url=None, endpoint_url, operation, params, username=None, password=None)

• clear()

• refresh_wsdl(wsdl_url=None, username=None, password=None, version="v1")

HTTP MCP transport (mounted at /mcp)

The MCP wrapper in mcp_server.py mounts an HTTP transport at /mcp by default. When calling the HTTP MCP endpoint, send a JSON POST where tool is the tool name and args is an object containing the tool arguments. Example payload:

{
  "tool": "describe",
  "args": {
    "wsdl_url": "https://example.com/service?wsdl",
    "operation": null,
    "username": null,
    "password": null
  }
}

The endpoint will return a JSON response containing the tool result (same shape as the internal function return values). This is useful for MCP agents that communicate over HTTP instead of stdio.

🤝 MCP Agent Configuration

Local spawn (stdio)

{
  "mcpServers": {
    "soap-gateway": {
      "type": "stdio",
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "HEALTHCHECK_WSDL_URL": "https://dev.example.com/service?wsdl",
        "SOAP_USERNAME": "myuser",
        "SOAP_PASSWORD": "supersecret"
      }
    }
  }
}

Remote/HTTP

{
  "mcpServers": {
    "soap-gateway": {
      "type": "http",
      "url": "http://your-server-host:9010/mcp",
      "env": {
        "HEALTHCHECK_WSDL_URL": "https://prod.example.com/service?wsdl",
        "SOAP_USERNAME": "myuser",
        "SOAP_PASSWORD": "supersecret"
      }
    }
  }
}

🐳 MCP Configuration for Docker Deployment

When running inside Docker, connect over HTTP:

{
  "mcpServers": {
    "soap-gateway": {
      "type": "http",
      "url": "http://localhost:9010/mcp",
      "env": {
        "HEALTHCHECK_WSDL_URL": "https://dev.example.com/service?wsdl",
        "SOAP_USERNAME": "myuser",
        "SOAP_PASSWORD": "supersecret"
      }
    }
  }
}

❤️ Health Check

ENV HEALTHCHECK_WSDL_URL="http://example.com?wsdl"
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -sf http://localhost:9000/describe \
       -H "Content-Type: application/json" \
       -d "{\"wsdl_url\":\"${HEALTHCHECK_WSDL_URL}\"}" || exit 1

🧹 Cache Management

• Automatic: Processed WSDL cache is built on first use and reused until cleared or refreshed.

• Manual clear:

  • HTTP: POST /clear_cache

  • MCP: clear() tool

• Manual refresh:

  • HTTP: POST /refresh_wsdl

  • MCP: refresh_wsdl() tool