Yandex 360 (ycli)

io.github.bim-bav0.36.0更新于 Oct 2, 2026

Yandex 360 Tracker, Wiki and Forms: read and write tools with honest read-only annotations.

已验证STDIO仅桌面Developer ToolsProductivity & WorkflowKnowledge & Memory

概览

AI 生成的概览

让助手通过 322 个 MCP 工具读写 Yandex 360 的 Tracker 问题、Wiki 页面和 Forms 表单。

功能
为 Yandex 360 的 Tracker、Wiki 和 Forms 提供读写工具，每个工具对应一个已封装的 API 操作，另有一个跨领域的 status 工具。读取操作标注为只读，写入操作会声明是否具有破坏性或幂等性。可按服务、精选核心配置或单个工具名缩小工具集，只读模式则不提供任何写入工具。
适用场景
当助手需要处理 Yandex 360 内容时使用：查询或更新 Tracker 问题、评论、状态流转和工作日志，读取或编辑 Wiki 页面，或查看 Forms 表单及其回复。谨慎部署时可选择只读启动。
运行要求
通过 stdio 在本地运行，通常用 uvx 从带 mcp 附加组件的 yandex-cli 包启动。需要 Yandex OAuth 令牌（YANDEX_ID_OAUTH_TOKEN）和组织 id（YANDEX_ID_ORGANIZATION_ID），后者以 X-Org-Id 请求头发送。令牌须由已注册的 Yandex OAuth 应用签发，并具备 Tracker、Wiki 和 Forms 权限。
安装前请注意
YANDEX_ID_OAUTH_TOKEN 中的令牌可访问 Tracker、Wiki 和 Forms，写入工具能够创建、修改、移动和删除问题、页面、评论、附件及表单数据。破坏性命令会在交互时请求确认，在脚本中需显式传入确认标志。试运行选项可预览写入而不实际发送。完整工具集很大，有工具数量限制的宿主可能需要缩小选择范围。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Yandex 360 (ycli)，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

ycli

One Yandex 360 toolkit — four ways to use it. Drive Tracker, Wiki, and Forms from a CLI, an MCP server, a Python SDK, or a Claude Code plugin. Built for AI agents first — pleasant for humans too.

[CI] [Coverage] [PyPI] [Python] [License] [Ask DeepWiki]

[ycli in action]
  • 🧩 One SDK, four surfaces — write logic once, use it as a CLI, an MCP server, a Python library, or a Claude Code plugin.
  • 🤖 Agent-native — the MCP server exposes read and write tracker_*, wiki_*, forms_* tools, one per SDK/CLI operation, plus a cross-cutting status tool (counts in Coverage), with honest annotations (reads are marked read-only; writes declare whether they are destructive/idempotent); ycli mcp start --read-only serves a reads-only view for cautious deployments, and --toolsets core serves a curated everyday profile when a host limits how many tools it accepts.
  • 🛡️ Trustworthy — typed pydantic models, the real Yandex API quirks handled for you, and a test suite kept at 100% coverage.
  • ⚡ Zero-friction start — uv add yandex-cli, ycli auth login, go.

Install

bash
uv add yandex-cli            # CLI + Python SDKuv add 'yandex-cli[mcp]'     # …plus the MCP server (`ycli mcp start`)

Run it without installing, or install it as a standalone tool:

bash
uvx yandex-cli --help                 # one-off, no installuv tool install yandex-cli            # persistent CLIuv tool install 'yandex-cli[mcp]'     # …with the MCP server

pip install yandex-cli works too. The CLI ships as both yandex-cli and the short ycli.

Using an AI harness (Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, opencode, Docker)? See Install in your harness.

The SDK's ServiceAccountAuth (IAM tokens minted from a Yandex Cloud service-account key) needs the service-account extra: uv add 'yandex-cli[service-account]'.

Quick start

Pick the surface that fits how you work.

CLI
bash
uv add yandex-cliycli --helpycli tracker issues get TRACKER-1ycli wiki pages get onboarding

Output formats — a global --format / -o picks how results print (the global options work before or after the subcommand: ycli -o json tracker issues get K = ycli tracker issues get K -o json; a command that declares an option of its own, like forms answers export --format, keeps it):

bash
ycli tracker issues get TRACKER-1            # auto: a pretty table on a TTY…ycli tracker issues get TRACKER-1 | jq .     # …and raw JSON when piped (agent/script-safe)ycli -o yaml wiki pages get onboarding       # or: -o json | -o yaml | -o prettyycli --jq .summary tracker issues get TRACKER-1   # filter the JSON with jq; a string prints bare

--jq EXPR runs a jq program over the command's JSON result and prints like jq -r: a string comes out raw, anything else as one compact JSON value per line. It cannot be combined with -o yaml / -o pretty, and it needs the jq Python package (a dependency; it has no build for Windows on ARM).

Deleting asks first. A command that destroys data (every delete, clear, abort…) asks DELETE <url> — this deletes data. Continue? on stderr when you are at a terminal, and exits 1 if you decline. In a script, a pipe or CI there is no one to ask, so it fails with exit 2 until you pass --yes / -y: ycli tracker boards delete 7 --yes. Reads and ordinary writes never ask.

Preview a write. --dry-run sends nothing for any write: it prints the request instead (method, URL, body; never your token), through the same -o / --jq output, and exits 0. Reads still run, so a command that reads and then writes shows its first write only: ycli tracker boards delete 7 --dry-run. (The two commands that ask the API itself to validate a request, forms filling submit and wiki pages move, call that --validate-only.)

An endpoint ycli has not wrapped. ycli api PATH --service tracker|wiki|forms calls it like gh api would, with the same auth, retries, output and exit codes:

bash
ycli api issues/TRACKER-1 --service tracker --jq .summary           # GET (the default method)ycli api issues/TRACKER-1/comments --service tracker -F [email protected]   # POST: a field turns it into oneycli api pages/descendants --service wiki -f slug=docs --paginate   # every page, as one JSON array

PATH is relative to the service's base URL; a full URL of a service needs no --service, and any other host is refused (your token never goes elsewhere). -f key=value is a string, -F is typed (true, null, numbers, JSON, @file for a file's text, key[sub]=v to nest, key[]=v for an array); fields of a GET or DELETE go to the query string, otherwise to a JSON body (--input FILE sends a raw body instead). -H 'Name: value' adds a header, -X sets the method, and --dry-run, --yes and --jq behave as everywhere. --paginate follows Tracker's Link: rel="next" and Wiki's next_cursor; Forms pages its listings in more than one way, so pass its paging parameters with -f yourself.

MCP server (read/write)

Run it over stdio (needs the mcp extra):

bash
ycli mcp start               # full read/write tool set (honest annotations)ycli mcp start --read-only   # reads-only view for cautious deployments

Serving all 322 tools costs a large tools/list and some hosts cap a request (VS Code allows 128 tools), so pick what the session needs:

FlagServes
--toolsets tracker,wikionly those services (tracker, wiki, forms); default all
--toolsets corea curated everyday profile of about 40 tools (issues, comments, transitions, worklog, wiki pages and search, form reads)
--tools a,b / --exclude-tools a,badd or hide single tools by name (unknown names fail at start)
--read-onlyno write tools; always wins over the flags above
--tool-searchlists a search tool and a call proxy instead of the tools; use it with a large set

status_get is always served. The listing omits output schemas and doctest examples (results still carry structuredContent), which cuts tools/list from about 1.9 MB to about 0.5 MB for the full set.

For several users, serve it over HTTP: each MCP client signs its user in through Yandex ID (OAuth), and every tool call runs with that user's own Yandex token. Setup, including the Yandex OAuth app and the reverse proxy, is in Self-host over HTTP.

bash
ycli mcp start --transport http --toolsets core   # needs YCLI__MCP__BASE_URL and an OAuth app

List the tool names a given set of flags exposes without running the server:

bash
ycli mcp methods --toolsets core --read-only

Point an MCP client at it — no prior install needed via uvx (tools are namespaced tracker_*, wiki_*, forms_*):

json
{  "mcpServers": {    "yandex": {      "command": "uvx",      "args": ["--from", "yandex-cli[mcp]", "ycli", "mcp", "start"],      "env": {        "YANDEX_ID_OAUTH_TOKEN": "...",        "YANDEX_ID_ORGANIZATION_ID": "..."      }    }  }}
Python SDK
python
from ycli.yandex.tracker.client import TrackerClient
tracker = TrackerClient(oauth_token="…", organization_id="…")issue = tracker.issues.get("TRACKER-1")print(issue.summary)
Claude Code plugin 
/plugin marketplace add bim-ba/ycli/plugin install yandex-360@ycli

Teaches an agent to drive Yandex 360 through ycli — including the real API quirks. See plugins/yandex-360/.

Skills (Claude Code plugin)

SkillUse for
yandex-360Entry point — install + auth, pick a surface (CLI/MCP/SDK), route to a domain
yandex-360-trackerIssues, epics, comments, transitions, links, worklog, changelog
yandex-360-wikiWiki pages, page tree, comments, attachments, YFM authoring
yandex-360-formsForms, questions/schema, responses, publishing

The skills encode the read/write commands and the gnarly Yandex API quirks (epic-vs-parent, transition discovery, permanent wiki slugs, fields= rules, Forms host/header traps, answers pagination).

Configure

ycli reads two values from the environment (or a .env file — cp .env.example .env):

bash
YANDEX_ID_OAUTH_TOKEN=...        # a Yandex OAuth token with Tracker/Wiki/Forms accessYANDEX_ID_ORGANIZATION_ID=...    # your Yandex 360 organization id

ycli sends the org id as X-Org-Id for every service (HTTP header names are case-insensitive per RFC 9110, so one casing serves all).

Optional settings follow the YCLI__<GROUP>__<SETTING> pattern; ycli rejects an invalid value at startup and names the variable:

VariableDefaultMeaning
YCLI__HTTP__TIMEOUT_SECONDS30Per-request timeout, seconds (> 0)
YCLI__HTTP__RETRIES3Retries for idempotent requests on 429/5xx (≥ 0)
YCLI__HTTP__MAX_ITEMS500Item cap for listings without --limit/--all (> 0)
YCLI__LOGGING__LEVELWARNINGDEBUG, INFO, WARNING, ERROR or CRITICAL; -v means INFO (every HTTP request), -vv means DEBUG
YCLI__LOGGING__FORMATtexttext or json (one object per line); logs always go to stderr

Get your credentials

Yandex issues OAuth tokens only through a registered application, so it's a one-time app registration plus one command.

1. Register an OAuth app at oauth.yandex.ru and grant it the Tracker, Wiki, and Forms permissions (read and write — the CLI and the MCP server both write; the read scopes alone suffice only if you run the MCP server with ycli mcp start --read-only). Put the ClientID — and the Client secret if you want the headless flow — in your .env (ycli reads it from there):

bash
YANDEX_OAUTH_CLIENT_ID=...        # from your appYANDEX_OAUTH_CLIENT_SECRET=...    # optional — enables the headless device flow

2. Log in. ycli auth login gets a token, detects your organization, and writes both into .env:

bash
ycli auth login
  • client id + secret → the device flow: ycli prints a code and a https://ya.ru/device link; approve there and it captures the token — no redirect, works over SSH.
  • only the client id (or --implicit) → the browser flow: ycli opens the Yandex authorize page; approve, then copy the token it displays and paste it back.

Check it any time with ycli auth status: it shows whose token it is (from Yandex ID), your organization (its name needs the optional directory:read_organization scope; without it you get the id and a note) and whether each service accepts the token. ycli tracker auth status (or wiki, forms) probes just that one service. Both exit non-zero when a service rejects the token.

Prefer to do it by hand?

Headless (device flow):

bash
# 1. start the flow — returns a user_code + verification_urlcurl -s -X POST https://oauth.yandex.ru/device/code -d "client_id=$YANDEX_OAUTH_CLIENT_ID"# 2. open https://ya.ru/device, enter the user_code, approve# 3. exchange the device_code for the tokencurl -s -X POST https://oauth.yandex.ru/token \  -d grant_type=device_code -d "code=<device_code>" \  -d "client_id=$YANDEX_OAUTH_CLIENT_ID" -d "client_secret=$YANDEX_OAUTH_CLIENT_SECRET"

Browser (implicit): open https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID> in a logged-in browser, approve, and copy the token from the page. (Plain curl can't — implicit needs an interactive browser session.)

Organization id: tracker.yandex.ru/admin/orgs → your organization → copy the identifier.

Exit codes

A failed ycli command exits with a code that says what kind of failure it was, so a script can branch without parsing the message.

CodeMeaningWhen
0okthe command succeeded
1failureany other failure: a 4xx the API rejected, an unmapped error, a declined confirmation
2usagea bad command line or an invalid YCLI__… setting
3not foundthe API answered 404 (or the token cannot see the object)
4auth401 / 403, or no credentials set
5rate limitedthe API answered 429 and the retries ran out (the hint shows Retry-After)
6transienta 5xx, a timeout or a lost connection: worth retrying later

Coverage

ycli wraps 334 operations across 62 resources of the Tracker, Wiki, and Forms REST API — every one reachable from the Python SDK and the CLI, plus 322 MCP tools (321 domain-scoped + 1 cross-cutting: status) for agents.

Legend — operations ship on SDK + CLI, and the MCP server mirrors them with honest annotations: reads carry readOnlyHint, writes carry explicit destructive/idempotent hints, and ycli mcp start --read-only serves the reads-only view. In each table SDK and CLI mean the operation is wrapped on that surface; MCP is ✅ when the resource exposes at least one MCP tool. Resource and operation names link to the official Yandex API reference (yandex.ru/support/…/api-ref). These tables are generated from the code by scripts/gen_coverage.py — do not edit by hand.

Tracker

35 resources · 190 operations · 187 MCP tools

Issues & work items
ResourceOperationsSDKCLIMCP
issuesget · search · count · create · update · move · suggest · scroll_clear✅✅✅
commentslist · get · add · edit · delete · react✅✅✅
linkslist · search · add · delete✅✅✅
transitionslist · execute✅✅✅
workloglist · search · global_list · create · edit · delete✅✅✅
changeloglist✅✅✅
checklistsget · create · edit · delete · clear✅✅✅
attachmentslist · download · download_thumbnail · get · delete · upload · upload_temp✅✅✅
remotelinkslist · create · delete✅✅✅
Agile boards
ResourceOperationsSDKCLIMCP
boardslist · get · create · edit · delete✅✅✅
sprintslist · get · create · edit · delete · start · archive✅✅✅
columnslist · get · create · edit · delete✅✅✅
Dictionaries
ResourceOperationsSDKCLIMCP
prioritieslist · create · edit✅✅✅
statuseslist · create · edit✅✅✅
resolutionslist · create · edit✅✅✅
issuetypeslist · create · edit✅✅✅
linktypeslist✅✅✅
Fields, queues & structure
ResourceOperationsSDKCLIMCP
fieldslist · get · create · edit · category_create · category_edit✅✅✅
localfieldslist · get · create · edit✅✅✅
componentslist · create · edit · list_for_queue · get · delete · user_permissions · group_permissions✅✅✅
queueslist · get · tags · versions · fields · create · delete · restore · set_permissions · tag_remove · version_create · version_get · version_edit · version_delete · user_permissions · group_permissions✅✅✅
workflowslist · get · for_queue · create · edit · edit_action · delete✅✅✅
projectslist · get · queues · create · edit · delete✅✅✅
Automation & bulk
ResourceOperationsSDKCLIMCP
macroslist · get · create · edit · delete✅✅✅
triggerslist · get · create · edit · webhook_log✅✅✅
autoactionsget · create · logs · log_detail✅✅✅
dashboardscreate · add_cycle_time_widget✅✅✅
bulkupdate · move · transition · get · issues✅✅✅
importtask · comment · link · worklog · file · comment_file✅✅✅
Entities, users & search
ResourceOperationsSDKCLIMCP
entitiescreate · get · edit · delete · search · history · permissions · set_permissions · direct_permissions · set_direct_permissions · bulk_update · bulk_status · create_report · comments_list · comments_relative · comments_get · comments_create · comments_edit · comments_delete · checklists_create · checklists_edit · checklists_edit_item · checklists_delete · checklists_delete_item · checklists_move · links_list · links_create · links_delete · attachments_list · attachments_get · attachment_download · attachments_attach · attachments_delete✅✅✅
usersget · list✅✅✅
applicationslist✅✅✅
filtersget · create · edit · delete✅✅✅
gapscreate · search · delete✅✅✅
meget✅✅✅

Wiki

11 resources · 58 operations · 56 MCP tools

Pages
ResourceOperationsSDKCLIMCP
pagesget_by_id · get · descendants · descendants_by_id · grids · create · update · delete · append_content · clone · move · revisions · backlinks✅✅✅
resourceslist✅✅✅
recoveryrestore✅✅✅
searchquery✅✅✅
Collaboration
ResourceOperationsSDKCLIMCP
commentslist · thread · thread_get · create · delete✅✅✅
attachmentslist · get · preview · download · download_by_url · delete · attach · upload✅✅✅
accesscreate · update · delete · clear✅✅✅
Grids (dynamic tables)
ResourceOperationsSDKCLIMCP
gridsget · create · update · delete · add_rows · remove_rows · move_rows · add_columns · remove_columns · move_columns · update_cells · clone · suggest_column · update_column · update_row✅✅✅
Async & uploads
ResourceOperationsSDKCLIMCP
operationsclone_get · gridclone_get · move_get✅✅✅
uploadsessionscreate · get · upload_part · finish · abort · abort_all✅✅✅
Identity
ResourceOperationsSDKCLIMCP
meget✅✅✅

Forms

16 resources · 86 operations · 78 MCP tools

Surveys & questions
ResourceOperationsSDKCLIMCP
surveyslist · get · create · modify · delete · publish · unpublish✅✅✅
questionsget · list · create · modify · delete · move✅✅✅
conditionsquestion_list · question_get · question_create · question_modify · question_delete · question_set_operator · page_list · page_get · page_create · page_modify · page_delete · page_set_operator · submit_list · submit_get · submit_create · submit_modify · submit_delete · submit_set_operator · hook_list · hook_get · hook_create · hook_modify · hook_delete · hook_set_operator✅✅✅
accessget · set · grant · revoke✅✅✅
historylist✅✅✅
Responses & export
ResourceOperationsSDKCLIMCP
answersget · list · list_all · export · export_results · download_export · integrations_list · delete · restore✅✅✅
operationsget✅✅✅
Integrations
ResourceOperationsSDKCLIMCP
hookslist · get · create · modify · delete✅✅✅
subscriptionslist · get · create · modify · delete · attach✅✅✅
variableslist✅✅✅
notificationslist · get · status_get · restart · cancel · errors_list✅✅✅
Distribution
ResourceOperationsSDKCLIMCP
keysetslist · get · create · modify · delete · download✅✅✅
fillingget · submit · suggest✅✅✅
Media
ResourceOperationsSDKCLIMCP
filesupload · verify · download · delete✅✅✅
imagesupload · clone✅✅✅
Identity
ResourceOperationsSDKCLIMCP
meget✅✅✅

Every resource and operation above deep-links to the Yandex API reference: 318 of 334 operations resolve to their own endpoint page and 15 to their resource's page. No public API reference exists yet for tracker.linktypes, tracker.linktypes.list, shown as plain text. See CONTRIBUTING.md for the intentional exclusions (UI-only endpoints with no public REST API) and per-method notes.

Layout

text
src/ycli/├── cli/                # root Typer CLI  → `ycli` / `yandex-cli` (app · context · output)├── mcp/                # root FastMCP server → `ycli mcp start` (read/write, `[mcp]` extra)├── settings.py         # AppConfig + Credentials (pydantic-settings)├── log.py              # stderr logging setup (stdlib)└── yandex/    ├── tracker/        # per-domain SDK …    ├── wiki/           #   each resource group has:    └── forms/          #   client.py · cli.py · mcp.py · models.pyplugins/yandex-360/     # distributable Claude Code plugin (skills + instructions)references/             # vendored Yandex API reference docs (local-only; see references/README.md)

Development

bash
uv sync --all-extras   # --all-extras pulls in the `mcp` extra the tests exerciseuv run pytest          # 100% coverage gate; HTTP stubbed with `MockAPI` (no live network)

See CONTRIBUTING.md for conventions and how to add an endpoint. Contributions welcome.

License

MIT © 2026 Sava Znatnov

来源：README.md，提交 834801d

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v0.36.0最新Oct 2, 2026