# yougile-mcp

[![CI](https://github.com/IvanTereshin/yougile-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/IvanTereshin/yougile-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/yougile-mcp.svg)](https://www.npmjs.com/package/yougile-mcp)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)

A production-grade [Model Context Protocol](https://modelcontextprotocol.io) server for
[YouGile](https://yougile.com) — lets AI agents (Claude Desktop, Cursor, and any MCP client)
read and manage your YouGile projects, boards, tasks, employees and more.

> Unlike a thin API wrapper, this server ships **full CRUD coverage**, **MCP resources**
> and **ready-made prompts**, with retries, strict input validation, tests and CI.

_[Русская версия ниже ↓](#русская-версия)_

---

## Why this server

|                  | Typical YouGile MCP wrapper | **yougile-mcp**                              |
| ---------------- | --------------------------- | -------------------------------------------- |
| API coverage     | partial (a few resources)   | **all core resources** (projects → webhooks) |
| MCP primitives   | tools only                  | **tools + resources + prompts**              |
| Input validation | minimal                     | **Zod schemas on every tool**                |
| Reliability      | single attempt              | **retry + backoff, 429/`Retry-After` aware** |
| Tests / CI       | none                        | **unit + integration, GitHub Actions**       |
| Transports       | stdio                       | **stdio + Streamable HTTP**                  |

## Capabilities

**Tools (44)** — full `list` / `get` / `create` / `update` (soft-delete via `update`) for:
`projects`, `boards`, `columns`, `tasks`, `users`, `departments`, `group_chats`,
`string_stickers`, `sprint_stickers`, `webhooks` — plus task chat
(`yougile_chat_list_messages`, `yougile_chat_send_message`) and company
(`yougile_company_get`, `yougile_company_update`).

**Resources** — `yougile://projects`, `yougile://users`, and the template
`yougile://board/{boardId}` (a board with its columns).

**Prompts** — `triage_board`, `create_task_from_note`, `standup_report`, `find_stale_tasks`.

See [docs/TOOLS.md](./docs/TOOLS.md) for the full reference.

## Quick start

You need a YouGile API key: **YouGile → Settings → API**, or via
`POST https://yougile.com/api-v2/auth/keys`.

```bash
# Run directly with npx
YOUGILE_API_KEY=your-key npx yougile-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "yougile": {
      "command": "npx",
      "args": ["-y", "yougile-mcp"],
      "env": { "YOUGILE_API_KEY": "your-key" }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "yougile": {
      "command": "npx",
      "args": ["-y", "yougile-mcp"],
      "env": { "YOUGILE_API_KEY": "your-key" }
    }
  }
}
```

## Configuration

All configuration is via environment variables (see [.env.example](./.env.example)):

| Variable                | Required | Default                      | Description                             |
| ----------------------- | -------- | ---------------------------- | --------------------------------------- |
| `YOUGILE_API_KEY`       | ✅       | —                            | YouGile API bearer token                |
| `YOUGILE_BASE_URL`      |          | `https://yougile.com/api-v2` | API base URL (override for self-hosted) |
| `YOUGILE_TIMEOUT_MS`    |          | `30000`                      | Per-request timeout                     |
| `YOUGILE_MAX_RETRIES`   |          | `3`                          | Retries for 429/5xx/network             |
| `YOUGILE_MCP_TRANSPORT` |          | `stdio`                      | `stdio` or `http`                       |
| `YOUGILE_MCP_HTTP_PORT` |          | `3000`                       | Port when `transport=http`              |

### HTTP transport

```bash
YOUGILE_API_KEY=your-key YOUGILE_MCP_TRANSPORT=http YOUGILE_MCP_HTTP_PORT=3000 npx yougile-mcp
# Stateless Streamable HTTP endpoint at POST http://localhost:3000/mcp
```

## Development

```bash
npm install
npm run build        # bundle to dist/ (tsup)
npm run typecheck    # tsc --noEmit (strict)
npm run lint         # eslint (type-checked)
npm test             # vitest (unit + integration)
```

### Architecture

```
src/
  config.ts          # env config, Zod-validated
  client/            # typed YouGile API client
    http.ts          #   fetch + timeout + retry/backoff
    yougile.ts       #   resource namespaces (client.tasks.list(...))
    types.ts errors.ts
  tools/             # MCP tools (CRUD via a shared helper) + chat/company
  resources/         # MCP resources (projects, users, board template)
  prompts/           # MCP prompts (triage, standup, ...)
  transport/http.ts  # stateless Streamable HTTP
  server.ts          # factory: wires client + tools/resources/prompts
  index.ts           # bin entrypoint (stdio | http)
```

## License

[MIT](./LICENSE) © Ivan Tereshin

---

## Русская версия

Production-grade сервер [Model Context Protocol](https://modelcontextprotocol.io) для
[YouGile](https://yougile.com). Позволяет AI-агентам (Claude Desktop, Cursor и любым
MCP-клиентам) читать и управлять проектами, досками, задачами и сотрудниками в YouGile.

> В отличие от тонкой обёртки над API, этот сервер даёт **полное покрытие CRUD**,
> **MCP-ресурсы** и **готовые prompt-сценарии**, с ретраями, строгой валидацией входных
> данных, тестами и CI.

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

**Инструменты (44)** — полный `list` / `get` / `create` / `update` (мягкое удаление через
`update`) для ресурсов: `projects`, `boards`, `columns`, `tasks`, `users`, `departments`,
`group_chats`, `string_stickers`, `sprint_stickers`, `webhooks`. Плюс чат задачи
(`yougile_chat_list_messages`, `yougile_chat_send_message`) и компания
(`yougile_company_get`, `yougile_company_update`).

**Ресурсы** — `yougile://projects`, `yougile://users` и шаблон `yougile://board/{boardId}`
(доска со своими колонками).

**Prompt-сценарии** — `triage_board` (триаж доски), `create_task_from_note` (задача из
заметки), `standup_report` (отчёт-летучка), `find_stale_tasks` (поиск «застрявших» задач).

### Быстрый старт

Нужен API-ключ YouGile: **Настройки → API** (или `POST .../api-v2/auth/keys`).

```bash
YOUGILE_API_KEY=ваш-ключ npx yougile-mcp
```

Конфигурация Claude Desktop / Cursor — см. блоки выше; все переменные окружения описаны в
[.env.example](./.env.example) и таблице [Configuration](#configuration).

### Лицензия

[MIT](./LICENSE) © Иван Терешин