Metadata-Version: 2.4
Name: yandex-cli
Version: 0.9.0
Summary: Interact with Yandex 360 services (Wiki, Tracker, Forms, …) from a CLI, an MCP server, or a Python SDK.
Project-URL: Homepage, https://github.com/bim-ba/ycli
Project-URL: Repository, https://github.com/bim-ba/ycli
Project-URL: Documentation, https://github.com/bim-ba/ycli/tree/main/docs
Project-URL: Issues, https://github.com/bim-ba/ycli/issues
Project-URL: Changelog, https://github.com/bim-ba/ycli/blob/main/CHANGELOG.md
Author-email: Sava Znatnov <careless.sava@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,fastmcp,forms,mcp,sdk,tracker,typer,wiki,yandex,yandex-360
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: loguru>=0.7.3
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.34.2
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.26.8
Requires-Dist: uplink>=0.10.0
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.4.2; extra == 'mcp'
Description-Content-Type: text/markdown

<div align="center">

# 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](https://img.shields.io/github/actions/workflow/status/bim-ba/ycli/ci.yml?branch=main&logo=githubactions&logoColor=white&label=ci)](https://github.com/bim-ba/ycli/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?logo=pytest&logoColor=white)](https://github.com/bim-ba/ycli)
[![PyPI](https://img.shields.io/pypi/v/yandex-cli?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/yandex-cli/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-lightgrey?logo=opensourceinitiative&logoColor=white)](LICENSE)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bim-ba/ycli)

<img src="https://raw.githubusercontent.com/bim-ba/ycli/main/docs/assets/demo.gif" alt="ycli in action" width="760">

</div>

## Why ycli

- 🧩 **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-only `tracker_*`, `wiki_*`, `forms_*`
  tools so agents explore safely; writes stay in the CLI/SDK.
- 🛡️ **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`, two env vars, go.

## Install

```bash
uv add yandex-cli            # CLI + Python SDK
uv 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 install
uv tool install yandex-cli            # persistent CLI
uv 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`.

## Quick start

Pick the surface that fits how you work.

<details open>
<summary><b>CLI</b></summary>

```bash
uv add yandex-cli
ycli --help
ycli tracker issues get TRACKER-1
ycli wiki pages get onboarding
```

**Output formats** — a global `--format` / `-o` picks how results print:

```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 pretty
```
</details>

<details>
<summary><b>MCP server</b> (read-only)</summary>

Run it over stdio (needs the `mcp` extra):

```bash
ycli mcp start
```

List the exposed tool names without running the server:

```bash
ycli mcp methods
```

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": "..."
      }
    }
  }
}
```
</details>

<details>
<summary><b>Python SDK</b></summary>

```python
from ycli.yandex.tracker.client import TrackerClient

tracker = TrackerClient(oauth_token="…", organization_id="…")
issue = tracker.issues.get("TRACKER-1")
print(issue.summary)
```
</details>

<details>
<summary><b>Claude Code plugin</b></summary>

```
/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/`](plugins/yandex-360/).
</details>

## Skills (Claude Code plugin)

| Skill | Use for |
|-------|---------|
| `yandex-360` | Entry point — install + auth, pick a surface (CLI/MCP/SDK), route to a domain |
| `yandex-360-tracker` | Issues, epics, comments, transitions, links, worklog, changelog |
| `yandex-360-wiki` | Wiki pages, page tree, comments, attachments, YFM authoring |
| `yandex-360-forms` | Forms, questions/schema, responses, pagination |

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).

## What's covered

Reads ship across **SDK + CLI + MCP**; writes across **SDK + CLI** only (the MCP server is
read-only by design).

### Tracker

| Resource | Operations | SDK | CLI | MCP |
|----------|-----------|:---:|:---:|:---:|
| issues | get · full · search · list · count | ✅ | ✅ | ✅ |
| issues | create · update | ✅ | ✅ | — |
| comments | list | ✅ | ✅ | ✅ |
| comments | add | ✅ | ✅ | — |
| links | list | ✅ | ✅ | ✅ |
| links | add | ✅ | ✅ | — |
| transitions | list | ✅ | ✅ | ✅ |
| transitions | execute | ✅ | ✅ | — |
| worklog · changelog · priorities · issuetypes · linktypes | list | ✅ | ✅ | ✅ |

### Wiki

| Resource | Operations | SDK | CLI | MCP |
|----------|-----------|:---:|:---:|:---:|
| pages | get · descendants | ✅ | ✅ | ✅ |
| pages | meta (metadata-only) | — | — | ✅ |
| pages | create · update | ✅ | ✅ | — |
| comments | list | ✅ | ✅ | ✅ |
| attachments | list | ✅ | ✅ | ✅ |

### Forms (read-only today)

| Resource | Operations | SDK | CLI | MCP |
|----------|-----------|:---:|:---:|:---:|
| me | get (whoami) | ✅ | ✅ | ✅ |
| surveys | list · get | ✅ | ✅ | ✅ |
| questions | list | ✅ | ✅ | ✅ |
| answers | list (drains all pages) | ✅ | ✅ | ✅ |

> **Mail and more — coming.** See [`docs/api-coverage.md`](docs/api-coverage.md) for the full
> gap analysis and prioritized roadmap.

## Configure

```bash
cp .env.example .env
```

```bash
YANDEX_ID_OAUTH_TOKEN=...        # get one at https://oauth.yandex.ru/
YANDEX_ID_ORGANIZATION_ID=...    # from the Yandex 360 admin panel
```

Header casing differs per service (Tracker `X-Org-ID`, Wiki/Forms `X-Org-Id`) — ycli
handles it for you.

## Project layout

```text
src/ycli/
├── cli.py              # root Typer CLI  → `ycli` / `yandex-cli`
├── mcp.py              # root FastMCP server → `ycli mcp start` (read-only, `[mcp]` extra)
├── log.py              # central loguru config
└── yandex/
    ├── tracker/        # per-domain SDK …
    ├── wiki/           #   each resource group has:
    └── forms/          #   client.py · cli.py · mcp.py · models.py
plugins/yandex-360/     # distributable Claude Code plugin (skills + instructions)
docs/references/        # vendored Yandex API reference docs
```

## Development

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for conventions. Contributions welcome — the
[coverage roadmap](docs/api-coverage.md) is a good place to find a first issue.

## License

[MIT](LICENSE) © 2026 Sava Znatnov
