What is Mcp Adapter Service

MCP Adapter Service is a lightweight, containerized FastAPI service designed to handle Model Context Protocol (MCP) requests and asynchronously route them to various backend services for tasks such as geometry optimization, structural analysis, and GFN1-xTB-based optimization.

Use cases

Use cases include submitting structured requests for geometry optimization, querying results of asynchronous tasks, and listing available analysis routes for Zeo++.

How to use

To use the MCP Adapter Service, clone the repository, configure the environment variables in a .env file, and then build and start the services using Docker Compose. Access the API documentation at http://:9000/docs.

Key features

Key features include support for standardized MCP request format, asynchronous task handling via Celery, rich structured logging with trace IDs, easy extensibility for additional backend models, full containerization for deployment, and route-based multi-function support for Zeo++.

Where to use

MCP Adapter Service is suitable for fields such as computational chemistry, materials science, and any domain requiring advanced modeling and simulation capabilities.

MCP Adapter Service

A lightweight, containerized FastAPI service that receives Model Context Protocol (MCP) requests and asynchronously dispatches them to backend services such as:

• maceopt: Geometry optimization using MACE
• zeopp: Structural analysis using Zeo++
• xtb: GFN1-xTB-based optimization

🚀 Features

• ✅ Supports standardized MCP request format
• 🧠 Asynchronous task queue via Celery
• 🧪 Rich structured logging with trace ID
• 🔌 Easily extendable to more backend models
• 🐳 Fully containerized for server deployment
• 🧵 Route-based Zeo++ multi-function support

📦 Deployment (Docker Compose)

1. Clone the repository

git clone https://github.com/your-org/mcp-adapter-service.git
cd mcp-adapter-service
```text

2. Configure environment

Create a .env file:

# Redis
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

# Backend services
MACEOPT_BASE_URL=http://192.168.100.208:4748
ZEO_BASE_URL=http://192.168.100.208:9876
XTB_BASE_URL=http://192.168.100.208:4548

3. Build and start all services

docker-compose up --build -d

Access the API via: http://<your-server-ip>:9000/docs

🧠 API Endpoints

POST /mcp

Submit a structured request to route to the appropriate backend.

Example body:

{
  "input": "<.xyz or .cssr content>",
  "context": {
    "task_id": "mcp_001",
    "model": "zeopp",
    "parameters": {
      "route": "surface_area",
      "output_filename": "output.sa"
    }
  }
}

GET /result/{task_id}

Query asynchronous task result by task ID.

GET /zeopp/list_routes

List all supported Zeo++ analysis endpoints.

📂 Project Structure

app/
├── adapters/         # Dispatcher and router
├── middleware/       # Trace logging
├── models/           # Pydantic schema
├── services/         # Celery tasks and backend clients
├── utils/            # Rich logger and trace ID
├── main.py           # FastAPI app entry
celery_worker.py      # Celery worker entry
Dockerfile
docker-compose.yml
.env.template

👤 Author

Shibo Li · 2025
MIT License