How the MCP Server Integrates with the 3D Relief Generation Pipeline in bigchx/mcp_3d_relief

The MCP server wraps a FastAPI application with FastMCP to expose a stdio transport, delegating all 3D relief processing to the relief.py module which handles image acquisition, depth map generation, and STL mesh creation.

The bigchx/mcp_3d_relief repository implements a complete 3D relief generation system that combines the Model Context Protocol (MCP) with computer vision pipelines. Understanding how the MCP server integrates with the 3D relief generation pipeline reveals the architecture that enables AI assistants to generate physical 3D models from 2D images through a standardized protocol interface.

MCP Server Architecture and FastAPI Integration

The integration begins with a FastAPI application that is wrapped by FastMCP to create a protocol-compatible server. This architecture allows the 3D relief generation pipeline to be invoked through MCP clients while maintaining HTTP accessibility for direct testing.

FastMCP Wrapper and stdio Transport

In server.py, the integration starts at lines 58-62 where FastMCP.from_fastapi(app, "mcp_3d_relief") creates an MCP-compatible wrapper around the FastAPI application. The server then runs with mcp.run(transport="stdio"), enabling MCP clients to invoke the 3D relief generation pipeline through standard input/output streams. This transport mechanism is critical for integration with AI assistants that communicate via the MCP protocol.

The /convert Endpoint and Pydantic Validation

The FastAPI route POST /convert defined in server.py (lines 16-34) serves as the single entry point for the 3D relief generation pipeline. It receives parameters including image_path, model_width, model_thickness, base_thickness, skip_depth, invert_depth, and detail_level. These parameters are validated using Pydantic Field definitions, ensuring type safety before delegation to the core relief() function in relief.py.

3D Relief Generation Pipeline Integration

Once the MCP server receives a request, it delegates all processing to the relief.py module. This module implements the complete 3D relief generation pipeline, orchestrating image acquisition, depth map creation, and STL mesh generation.

Image Acquisition and Preprocessing

The pipeline begins in relief.py (lines 80-95) where the input_image_path is examined. If the path starts with http:// or https://, the system performs an asynchronous download using aiohttp. For local files, the system opens the image using Pillow. This dual-path approach allows the MCP server to process both remote URLs and local file uploads, providing flexibility for different client implementations.

Depth Map Generation

The 3D relief generation pipeline offers two depth map creation strategies in relief.py (lines 166-194):

• Fast path (skip_depth=False): The original grayscale image is resized and filtered using OpenCV to produce a basic depth map suitable for rapid prototyping.
• Alternative path (skip_depth=True): The generate_depth_map() function (lines 25-48) creates a more sophisticated depth map by resizing the image, converting to luminance, applying a power-curve adjustment, optional inversion, and Gaussian blur for smoother relief surfaces.

The resulting depth map is persisted as a PNG file in the configured output_dir (lines 36-38), allowing clients to preview the height data before STL generation.

STL Mesh Generation

The final stage of the 3D relief generation pipeline occurs in generate_stl() (lines 52-146) within relief.py. This function translates the depth map into a 3D mesh by:

1. Computing per-pixel heights using depth_map / 255 * model_thickness
2. Building vertices for the relief surface
3. Generating facets including base and side walls to create a watertight manifold
4. Writing the mesh to an STL file in binary format

The function returns absolute paths to both the depth map PNG and the STL file, which are then packaged into the JSON response returned to the MCP client.

Error Handling and Response Format

The MCP server implements comprehensive error handling throughout the 3D relief generation pipeline. Any exception raised during image processing, depth map generation, or STL creation is caught in relief.py (lines 56-60), logged, and translated into a JSON error response with "status": "failed". This ensures that MCP clients receive structured feedback rather than transport-level errors, enabling graceful degradation in AI assistant workflows.

Successful responses include "status": "success" along with absolute paths to the generated depth map and STL files, allowing clients to directly access the 3D relief generation pipeline outputs.

Code Examples

Invoking the MCP Server via the MCP Client (stdio)

The following Python example demonstrates how to invoke the 3D relief generation pipeline through the MCP stdio transport:

import subprocess
import json

# Start the MCP server process

proc = subprocess.Popen(
    ["python", "server.py"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True
)

# Build an MCP request (the exact format depends on the client library;

# here we simply send a JSON payload)

request = {
    "method": "POST",
    "path": "/convert",
    "json": {
        "image_path": "https://example.com/sample.jpg",
        "model_width": 80,
        "model_thickness": 6,
        "base_thickness": 3,
        "skip_depth": False,
        "invert_depth": False,
        "detail_level": 1.2,
    },
}
proc.stdin.write(json.dumps(request) + "\n")
proc.stdin.flush()

# Read the response line (JSON)

response_line = proc.stdout.readline()
response = json.loads(response_line)
print(response)

# → {'depth_map_path': '/abs/path/output/abc123_depth_map.png',

#    'stl_path': '/abs/path/output/abc123.stl',

#    'status': 'success'}

Direct HTTP Testing

For development and testing, you can bypass the MCP transport and call the 3D relief generation pipeline directly via HTTP:

curl -X POST "http://localhost:8000/convert" \
  -H "Content-Type: application/json" \
  -d '{
        "image_path":"uploads/demo.png",
        "model_width":60,
        "model_thickness":4,
        "base_thickness":2,
        "skip_depth":false,
        "invert_depth":true,
        "detail_level":1.0
      }'

The response JSON mirrors the payload described above, containing paths to the generated depth map and STL files.

Summary

• The MCP server in bigchx/mcp_3d_relief wraps a FastAPI application using FastMCP to expose stdio transport for MCP clients.
• The POST /convert endpoint in server.py validates parameters with Pydantic and delegates to the relief() function in relief.py.
• The 3D relief generation pipeline handles both remote (via aiohttp) and local images (via Pillow), generates depth maps using OpenCV, and produces watertight STL meshes.
• The server returns structured JSON responses with absolute paths to the depth map PNG and STL file, or error statuses if the pipeline fails.

Frequently Asked Questions

How does the MCP server communicate with the 3D relief generation pipeline?

The MCP server communicates via direct Python function calls. The FastAPI endpoint POST /convert in server.py receives HTTP requests, validates them using Pydantic models, and immediately invokes the relief() function from relief.py. This synchronous delegation ensures that the heavy processing occurs within the same process, avoiding inter-process communication overhead while maintaining the MCP protocol compatibility through the stdio transport wrapper.

Can the MCP server process images from URLs or only local files?

The MCP server handles both remote URLs and local file paths seamlessly. In relief.py (lines 80-95), the pipeline inspects the input_image_path string. If it begins with http:// or https://, the system uses aiohttp to download the image asynchronously. Otherwise, it treats the path as a local file and opens it with Pillow. This dual-path approach allows MCP clients to reference web-hosted images without manual downloading.

What parameters control the 3D relief generation pipeline output?

The pipeline accepts several Pydantic-validated parameters through the POST /convert endpoint: image_path (source image), model_width (physical width in mm), model_thickness (maximum relief height), base_thickness (solid base height), skip_depth (boolean to toggle between fast OpenCV processing and advanced depth generation), invert_depth (boolean to invert height values), and detail_level (float controlling Gaussian blur and power-curve adjustments). These parameters directly influence the depth map generation in relief.py and the subsequent STL mesh creation in generate_stl().

How does error handling work in the MCP server integration?

Error handling occurs at multiple levels within the 3D relief generation pipeline. The FastAPI endpoint in server.py catches validation errors through Pydantic before reaching the core logic. Within relief.py (lines 56-60), a try-except block wraps the entire processing workflow, catching any exceptions during image download, depth map generation, or STL creation. Errors are logged and translated into a JSON response containing "status": "failed" and error details, ensuring MCP clients receive structured feedback rather than transport-level failures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}