ModelSyncBridge

Go backend middleware that unifies the world's AI 3D-generation vendor APIs behind a single standard interface — REST OpenAPI, MCP Streamable HTTP, and a first-party Go SDK.

Zero frontend · Zero CGO · Single binary · Built-in SQLite

中文版见 README.zh.md

---

Highlights

One gateway, three surfaces — the same capability exposed however your consumers prefer:

	Interface	Protocol / Port	Who consumes it
1	REST OpenAPI	HTTP/JSON · :8080	Any HTTP client, curl, your own backend
2	MCP Streamable HTTP	MCP 2025-11-25 · :8081	AI Agents — Cursor / Claude Code / Trae / Cline
3	Go SDK	Go module (sdk/)	Go developers embedding in code

Production-grade plumbing built in:

Capability	What it does
SmartScheduler	Weighted scoring (success×0.5 + speed×0.3 + priority×0.2) routes each task to the best provider · circuit breaker
KeyRotator	Multi-API-Key pool · failure-rate weighted rotation · 401→permanent ban · 429→5min cooldown · 5×5xx→1min cooldown · auto-recover
TaskService	Async task lifecycle · batch (≤100) · dedup · retry & timeout
Storage	SQLite (modernc.org/sqlite, pure Go, zero CGO) · local file cache for models / previews

Supported providers: Meshy ✅ · Tripo3D ✅ · Hyper3D ✅ · Neural4D ✅ · WorldLabs ✅ · Luma ⚠️ stub · Mock ✅ (built-in, no key needed)

---

Architecture

┌─────────────────────────────────────────────────┐
│  REST OpenAPI(:8080) │ MCP Streamable(:8081) │ Go SDK │
├─────────────────────────────────────────────────┤
│  Access Key Auth │ IP Rate Limit │ Logging        │
├─────────────────────────────────────────────────┤
│  TaskService  async lifecycle · batch · dedup    │
├─────────────────────────────────────────────────┤
│  SmartScheduler  weighted score (success×0.5     │
│                  +speed×0.3 +priority×0.2)       │
│                  · circuit breaker                │
├─────────────────────────────────────────────────┤
│  Provider Adapter  Meshy·Tripo3D·Hyper3D·Neural4D│
│                    WorldLabs·Luma(stub)·Mock     │
├─────────────────────────────────────────────────┤
│  KeyRotator  multi-API-Key pool · failure-rate   │
│              weighted rotation                    │
│              401→permanent ban · 429→5min cooldown│
│              · 5×5xx→1min cooldown · lazy-recover │
├─────────────────────────────────────────────────┤
│  SQLite (modernc.org/sqlite, pure Go, zero CGO) │
│  Local file cache (models / previews)            │
└─────────────────────────────────────────────────┘

---

Quick Start

Option A — Docker (no local build)

docker run -d --name modelsyncbridge \
  -p 8080:8080 -p 8081:8081 \
  -e MSB_AUTH_ENABLE_API_KEY=true \
  -e MSB_AUTH_API_KEYS=sk-your-access-key \
  -e MSB_SERVER_PUBLIC_URL=http://localhost:8080 \
  ghcr.io/halor-qu/modelsyncbridge:latest

Or with docker compose: export MSB_AUTH_API_KEYS=... && docker compose up -d

Option B — Build from source

git clone https://github.com/HaloR-Qu/ModelSyncBridge.git
cd ModelSyncBridge
go build -o modelsyncbridge.exe ./cmd/server/
./modelsyncbridge.exe

Default endpoints

Service	URL
REST	http://localhost:8080
MCP	http://localhost:8081/mcp (Streamable HTTP) · http://localhost:8081/sse (legacy SSE)

Smoke test

curl http://localhost:8080/api/v1/health

curl -X POST http://localhost:8080/api/v1/task/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a cute cat in a spacesuit"}'

Enable a real provider (Mock is built-in, no key needed):

MSB_PROVIDER_MESHY_ENABLED=true \
MSB_PROVIDER_MESHY_API_KEYS="sk-primary,sk-backup" \
./modelsyncbridge.exe

---

Remote Deployment: let others' Agents call it directly (no clone needed)

ModelSyncBridge speaks MCP Streamable HTTP — a remote protocol. Once deployed to a public HTTPS endpoint, any MCP client (Cursor / Claude Code / Trae / Cline, etc.) just configures a URL. They never need to download or build this project.

// On the other side — Cursor / Trae / Claude config only needs:
{
  "mcpServers": {
    "modelsyncbridge": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer sk-your-access-key" }
    }
  }
}

• CI auto-builds multi-arch images (linux/amd64 + arm64) and pushes them to GHCR
• docker pull ghcr.io/halor-qu/modelsyncbridge:latest gets you the image
• Caddy / Nginx reverse proxy adds HTTPS automatically; or deploy to Railway / Fly.io / Render
• Full deployment guide (HTTPS, security checklist, PaaS, verification) in docs/deployment.md

---

Documentation

Doc	Description
docs/deployment.md	Deployment guide: Docker/compose/GHCR, HTTPS proxy, PaaS, remote MCP setup, security checklist
docs/config.md	Full config reference: ENV variable table, YAML fields, KeyRotator multi-key rotation strategy
docs/sdk.md	Go SDK guide: init, all methods, retry/timeout, error handling, full example
docs/mcp-clients.md	MCP setup for Cursor / Claude Code / Trae / VS Code / Cline and other Agents

Chinese versions: docs/deployment.zh.md · docs/config.zh.md · docs/sdk.zh.md · docs/mcp-clients.zh.md

---

REST API Cheat Sheet

Uniform envelope {"code":"OK","message":"success","data":{...}}. Error codes: INVALID_PARAM · PROVIDER_NOT_FOUND · NO_AVAILABLE_PROVIDER · TASK_NOT_FOUND · PROVIDER_ERROR · TASK_TIMEOUT · RATE_LIMITED · AUTH_FAILED.

Method	Endpoint	Description
GET	/api/v1/health	Liveness probe (no auth required)
POST	/api/v1/task/generate	Submit text/image→3D
POST	/api/v1/task/batch-generate	Batch, up to 100
GET	/api/v1/task/query?task_id=...	Query status / progress / result URLs
POST	/api/v1/task/cancel	Cancel task
GET	/api/v1/provider/list	Provider list + capabilities
GET	/api/v1/model/download/{id}?type=model|preview	Local file download
GET	/api/v1/stats/summary · /stats/providers · /stats/provider-scores	Stats · scores · KeyRotator state

---

Project Layout

ModelSyncBridge/
├── cmd/server/main.go          # dual-port entry
├── config/config.yaml          # runtime config (ENV can override)
├── sdk/                        # first-party Go SDK
├── internal/
│   ├── config/                 # YAML loader + ENV overrides
│   ├── model/                  # core data types
│   ├── store/sqlite.go         # SQLite persistence
│   ├── vendor/
│   │   ├── adapter.go          # Adapter interface
│   │   ├── manager.go          # Provider manager
│   │   ├── httpclient.go       # HTTP client + KeyRotator auto rotation
│   │   ├── keyrotator.go       # multi-key pool · weighted rotation · state tracking
│   │   └── meshy.go / tripo3d.go / hyper3d.go / neural4d.go / worldlabs.go / luma.go / mock.go
│   ├── service/                # TaskService · Scheduler · RateLimiter
│   ├── rest/                   # REST API (:8080)
│   └── mcp/                    # MCP Streamable HTTP (:8081)
└── go.mod                      # Go 1.22, zero CGO, zero heavy deps

---

License

GNU Affero General Public License v3.0 (AGPL-3.0)

Any derivative work or modification distributed or offered as a network service must be released under the AGPL-3.0 as well.