• Core flow: Intent classification → Ambiguity resolution → Product mapping → Reference reading → Tool execution → Result verification
• Scope: CI/CD, code management, project collaboration, sprints/work items, artifacts, testing, application delivery

[MUST] Execution order is mandatory. Steps in this section form a sequential decision tree. You MUST execute them in the numbered order below. Do NOT check Node.js, MCP, or mcporter availability until the CLI path (Steps 1–4) has been fully attempted and failed. Do NOT run any checks in parallel across subsections 2.1 and 2.2.

Token Security Rules (applies to ALL channels):

• NEVER ask users to paste plaintext tokens in conversation or command line
• NEVER read/print token values using

  echo

  or similar commands
• ONLY verify token existence via check (see steps below for channel-specific env var names)
• If token is not configured, STOP and guide user to Yunxiao Personal Access Token. Required scopes: Organization Management (R/W), Project Collaboration (R/W), Code Management (R/W), Pipeline (R/W), Packages (R/W), Application Delivery (R/W), Test Management (R/W).

The Alibaba Cloud CLI (

aliyun devops

) is the primary invocation channel. MCP Server and mcporter are fallbacks only. Full configuration guide: references/aliyun-cli-setup.md.

aliyun devops --help >/dev/null 2>&1 && echo "cli ready" || echo "cli not available"

• Available → Go to Step 3
• Not available → Go to Step 2 (attempt installation)

[MUST] If CLI is not found in Step 1, you MUST attempt installation before considering any fallback channel. Skipping this step is prohibited. Full installation guide: references/aliyun-cli-install.md.

1. Detect OS and install:
   • macOS (Homebrew available):
     bash

     brew install aliyun-cli

   • macOS / Linux (no Homebrew):
     bash

     /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

   • Windows (PowerShell): Guide user to download and run the PowerShell install script. See references/aliyun-cli-install.md.
2. Verify installation and re-check:
   bash

   aliyun version
   aliyun devops --help >/dev/null 2>&1 && echo "cli ready" || echo "cli not available"

   • Available → Go to Step 3
   • Still not available → Go to Section 2.2 Fallback

[ -n "$ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN" ] && echo "token configured" || echo "token missing"

export ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN=<your-personal-access-token>
export ALIBABA_CLOUD_YUNXIAO_ORGANIZATION_ID=<your-organization-id>

export ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN=<your-personal-access-token>
export ALIBABA_CLOUD_YUNXIAO_API_BASE_URL=<your-region-api-base-url>

[MUST] Never ask the user for an API base URL on the central site — it defaults to

openapi-rdc.aliyuncs.com

(for both the CLI and the MCP Server). The base URL is a region-site-only setting.

~/.bashrc

~/.zshrc

[ -n "$ALIBABA_CLOUD_YUNXIAO_API_BASE_URL" ] && echo "region site" || echo "central site (default)"
[ -n "$ALIBABA_CLOUD_YUNXIAO_ORGANIZATION_ID" ] && echo "org id configured" || echo "org id missing"

• ALIBABA_CLOUD_YUNXIAO_API_BASE_URL

  set → Region site: subsequent CLI calls do NOT use

  --organization-id

  ; the API base URL is read from the environment variable automatically
• Not set → Central site (default): subsequent CLI calls use

  --organization-id

  ; if the org id is missing, guide user to set

  ALIBABA_CLOUD_YUNXIAO_ORGANIZATION_ID

  (it can be looked up via

  aliyun devops base-get-user-by-token

  )

[MUST] Remember the detected site type. All subsequent CLI calls in this session must use the corresponding parameter pattern. CLI parameters use kebab-case (e.g.,

--organization-id

), not camelCase (

--organizationId

).

devops

aliyun-cli-devops

aliyun devops <business-command>

Do you want to install it? [Y/n]:

aliyun configure set --auto-plugin-install true

Skipping this step wastes the whole timeout budget of your first business call.

CLI ready — If Steps 1–4 all pass, CLI channel is ready. Skip Section 2.2 entirely and proceed to Section 3.

[GATE] You may ONLY enter this section if both conditions are true:

1. Step 1 (CLI check) returned "cli not available"
2. Step 2 (CLI installation attempt) was executed and failed

If you have not attempted Step 2, go back and execute it now. Do NOT proceed here.

alibabacloud-devops-mcp-server@0.3.38

npx

docker

node --version   # Node.js 18+ recommended
npx --version

Recommended: Pre-install dependencies (avoid runtime downloads)

bash

npm install -g alibabacloud-devops-mcp-server@0.3.38 mcporter@0.11.1 --registry=https://registry.npmmirror.com

{
  "mcpServers": {
    "yunxiao": {
      "command": "npx",
      "args": ["-y", "alibabacloud-devops-mcp-server@0.3.38"],
      "env": {
        "YUNXIAO_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Central site needs the token only —

YUNXIAO_API_BASE_URL

defaults to

https://openapi-rdc.aliyuncs.com

. Add it to

env

only for a region site.

[MUST] When any tool call returns an authentication/authorization error:

1. Consult references/token-scopes.md for the required token scope
2. Guide user to add the scope in Yunxiao console under "Personal Access Token"
3. Pause execution, wait for user confirmation before proceeding

search_*

list_*

IMPORTANT — Before executing any tool call, all user-defined parameters (organizationId, projectId, repositoryId, pipelineId, branch names, work item subject, sprint dates, app/env names, etc.) must be confirmed with the user. Never call based on defaults or guesses.

organizationId

repositoryId

sourceBranch

targetBranch

filePath

pipelineId

branch

runId

jobId

projectId

workitemTypeId

sprintId

subject

projectId

testcaseId

testPlanId

appName

envName

changeOrderId

• "CI/CD full flow" → Build-only → Flow; app lifecycle → AppStack; both → ask
• "Repository" → Code repo → Codeup; artifact repo → Packages; unclear → ask

aliyun devops

aliyun

use_mcp_tool

• MUST prompt user to update MCP Server config (

  YUNXIAO_API_BASE_URL

  /

  YUNXIAO_ACCESS_TOKEN

  )
• MUST NOT bypass MCP Server via mcporter — mcporter is only for when MCP Server is absent
• URL with Region keywords (e.g.,

  cn-shanghai

  ) → Region edition;

  openapi-rdc.aliyuncs.com

  or unspecified → Central (default, no base URL config needed)

aliyun devops <command> --<param1> <value1> \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-devops/${SESSION_ID}"

All

aliyun devops

commands must include

--user-agent

with the session-scoped UA value (see Section 7: Observability). When using environment variables for authentication, no additional auth parameters are needed. When using command-line parameters, append

--yunxiao-access-token

and

--organization-id

(central) or

--api-base-url

(region) to each command.

scripts/discover-commands.sh

use_mcp_tool(
  server_name: "yunxiao",
  tool_name: "<tool>",
  arguments: { "<key>": "<value>" }
)

npx -y mcporter@0.11.1 call --no-coerce --stdio "npx -y alibabacloud-devops-mcp-server@0.3.38" <tool_name> [key:"value" ...]

MUST always use

--no-coerce

to prevent auto type conversion of string enums.

key:"value"

scripts/mcporter-call.sh

npx -y mcporter@0.11.1 list --stdio "npx -y alibabacloud-devops-mcp-server@0.3.38" --schema

[MUST] Tool selection must be based on dynamic discovery: Select from registered tool list, never fabricate tool names. Use

mcporter list

or references/tool-catalog.md.

[MUST] Never fabricate results: All tool calls must be actually executed with real return values.

1. Obtain

   organizationId

   via

   aliyun devops base-get-user-by-token

   (MCP:

   get_current_organization_info

   )
2. [Mandatory] Verify target resource exists via

   list_*

   /

   search_*

   /

   get_*

   — even if ID is provided
3. All required parameters confirmed with user (Section 4)
4. Delete operations require confirmation
5. [Mandatory] Dynamic schema validation before first call to any unfamiliar tool:
   • Method B: Check platform tool registry
   • Method C:

     npx -y mcporter@0.11.1 list --stdio "npx -y alibabacloud-devops-mcp-server@0.3.38" --schema 2>&1 | grep -A 30 'function <tool_name>'

   • If schema returns a different tool name, use the schema's version
   • For Testhub: call

     test-hub-get-testcase-field-config

     (MCP:

     get_testcase_field_config

     ) first — it reports which fields are required (

     assignedTo

     is) and yields the per-library option IDs that

     customFieldValues

     must carry (e.g.

     {"tc.priority": "<P1 option id>"}

     ; sending the label

     "P1"

     fails with

     400 字段【优先级】所填值无效

     ).

     testSteps

     must carry a

     content[]

     array — a payload using only

     stepContent

     /

     expectedResult

     (which is the read-back shape) fails with

     500 unknown exception

     . See references/common-scenarios.md Scenario 6.
   • For Projex: call

     projex-list-workitem-types

     (MCP:

     list_work_item_types

     ) first — never use hardcoded type IDs

[RECOMMENDED] After

create_*

/

update_*

, call the corresponding

get_*

to verify when budget permits. If API returned success with a resource ID, creation can be considered successful even without read-back.

Known API limitations: Some fields may differ between write and read-back — see references/verification-method.md.

flow-get-pipeline

get_pipeline

flow-get-latest-pipeline-run

get_latest_pipeline_run

FAIL

codeup-get-branch

get_branch

codeup-get-change-request

get_change_request

OPENED

projex-get-workitem

get_work_item

projex-get-sprint

get_sprint

[MUST] Every

aliyun devops

business command must carry the

--user-agent

flag for attribution and tracing. The UA value follows a fixed template that includes a per-session identifier.

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-devops/{session-id}

f47ac10b58cc4372a5670e02b2c3d479

{session-id}

--user-agent

python3 -c "import uuid; print(uuid.uuid4().hex)"

uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]'

aliyun devops

SESSION_ID=$(python3 -c "import uuid; print(uuid.uuid4().hex)")

aliyun devops <command> --<param1> <value1> \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-devops/${SESSION_ID}"

Important: The

--user-agent

flag is applied directly on each business command. Do NOT configure UA through any global mode-setting command — always pass it inline per invocation.

1. Read before write:

   get_*

   before

   update_*

   /

   delete_*

   to confirm current state
2. Pagination: List APIs paginate by default; pass

   page

   /

   perPage

   for large lists
3. YAML first: Pipeline creation goes through

   flow-create-pipeline --name --content

   (YAML is mandatory). Before composing the YAML, collect the three organization-specific values that are always rejected if guessed — the repository's

   httpUrlToRepo

   (never

   webUrl

   ), the Codeup service connection

   uuid

   (query with the lowercase filter

   --service-connection-type codeup

   ;

   Codeup

   reproducibly returns an empty list, which is not proof the connection is missing), and a

   runsOn.group

   harvested from an existing pipeline (no API lists build clusters, and

   public/<region>

   often does not exist). The Codeup credential is a nested

   certificate

   object, not a bare

   serviceConnection

   key, and a build-only pipeline must omit

   ArtifactUpload

   . MCP's

   create_pipeline_from_description

   builds its YAML internally and cannot be corrected — on any

   yaml校验失败

   /

   服务连接[...]不存在

   error, stop retrying it and switch to the CLI path. Verified template and preflight steps: references/common-scenarios.md Scenario 1.
4. Smart search:

   flow-list-pipelines

   with timestamp parameters —

   --execute-start-time

   /

   --execute-end-time

   /

   --create-start-time

   /

   --create-end-time

   take millisecond epoch values (13 digits, e.g.

   $(($(date +%s) * 1000))

   ). Passing seconds (10 digits) is not rejected by the API; it silently filters against 1970 and returns misleading results, so always multiply by 1000 and sanity-check the digit count. (MCP provides

   smart_list_pipelines

   supporting natural-language time ranges.)
5. Read-only first: When uncertain, use

   list_*

   /

   search_*

   /

   get_*

6. Fail fast: Two consecutive same-parameter failures → change approach. Report: methods tried, errors, root cause, next steps
7. Budget discipline: Plan critical path first; debugging ≤3 steps; near limit (≤2 remaining) → stop and report
8. Clean up: Delete experimental resources after use

• Yunxiao Documentation
• Yunxiao OpenAPI
• alibabacloud-devops-mcp-server