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

> Learn how the MCP server integrates with the 3D relief generation pipeline in bigchx/mcp_3d_relief. Discover its role in image acquisition, depth map generation, and STL mesh creation.

- Repository: [bigchx/mcp_3d_relief](https://github.com/bigchx/mcp_3d_relief)
- Tags: architecture
- Published: 2026-02-26

---

**The MCP server wraps a FastAPI application with FastMCP to expose a stdio transport, delegating all 3D relief processing to the [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/relief.py).

## 3D Relief Generation Pipeline Integration

Once the MCP server receives a request, it delegates all processing to the [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/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:

```python
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:

```bash
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`](https://github.com/bigchx/mcp_3d_relief/blob/main/server.py) validates parameters with **Pydantic** and delegates to the `relief()` function in [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/server.py) receives HTTP requests, validates them using Pydantic models, and immediately invokes the `relief()` function from [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/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`](https://github.com/bigchx/mcp_3d_relief/blob/main/server.py) catches validation errors through Pydantic before reaching the core logic. Within [`relief.py`](https://github.com/bigchx/mcp_3d_relief/blob/main/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.