yunxiao-mcp-server AGENTS.md

Yunxiao MCP Server

Go implementation of an MCP server for the Alibaba Yunxiao (云效) DevOps platform. Defaults to read-only; write tools available with read_only=false.

Quick Start

Build:

make build

Run tests:

make test
make coverage-check   # verify 98% threshold

Run locally (HTTP mode):

YUNXIAO_MCP_ACCESS_TOKEN=<your-token> ./bin/yunxiao mcp --port 8080

Health check:

curl http://localhost:8080/healthz

Environment

Primary environment variables:

• YUNXIAO_MCP_ACCESS_TOKEN — Yunxiao personal access token
• YUNXIAO_MCP_BASE_URL — API base URL (defaults to https://openapi-rdc.aliyuncs.com)

Legacy aliases YUNXIAO_ACCESS_TOKEN and YUNXIAO_API_BASE_URL are also supported. See config.example.yaml for all options.

To test tool calls interactively, use an MCP client (e.g., mcpc) pointed at the server.

Project Structure

cmd/yunxiao/               # Entry point
internal/cmd/              # CLI commands (mcp mode, task commands, tool fallback)
pkg/server/http/           # HTTP/SSE transport
pkg/server/mcp/            # MCP server construction, stdio/HTTP/SSE
pkg/toolset/yunxiao/       # All Yunxiao tool definitions and handlers
  *_tools.go               # Tool schema definitions (mcp.NewTool)
  *_handlers.go            # Handler implementations
  *_test.go                # Handler and helper tests
  conditions.go            # Conditions JSON builders
  helpers.go               # Common handler helpers
  toolset.go               # Toolset registration and filtering
pkg/yunxiao/               # Shared Yunxiao OpenAPI SDK

Key Files

File	Purpose
pkg/toolset/yunxiao/toolset.go	Toolset registration, compactHiddenTools map (59 hidden tools across 4 categories), write-tool gating
pkg/toolset/yunxiao/*_tools.go	193 MCP tool schemas across 7 domains (170 read-only + 16 write-capable tools gated behind read_only=false)
pkg/toolset/yunxiao/projex_enhanced_*.go	8 enhanced aggregation tools
pkg/toolset/yunxiao/appstack_enhanced_*.go	5 AppStack enhanced overview tools
pkg/toolset/yunxiao/codeup_write_*.go	6 Codeup write tools
pkg/toolset/yunxiao/flow_write_*.go	2 Flow write tools
pkg/yunxiao/client.go	HTTP client with auth, pagination, and error handling
docs/ga-readiness.md	Release gate checklist and deferred endpoints
docs/quickstart.md	Common AI conversation patterns
docs/conditions-cookbook.md	Conditions JSON examples
docs/pagination-guide.md	Pagination mode reference