Пачка API

Пачка API

English version: README.en.md

Всё для работы с API Пачки, корпоративного мессенджера: документация, MCP-сервер и скиллы для AI-агентов, CLI, SDK на шести языках и нода для n8n. API описан на TypeSpec, и из этого описания собирается остальное: OpenAPI, страницы методов, CLI, SDK, нода n8n, набор инструментов MCP-сервера и файлы для агентов. Скиллы пишутся руками, а сборка сверяет их с тем же описанием.

Документация: https://dev.pachca.com · OpenAPI: https://dev.pachca.com/openapi.yaml · Авторизация: https://dev.pachca.com/api/authorization · Changelog: https://dev.pachca.com/updates · Postman/Bruno: https://dev.pachca.com/pachca.postman_collection.json

MCP-сервер

https://mcp.pachca.com/mcp — инструмент на каждый метод API. Какие инструменты видит агент, зависит от роли сотрудника, тарифа и типа токена. Claude Code, Claude, VS Code и GitHub Copilot, Codex и приложение ChatGPT на компьютере входят через браузер, остальные программы передают токен в заголовке. Сервер опубликован в официальном реестре MCP под именем com.pachca/mcp, описание для реестра — server.json. Правила каждого метода сервер отдаёт в описаниях инструментов, а общие правила поведения — в своих инструкциях. Довести до конца задачу из нескольких шагов агенту помогают скиллы: их ставят отдельно, одной командой.

claude mcp add --transport http pachca https://mcp.pachca.com/mcp

Документация: dev.pachca.com/guides/mcp · Подключение программ: dev.pachca.com/guides/mcp/connect · Манифест инструментов: @pachca/mcp-manifest

CLI

# Без установки (npx)
npx @pachca/cli messages create --entity-id=123 --content="Привет!" --token $PACHCA_TOKEN

# Для постоянной работы
npm install -g @pachca/cli
pachca auth login
pachca messages create --entity-id=123 --content="Привет!"

# Встроенный справочник по API прямо в терминале (для агентов)
pachca api ls                          # список всех эндпоинтов
pachca api POST /messages --describe   # параметры, тело, пример
pachca api POST /messages -F 'message[entity_id]=123' -f 'message[content]=Привет'  # прямой запрос

Все методы API доступны как команды. Типизированные флаги, валидация, 4 формата вывода (table, JSON, YAML, CSV), курсорная пагинация, несколько профилей авторизации, неинтерактивный режим для CI и AI-агентов. Команда pachca api — прямые запросы к любому методу и встроенный справочник по API (ls, --describe, --spec, --docs) из той же OpenAPI-спеки: агенту не нужно открывать сайт документации.

Агент, который может запускать команды, делает через CLI всё то же, что через MCP-сервер, и тратит меньше контекста модели: команды он узнаёт из --help. Скиллы работают и с CLI. Вход pachca auth login выполняют в своём терминале, а не в команде агента: подробнее в разделе AI-агент с CLI.

Документация: https://dev.pachca.com/guides/cli

Скиллы и плагин

Скиллы — знание о задачах в Пачке из нескольких шагов: пересказать тред целиком и по порядку, собрать дайджест, подключить программу и выбрать токен, сделать бота, OAuth-приложение или скрипт. Правила каждого метода и общие правила поведения агент с MCP-сервером берёт уже из описаний инструментов и инструкций сервера. Скиллы подробнее разбирают переписку с коллегами, а агенту с CLI, API или SDK заранее подсказывают, что важно для задачи. Инструмент MCP или команда CLI рассказывают про один метод API, а скилл — как связать вызовы в задачу. Справочник по аргументам агент берёт из описаний инструментов MCP-сервера, pachca <команда> --help и страниц методов, поэтому скиллы его не повторяют. Скиллы работают с любым способом доступа: MCP-сервер, CLI, API или SDK. Агент берёт скилл сам, когда задача ему подходит.

Скиллы ставит одна команда, ей нужен Node.js 22.20 или новее. Можно и попросить агента: «Поставь скиллы Пачки: npx skills add https://dev.pachca.com -g -a <эта программа> -y».

# claude-code, codex, cursor, github-copilot, opencode, devin, cline, kilo, qwen-code, gemini-cli и другие
npx skills add https://dev.pachca.com -g -a claude-code -y

Плагин «Пачка» необязателен. Он ставит MCP-сервер и скиллы одной установкой в Claude Code, приложение Claude, Codex, VS Code с GitHub Copilot и Cursor, а скиллы обновляются вместе с ним:

# Claude Code
claude plugin marketplace add pachca/openapi --sparse .claude-plugin plugins
claude plugin install pachca@pachca

# Codex
codex plugin marketplace add pachca/openapi --sparse .agents/plugins --sparse plugins/pachca
codex plugin add pachca@pachca

# GitHub Copilot CLI и VS Code
copilot plugin marketplace add pachca/openapi
copilot plugin install pachca@pachca

# Cursor CLI: затем в сессии агента выполните /plugin и установите pachca
agent plugin marketplace add https://github.com/pachca/openapi

В Cursor сервер плагина подключается персональным токеном из переменной PACHCA_TOKEN. В агент, где уже стоит плагин, скиллы через npx skills не ставьте: у него окажется по две копии каждого скилла. Cursor, приложение Claude и вход в Пачку — на странице Плагин, скиллы без Node.js и в GigaCode CLI — в разделе Установка вручную страницы «Скиллы».

Скилл можно вызвать и явно, например в Claude Code /pachca-watch-thread, а с плагином /pachca:pachca-watch-thread. Как это сделать в остальных программах, сказано в разделе Вызов скилла страницы «Скиллы».

Скиллы пишутся руками в plugins/pachca/skills/<name>/. Сборка публикует их на dev.pachca.com (/.well-known/agent-skills/index.json, /skill.md) и проверяет ссылки, имена инструментов MCP и команд CLI. В скиллах только инструкции, кроме pachca-watch-thread: он запускает в фоне скрипт scripts/watch.mjs на Node.js, который следит за тредом через CLI, поэтому ему нужен @pachca/cli с входом pachca auth login или персональным токеном в переменной PACHCA_TOKEN. Прогоны плагина через claude plugin eval лежат в plugins/pachca/evals, как их запускать — в CONTRIBUTING.md.

n8n

Community node для n8n — 19 ресурсов, больше 100 операций, Pachca Trigger с авторегистрацией вебхука.

# В n8n: Settings > Community Nodes > n8n-nodes-pachca
npm install n8n-nodes-pachca

Автоматически генерируется из OpenAPI-спецификации, полная обратная совместимость с v1.

Документация: dev.pachca.com/guides/n8n · Готовые workflow: dev.pachca.com/guides/n8n/workflows · README

SDK

Все SDK следуют единому паттерну: PachcaClient(token) → client.service.method(request).

Конвенции:

• Вход: path-параметры передаются аргументами метода. Тело из одного обязательного поля, например роль участника чата, тоже разворачивается в аргумент. Остальные тела передаются одним объектом-запросом.
• Выход: если ответ API содержит единственное поле data, SDK возвращает его содержимое напрямую. Если рядом с data есть meta (списки и метод Новый чат), SDK возвращает ответ целиком: data и meta.
• Сервисы называются по тегам OpenAPI, методы — по operationId без префикса до _ (UserOperations_listUsers → listUsers), а имена методов и полей пишутся в стиле языка: listUsers и createdAt в TypeScript, list_users и created_at в Python, ListUsers и CreatedAt в Go.

Пример (TypeScript):

import { PachcaClient } from "@pachca/sdk";

const pachca = new PachcaClient("YOUR_TOKEN");
const users = await pachca.users.listUsers();
await pachca.reactions.addReaction(messageId, { code: "👍" }); // тело из нескольких полей → объект-запрос

SDK генерируются из openapi.yaml. При пуше в main CI коммитит перегенерированный код (chore: regenerate SDK), а когда в apps/docs/data/releases.json появилась новая версия sdk, ставит теги и публикует её в npm, PyPI, NuGet и JitPack. Swift и Go выходят через Git-теги. Как выбрать версию — в docs/releases.md.

Генератор

Вместо готового SDK можно сгенерировать типизированный клиент прямо в своём проекте:

npx @pachca/generator --output ./generated --lang typescript
npx @pachca/generator --output ./generated --lang typescript,python,go,kotlin,swift,csharp

Документация: https://dev.pachca.com/guides/sdk/overview

Тестирование

AI-интеграции

Через CLI справочник по API доступен и без сайта, без входа и без токена: pachca api ls, pachca api <МЕТОД> <путь> --describe.

Все файлы доступны с Access-Control-Allow-Origin: * и Cache-Control: public, max-age=300, s-maxage=3600, stale-while-revalidate=86400. .md-версии страниц, llms-full.txt, llms-en.txt и файлы скиллов помечены X-Robots-Tag: noindex, а /llms.txt индексируется, чтобы агенты находили его через поиск.

Разработка

bun install

bun turbo dev            # Разработка с hot reload (localhost:3000)
bun turbo build          # Production сборка
bun turbo check          # lint, typecheck, knip, формат, тесты, сверки спеки и доки с кодом
bun turbo generate       # TypeSpec → openapi.yaml + SDK

Перед PR прогоните шаги check.yml: bun turbo check, bun run check:changelog, bun run check:docs-format, bun run check:markdown и после коммита CI=1 bun run check:generated (без CI=1 или --force сверка сгенерированных файлов локально пропускается). После правки спеки bun run sdk:build повторяет сборку SDK из sdk.yml, а bun run check:mcp-manifest проверяет пакет MCP-манифеста по схеме. Порядок работы и правила веток — в CONTRIBUTING.md. AI-агенту, который работает в этом репозитории, — в AGENTS.md (CLAUDE.md ссылается на него). AGENTS.md генерирует сборка, руками его не правят.

CI/CD

Пакет публикуется, только когда у него новая версия и запись в changelog: проверку check-release и правила версий описывает docs/releases.md. Плагин в реестры не публикуется, программы берут его из этого репозитория. Его версию руками не меняют: сборка доков ставит её на патч выше, чем в main. Изменённому плагину нужна запись с product plugin и этой версией в apps/docs/data/releases.json, а новой версии @pachca/mcp-manifest — запись с product mcp, иначе check-changelog-sync падает. server.json выкладывают в реестр MCP вручную утилитой mcp-publisher после публикации манифеста с той же версией.

Контакты

• GitHub Issues
• [email protected] · [email protected]

Процесс разработки

Канонические доки (читать перед соответствующей задачей; AGENTS.md ссылается на них):

• CONTRIBUTING.md — раскладка, пайплайн генерации, build/check, workflow веток и PR
• docs/api-audit.md — аудит API и синхронизация с бэкендом (запускается на «проверь API»), bump версий и changelog'ов
• docs/updates-format.md — правила записей content/updates/<дата>.md, releases.json и changelog.json (нарушение ломает страницу обновлений)
• docs/docs-conventions.md — конвенции MDX/TypeSpec, регистрация компонентов в трёх местах, заголовки
• docs/releases.md — публикация пакетов, версии и проверки check-changelog-sync и check-release

Структура монорепозитория

├── apps/
│   └── docs/              # Next.js 16 сайт документации (@pachca/docs)
├── packages/
│   ├── spec/              # TypeSpec спецификация, английский оверлей, examples.ts, сборка MCP-манифеста (@pachca/spec)
│   ├── generator/         # SDK код-генератор для 6 языков (@pachca/generator)
│   ├── openapi-parser/    # Парсер OpenAPI-спеки (@pachca/openapi-parser)
│   ├── mcp-manifest/      # MCP-манифест и его схема для npm (@pachca/mcp-manifest)
│   └── cli/               # CLI для работы с API (@pachca/cli)
├── sdk/                   # SDK для 6 языков (генерируются @pachca/generator)
│   ├── typescript/        # npm
│   ├── python/            # PyPI
│   ├── go/                # Go modules
│   ├── kotlin/            # JitPack
│   ├── swift/             # SPM
│   └── csharp/            # NuGet
├── integrations/
│   └── n8n/               # n8n community node (генерируется из OpenAPI)
├── plugins/pachca/        # Плагин «Пачка»: скиллы (пишутся руками), настройки MCP, манифест для каждой программы
│   ├── skills/            # 9 скиллов
│   └── evals/             # Прогоны плагина через claude plugin eval: routing, knowledge, actions
├── .claude-plugin/        # Маркетплейс для Claude Code, приложения Claude и GitHub Copilot
├── .cursor-plugin/        # Маркетплейс для Cursor
├── .agents/plugins/       # Маркетплейс для Codex
├── docs/                  # Канонические процесс-доки (api-audit, updates-format, docs-conventions, releases)
├── scripts/               # Проверки CI (changelog, сгенерированные файлы, выпуск пакетов, MCP-манифест) и служебные скрипты: сборка SDK, первая публикация в npm, снапшоты генератора
├── server.json            # Описание MCP-сервера для официального реестра MCP (com.pachca/mcp)
├── llms-install.md        # Как агенту в Cline поставить MCP-сервер (для каталога Cline)
├── CONTRIBUTING.md        # Раскладка, пайплайн генерации, build/check, workflow
├── AGENTS.md              # Гайд для AI-агентов по работе с репозиторием (CLAUDE.md → симлинк)
├── .github/workflows/     # CI/CD (check, sdk, generator, mcp-manifest, n8n, deploy, gitlab)
├── Package.swift          # Корневой Swift Package: указывает на sdk/swift/generated, SwiftPM ставит SDK из корня репозитория
├── jitpack.yml            # JitPack конфиг для Kotlin (JDK 17)
├── Dockerfile             # Multi-stage Docker-сборка docs
├── context7.json          # закрепляет библиотеку pachca/openapi в Context7
├── turbo.json             # Turborepo пайплайн
└── package.json           # Корневой (workspaces: apps/*, apps/*/*, packages/*, sdk/*, integrations/*)

Пайплайн данных

typespec.tsp (packages/spec)
    │
    │ tsp compile
    ▼
openapi.yaml ─────────────┬─────────────────┬──────────────────────┐
    │                     │                 │                      │
    │ overlay:apply       ▼                 ▼                      ▼
    ▼                packages/cli      sdk/* (6 языков)     integrations/n8n
openapi.en.yaml           │                 │                      │
    │                     │ generate-cli    │ CI: generate         │ generate-n8n
    │                     ▼                 │ + publish            ▼
    │              npm (@pachca/cli)        ▼                   npm (n8n-nodes-pachca)
    │                                npm, PyPI, NuGet,
    │                                JitPack, SPM, Go modules
    │
    │ generate-mcp
    ├──────────────► mcp-manifest.json ──► npm (@pachca/mcp-manifest) ──► mcp.pachca.com
    │
    ▼
apps/docs ◄──────── plugins/pachca (скиллы пишутся руками)
    │
    │ generate-llms, next build
    ▼
  Сайт + llms.txt + llms-full.txt + llms-en.txt
  + skill.md + per-endpoint и per-guide .md
  + скиллы на сайте (.well-known/{skills,agent-skills}/, /skills/*.zip)
  + AGENTS.md, версия плагина в его манифестах
  + pachca.postman_collection.json
  + примеры запросов: cURL и CLI из lib/code-generators, SDK из examples.json каждого SDK
  + OG-изображения + sitemap + RSS

Сервер mcp.pachca.com живёт в бэкенде Пачки и исполняет собственную копию манифеста из пакета @pachca/mcp-manifest. Новую версию он сам не подхватывает: после публикации пакета её передают команде бэкенда, порядок описан в docs/releases.md. Описания инструментов пишутся в packages/spec/mcp-core.ts и mcp-tools.ts, а как модель выбирает инструменты по ним, проверяют прогоны по сценариям packages/spec/mcp-scenarios.ts (eval:build, eval:run, eval:score в packages/spec).

Turborepo пайплайн

Архитектура docs (apps/docs)

Next.js 16 (App Router, Turbopack) + MDX + FlexSearch (+ русские синонимы/стемминг) + Shiki + Mermaid + GSAP.

Всё динамическое — навигация, маршруты, поиск, примеры кода генерируются из OpenAPI.

Что генерируется автоматически

Маршрутизация

URL маппинг

Секция определяется из OpenAPI-тега через tagToUrlSegment(). Особые адреса закреплены в OPERATION_OVERRIDES в lib/openapi/mapper.ts. Скрипт check-url-conflicts.ts (задача check-urls, входит в turbo check) считает адреса той же функцией generateUrlFromOperation и падает, если два метода попали на один адрес.

Поиск

FlexSearch с tokenize: 'forward'. Русский язык: синонимы (участники → members, users), стемминг (участников → участник), стоп-слова, action patterns (отправить → create/post).

Ссылки на API методы в тексте

[Список сотрудников](GET /users)
[Новое сообщение](POST /messages)

Ссылки резолвятся в реальные URL и рендерятся с method-badge.

Требования к методам (x-requirements)

Ограничения эндпоинтов описываются через @extension("x-requirements", ...) в TypeSpec.Попадают в OpenAPI YAML как x-requirements и рендерятся в UI как бейджи и в per-endpoint .md-файлах, а из scope и roles собираются права инструментов в MCP-манифесте.

Поля:

• scope — требуемый скоуп токена (например "messages:read"). null — метод отвечает на любой действующий токен и скоупа не требует. Метод без scope, без scope: null и без auth: false валит сборку MCP-манифеста, как и скоуп, которого нет в x-scope-roles
• roles — роли метода, если их меньше, чем у скоупа (подробно в docs/docs-conventions.md)
• plan — требуемый тариф (например "corporation")
• auth — false если авторизация не нужна

MDX компоненты

Новый компонент регистрируется в трёх местах: components/mdx/mdx-components.tsx, components/api/markdown-content.tsx и обработчик в lib/mdx-expander.ts, который превращает тег в Markdown для .md-версий и llms-full.txt. Без обработчика тег попадёт в них как есть. Сборку тогда остановит scripts/generate-llms.ts, если тег есть в его списке LEAK_TAGS, поэтому новый тег добавьте и туда. Подробности — в docs/docs-conventions.md.

<SchemaBlock name="MessageWebhookPayload" />
<ApiCodeExample operationId="SecurityOperations_getAuditEvents" />
<Info>Информация</Info>
<Warning>Предупреждение</Warning>
<Danger>Опасно</Danger>
<Steps><Step title="Шаг 1">Описание</Step></Steps>
<CardGroup><Card title="…" href="…" /></CardGroup>
<Limit title="Название" limit="~4" period="1 сек" entity="chat_id" />
<Prompts><Prompt ask="«Перескажи тред»">Что сделает агент</Prompt></Prompts>
<CliCommands />
<McpTools />
<Mermaid chart={`graph TD; A-->B;`} />

Просьбы к агенту и что он сделает показываются компонентом <Prompts>, а не таблицей.

Как добавить новый гайд

Создайте content/guides/{slug}.mdx (или content/guides/{category}/{slug}.mdx, content/api/{slug}.mdx) с frontmatter:

---
title: Название гайда
description: Краткое описание для SEO
---

Добавьте путь в lib/tabs-config.ts (страницу content/api/ — в API_GUIDE_PAGES там же) → гайд появится в навигации, поиске, llms.txt и получит .md-файл.

Обновление API (changelog)

Создайте файл content/updates/<ГГГГ-ММ-ДД>.md (один файл на дату) с frontmatter и markdown-телом:

---
date: "2025-12-01"
title: "Название обновления"
---

- [Новый метод](POST /messages)

Пока записи не больше 7 дней, у вкладки «Обновления» в шапке горит точка, а её дата на ленте обновлений выделена цветом. Попадает в RSS feed. Полные правила — docs/updates-format.md.

Кастомная схема для гайда

Создайте lib/schemas/guides/{Name}.json → используйте <SchemaBlock name="Name" />. Индексируется для поиска и попадает в llms-full.txt.

Настройки

• lib/display-config.ts — showSchemaExamples (по умолчанию false)
• redirects.ts — редиректы: по умолчанию permanent (308), с permanent: false временные (307)

Безопасность (next.config.ts)

HSTS (2 года, preload), X-Frame-Options: DENY, nosniff, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy и Content-Security-Policy (default-src 'self': внешние скрипты, стили, шрифты и запросы заблокированы, картинки разрешены с любого https). CORS разрешён для llms.txt, llms-full.txt, llms-en.txt, /{api,guides,updates}/llms.txt, *.md (в том числе skill.md), /.well-known/skills/*, /.well-known/agent-skills/*, /skills/*.zip, openapi.yaml, pachca.postman_collection.json.