yunxiao-mcp-server

README

yunxiao-mcp-server

MCP (Model Context Protocol) server and CLI for Alibaba Cloud Yunxiao DevOps platform. Lets AI coding assistants (Claude Code, Cursor, etc.) browse projects, track work items, review code, and monitor pipelines directly from your IDE.

Quick start

# One-shot via npx (no install)
npx -y @futuretea/yunxiao-mcp-server

# Or install locally
go install github.com/futuretea/yunxiao-mcp-server/cmd/yunxiao@latest

You need a Yunxiao access token. Set it via environment variable:

export YUNXIAO_MCP_ACCESS_TOKEN=<your-token>

Features

• 196 MCP tools across 9 domains (180 read-only, 16 write)
• Dual mode: MCP server for AI assistants + standalone CLI for humans (yunxiao)
• Zero-install: available via npx with automatic platform binary download
• Multi-transport: stdio, SSE, and Streamable HTTP

Tool domains

Domain	Tools	What you can do
Projex	47	Projects, work items, sprints, milestones, test cases
Codeup	37	Repositories, branches, commits, MRs, CRs, code review
Flow	21	Pipelines, pipeline runs, build jobs, step diagnostics, validation gates
Appstack	62	App stacks, environments, releases, change orders
Platform	18	Organizations, departments, members, roles
Packages	3	Artifact repositories and versions
Lingma	6	Knowledge base and AI usage statistics
API	1	Generic API fallback
Meta	1	Tool discovery

Enhanced tools

Some tools aggregate multiple API calls into a single operation to reduce AI round-trips:

• get_project_overview — project info + members + sprints + milestones + versions + labels
• get_project_workitem_detail — work item + activities + comments + attachments + relations
• get_repository_overview — repo + default branch + recent commits + recent MRs
• get_change_request_overview — CR details + patch sets + comments
• get_pipeline_overview — pipeline info + recent runs + history
• get_pipeline_run_overview — pipeline run info + categorized jobs

Insight tools

• get_project_risk_dashboard — risk dashboard with category samples and overdue items
• get_member_workload_trend — member workload trends with recent activity
• get_team_workload_breakdown — per-member workload breakdown with task details
• get_sprint_velocity — historical sprint velocity metrics
• get_blocker_analysis — dependency blocker analysis
• get_workitem_status_timeline — status change history with dwell time

MCP client configuration

Add to your MCP client config (e.g., Claude Code's mcp.json):

{
  "mcpServers": {
    "yunxiao": {
      "command": "npx",
      "args": ["-y", "@futuretea/yunxiao-mcp-server"],
      "env": {
        "YUNXIAO_MCP_ACCESS_TOKEN": "<your-token>"
      }
    }
  }
}

For HTTP mode:

{
  "mcpServers": {
    "yunxiao": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Configuration

Priority: flags > environment variables > config file > defaults.

Environment variables

Variable	Description	Default
YUNXIAO_MCP_ACCESS_TOKEN	Yunxiao access token	(required)
YUNXIAO_MCP_BASE_URL	API base URL	https://openapi-rdc.aliyuncs.com
YUNXIAO_MCP_SSE_BASE_URL	Public SSE base URL (for reverse proxies)	""
YUNXIAO_MCP_INSECURE_SKIP_TLS_VERIFY	Skip TLS verification	false

Config file

Create config.yaml:

port: 0                    # 0 = stdio mode, >0 = HTTP server
sse_base_url: ""           # public URL when behind a reverse proxy
log_level: info            # debug, info, warn, error
base_url: https://openapi-rdc.aliyuncs.com
access_token: ""           # set via env var instead
insecure_skip_tls_verify: false
read_only: true            # deny write tools when true
compact: true              # compact tool descriptions
enabled_tools: []          # whitelist specific tools
disabled_tools: []         # blacklist specific tools
enabled_domains: []        # whitelist specific domains
disabled_domains: []       # blacklist specific domains
request_timeout_seconds: 30

Per-request tokens

For multi-tenant scenarios, pass the token via HTTP header or query parameter:

# Header
curl -H "x-yunxiao-token: <token>" http://localhost:8080/mcp

# Query parameter
curl "http://localhost:8080/sse?yunxiao_access_token=<token>"

CLI usage

The yunxiao binary doubles as a standalone CLI for humans:

# List projects
yunxiao project list

# Search by name
yunxiao project list --name demo

# Output as JSON
yunxiao project list --json

# View project overview
yunxiao project view 123

# List tasks in a sprint
yunxiao task list --project-id 123 --sprint sprint-456

# View pipeline status
yunxiao pipeline view pipeline-789

# Show your own tasks
yunxiao task my 123

Global flags

--config                    path to config file
--base-url                  API base URL
--access-token              Yunxiao access token
--insecure-skip-tls-verify  skip TLS certificate verification
--read-only                 deny write operations (default true)
--output                    output format: table, json, csv
--no-color                  disable ANSI color output
--compact                   compact output
--enabled-tools             comma-separated tool whitelist
--disabled-tools            comma-separated tool blacklist
--enable-domains            comma-separated domain whitelist
--disable-domains           comma-separated domain blacklist
--request-timeout-seconds   API request timeout (default 30)

Command tree

yunxiao
├── mcp                 start MCP server
├── version             print version
├── completion          shell completions (bash, zsh, fish, powershell, install)
├── organization        list, view, info
├── member              list, search
├── group               list, view
├── department          list, view
├── pipeline            list, view, run, job, resource-member
├── project             list, view, summary, context, risk, board,
│                       labels, milestones, member, role, member-tasks,
│                       member-trend, templates
├── role                list, view
├── repo                list, view, branch, change-request, mr, commit,
│                       compare, file
├── sprint              list, view, velocity
├── task                list, view, type-list, timeline, my,
│                       type-view, type-all, relation-types
├── testcase            repo-list, search, view, field-config,
│                       directories, plan-list
├── tools               list, describe, call
└── user                whoami, list, get, orgs

Build from source

git clone https://github.com/futuretea/yunxiao-mcp-server.git
cd yunxiao-mcp-server
make build

Requires Go 1.25+.

Make targets

Target	Description
build	Build bin/yunxiao binary
test	Run all tests
lint	Run go vet + gofmt + golangci-lint + gocyclo
ci	Full CI pipeline (lint + mod verify + race tests + build)
coverage	Generate test coverage report
smoke	Start server and verify /healthz
docs	Generate tool documentation
build-all-platforms	Cross-compile for darwin/linux/windows × amd64/arm64
clean	Remove build artifacts

Docker

# Build
docker build -t yunxiao-mcp-server .

# Run in stdio mode (for MCP clients)
docker run -i --rm -e YUNXIAO_MCP_ACCESS_TOKEN=<token> yunxiao-mcp-server

# Run in HTTP mode
docker run -p 8080:8080 -e YUNXIAO_MCP_ACCESS_TOKEN=<token> \
  yunxiao-mcp-server yunxiao mcp --port 8080

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

Architecture

AI Assistant (IDE) <--MCP JSON-RPC--> yunxiao binary (stdio or HTTP)
                                           |
                                           v
                                    Yunxiao OpenAPI
                              https://openapi-rdc.aliyuncs.com

The binary has two entry points that share the same core SDK:

• MCP server (yunxiao mcp): speaks MCP JSON-RPC over stdio, SSE, or Streamable HTTP. Designed for AI assistants.
• Standalone CLI (yunxiao): human-friendly output with table/JSON/CSV formatting. Same API surface.

Security: write tools are disabled by default (read_only: true). Per-request token override supports multi-tenant deployments.

Documentation

• Quickstart guide
• MCP client configuration
• Enhanced tools index
• Conditions cookbook
• Pagination guide
• Per-domain tool references in docs/*-tools.md

License

MIT