Yunxiao MCP Server

Go implementation of an MCP server for Alibaba Yunxiao (云效). Exposes a default read-only MCP catalog via stdio, HTTP Streamable, and SSE transports, with four Projex write tools available only when read_only=false.

Quick Start

npx (Recommended)

No installation required — npx downloads the correct platform binary automatically:

npx -y @futuretea/yunxiao-mcp-server

With environment variables:

YUNXIAO_MCP_ACCESS_TOKEN=<your-token> npx -y @futuretea/yunxiao-mcp-server

Docker

Pre-built images are published to ghcr.io/futuretea/yunxiao-mcp-server:

Stdio mode:

docker run -i --rm -e YUNXIAO_MCP_ACCESS_TOKEN=<your-token> ghcr.io/futuretea/yunxiao-mcp-server:latest

HTTP mode:

docker run --rm -p 3000:3000 -e YUNXIAO_MCP_ACCESS_TOKEN=<your-token> ghcr.io/futuretea/yunxiao-mcp-server:latest --port 3000

Build from source

make build
YUNXIAO_MCP_ACCESS_TOKEN=<your-token> ./bin/yunxiao-mcp-server

See MCP Client Config for Claude, Cursor, and other IDE setup examples.

Tools Overview

The default read_only=true catalog exposes 130 read-only tools. The full catalog has 134 tools: the same read-only tools plus four Projex write-capable tools (create_workitem, update_workitem, update_workitem_status, add_workitem_comment) when read_only=false.

| Domain | Tools | Access | Description | |--------|-------|--------|-------------| | Projex | 45 | 41 read-only, 4 write-capable | Projects, iterations, work items, milestones, test cases | | Codeup | 24 | read-only | Repositories, branches, commits, merge requests, code review | | Flow | 8 | read-only | Pipelines, runs, build tasks | | Appstack | 31 | read-only | Applications, environments, releases, change orders | | Platform | 18 | read-only | Organizations, departments, members, roles | | Packages | 2 | read-only | Artifact repositories and versions | | Lingma | 4 | read-only | Knowledge bases and usage | | API | 1 | read-only | call_yunxiao_api — fallback for supported read-only OpenAPI calls | | Meta | 1 | read-only | describe_toolset — discover all available tools |

Enhanced tools aggregate multiple API calls into single user-friendly operations. For example, get_project_overview returns project info, members, iterations, milestones, and tags in one call.

Configuration

Priority: explicit values > flags > environment > config file > defaults.

Environment Variables

| Variable | Purpose | Default | |----------|---------|---------| | YUNXIAO_MCP_ACCESS_TOKEN | Yunxiao access token | — | | YUNXIAO_MCP_BASE_URL | API base URL or host | https://openapi-rdc.aliyuncs.com | | YUNXIAO_MCP_SSE_BASE_URL | Public SSE base URL (reverse proxy) | — | | YUNXIAO_MCP_INSECURE_SKIP_TLS_VERIFY | Skip Yunxiao server TLS certificate verification for private/self-signed endpoints | false |

Legacy aliases YUNXIAO_ACCESS_TOKEN and YUNXIAO_API_BASE_URL are also supported.

Use YUNXIAO_MCP_INSECURE_SKIP_TLS_VERIFY=true or --insecure-skip-tls-verify only for trusted internal endpoints where certificate validation cannot be fixed.

Tool Modes

| Option | Default | Purpose | |--------|---------|---------| | read_only / --read-only | true | Excludes write-capable tools. Set read_only=false only when Projex work item mutations are intended. | | project_focused / --project-focused | false | Registers a focused platform + Projex catalog, hiding low-value raw tools with enhanced alternatives. | | minimal / --minimal | false | Registers the smallest project-centric catalog. Write tools still require read_only=false. | | enabled_tools / --enabled-tools | [] | Explicit tool allow-list by name. | | disabled_tools / --disabled-tools | [] | Explicit tool deny-list by name. | | enabled_domains / --enable-domains | [] | Explicit domain allow-list, overriding project_focused. | | disabled_domains / --disable-domains | [] | Explicit domain deny-list. |

Per-Request Tokens (HTTP/SSE)

Clients can override the default token per request:

curl -H "x-yunxiao-token: <token>" http://localhost:3000/mcp
# or
http://localhost:3000/sse?yunxiao_access_token=<token>

Config File

./bin/yunxiao-mcp-server --config config.example.yaml

See config.example.yaml for all options.

HTTP Endpoints

| Endpoint | Purpose | |----------|---------| | /mcp | Streamable HTTP MCP | | /sse | SSE MCP | | /message | SSE message endpoint | | /healthz | Health check (returns 503 if tools not registered) |

Development

make format   # gofmt
make tidy     # go mod tidy
make lint     # golangci-lint
make test     # go test ./...
make build    # build binary to bin/
make smoke    # local smoke test (default port 39393)

Coverage threshold: 98%. Run make coverage-check to verify.

Documentation

• MCP Client Config — IDE integration examples
• Quick Start Guide — Common AI conversation patterns
• Enhanced Tools Index — Aggregated tool reference
• Conditions Cookbook — Query filter examples
• Pagination Guide — Pagination mode reference
• GA Readiness — Release checklist and deferred endpoints

License

MIT