Metadata-Version: 2.4
Name: y360-mcp
Version: 0.2.0a1
Summary: MCP server for Yandex 360 for Business: Tracker and Wiki
Project-URL: Homepage, https://sourcecraft.dev/shiftline/360-mcp
Project-URL: Repository, https://sourcecraft.dev/shiftline/360-mcp
Project-URL: Issues, https://sourcecraft.dev/shiftline/360-mcp/issues
Project-URL: Author, https://sourcecraft.dev/users/scarklei/overview
Author-email: Erich Helvig <ScarKlei@ya.ru>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: fastmcp,llm,mcp,model-context-protocol,yandex,yandex-360,yandex-tracker,yandex-wiki
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Natural Language :: Russian
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Description-Content-Type: text/markdown

# y360-mcp

[![PyPI](https://img.shields.io/pypi/v/y360-mcp.svg)](https://pypi.org/project/y360-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/y360-mcp.svg)](https://pypi.org/project/y360-mcp/)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0--or--later-blue.svg)](LICENSE)

MCP-сервер для **Яндекс 360 для бизнеса** — Трекер и Вики. Построен на [FastMCP](https://gofastmcp.com).

## Возможности

### Трекер (`tracker_*`)
- `tracker_list_queues` — список доступных очередей.
- `tracker_list_issues` — поиск/листинг задач (по `queue`, `keys`, `filter`, `query`).
- `tracker_get_issue` — получить задачу по ключу/id.
- `tracker_create_issue` — создать задачу.
- `tracker_update_issue` — изменить задачу (PATCH-патч произвольной формы).
- `tracker_delete_issue` — удалить задачу (требует особое право).
- `tracker_get_transitions` / `tracker_transition_issue` — переходы по статусам.
- `tracker_list_comments` — список комментариев к задаче (курсорная пагинация через `from_id`).
- `tracker_add_comment` — добавить комментарий (поддержка YFM через `markup_type='md'`, призыв пользователей).
- `tracker_edit_comment` — изменить комментарий.
- `tracker_delete_comment` — удалить комментарий.
- `tracker_myself` — текущий пользователь (для проверки авторизации).

### Вики (`wiki_*`)
- `wiki_get_page` / `wiki_get_page_by_id` — получить страницу.
- `wiki_list_pages` — листинг подстраниц (по slug или id, с курсорной пагинацией).
- `wiki_create_page` — создать страницу.
- `wiki_update_page` — обновить страницу.
- `wiki_delete_page` — удалить страницу (возвращает `recovery_token`).

## Структура

```
src/y360_mcp/
├── config.py              # настройки (env / .env)
├── server.py              # точка входа FastMCP
├── clients/
│   ├── base.py            # асинхронный httpx-клиент
│   ├── tracker.py         # Tracker API v3
│   └── wiki.py            # Wiki API v1
└── tools/
    ├── tracker_tools.py   # MCP-инструменты Трекера
    └── wiki_tools.py      # MCP-инструменты Вики
```

## Авторизация (OAuth 2.0)

1. Откройте https://oauth.yandex.ru → **Создать** → "Для доступа к API или отладки".
2. Добавьте права:
   - `tracker:write`, `tracker:read` — для Трекера;
   - `wiki:write`, `wiki:read` — для Вики.
3. Скопируйте `ClientID` приложения и откройте в браузере (от имени нужного пользователя):

   ```
   https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>
   ```

4. Скопируйте полученный токен.
5. Узнайте идентификатор организации: https://tracker.yandex.ru/admin/orgs (поле «идентификатор»).

## Установка

```bash
# через uvx (рекомендуется — без локального окружения)
uvx y360-mcp

# или через pipx
pipx install y360-mcp

# или через pip
pip install y360-mcp
```

## Настройка

```bash
cp .env.example .env
# заполните YANDEX_OAUTH_TOKEN и YANDEX_ORG_ID
uv sync
```

Для Yandex Cloud Organization используйте `YANDEX_CLOUD_ORG_ID` (вместо `YANDEX_ORG_ID`)
и/или `YANDEX_IAM_TOKEN` вместо OAuth.

## Запуск

```bash
uv run y360-mcp
# или
uv run python main.py
```

Сервер использует **stdio**-транспорт — подключайте его к любому MCP-клиенту
(Claude Desktop, Cursor, OpenCode и т.д.):

```json
{
  "mcpServers": {
    "y360": {
      "command": "uvx",
      "args": ["y360-mcp"],
      "env": {
        "YANDEX_OAUTH_TOKEN": "y0__xAbc...",
        "YANDEX_ORG_ID": "1234..."
      }
    }
  }
}
```

## Лицензия

[AGPL-3.0-or-later](LICENSE) — все производные работы должны оставаться под совместимой open-source лицензией.

## Полезные ссылки

- [API Яндекс Трекера](https://yandex.ru/support/tracker/ru/api-ref/about-api)
- [Доступ к API Трекера](https://yandex.ru/support/tracker/ru/api-ref/access)
- [API Яндекс Вики](https://yandex.ru/support/wiki/ru/api-ref/)
- [FastMCP docs](https://gofastmcp.com/servers/server)
