WEEEK MCP

MCP-сервер для WEEEK Public API v1: задачи, проекты, доски, теги, кастомные поля, тайм-трекинг и CRM.

Сервер строит инструменты из официальной OpenAPI-спецификации WEEEK, поэтому названия и параметры эндпоинтов не переписаны вручную.

Возможности

• Workspace: информация о рабочем пространстве, участники, теги.
• Task Manager: portfolios, projects, boards, board columns, tasks, watchers, assignees, timers, time entries, attachments, custom fields.
• CRM: funnels, statuses, deals, organizations, contacts, currencies, связи между сущностями, custom fields.
• Генератор npm run update:openapi подтягивает свежую спецификацию из developers.weeek.net.

Установка

git clone https://github.com/maxwellviksna-stack/weeek-mcp.git
cd weeek-mcp
npm install
npm run build

Создайте токен в настройках workspace WEEEK, раздел API, и передайте его в окружение:

export WEEEK_API_TOKEN="your-token"

WEEEK_TOKEN тоже поддерживается, если такое имя уже используется в вашей конфигурации.

Подключение

Claude Desktop

{
  "mcpServers": {
    "weeek": {
      "command": "node",
      "args": ["/absolute/path/to/weeek-mcp/dist/server.js"],
      "env": {
        "WEEEK_API_TOKEN": "your-token"
      }
    }
  }
}

Локальный запуск

WEEEK_API_TOKEN="your-token" npm start

Для разработки:

WEEEK_API_TOKEN="your-token" npm run dev

Инструменты

Все API-операции публикуются как отдельные MCP tools с префиксом weeek_.

Примеры:

• weeek_get_workspace_info
• weeek_get_project_list
• weeek_create_task
• weeek_get_tasks
• weeek_complete_task
• weeek_get_all_deals
• weeek_create_a_contact

Есть служебный инструмент:

• weeek_list_operations — поиск по доступным операциям, тегу или тексту.

Формат аргументов у сгенерированных инструментов одинаковый:

{
  "path": { "id": 123 },
  "query": { "search": "release" },
  "body": { "title": "Prepare release notes" }
}

Для загрузки файлов используется files:

{
  "path": { "task_id": 123 },
  "files": [
    {
      "path": "/absolute/path/to/file.pdf",
      "fieldName": "files[]"
    }
  ]
}

Конфигурация

Переменная	По умолчанию	Описание
WEEEK_API_TOKEN	обязательна	Bearer token из настроек workspace
WEEEK_TOKEN	optional	Алиас для WEEEK_API_TOKEN
WEEEK_BASE_URL	https://api.weeek.net/public/v1	Базовый URL API
WEEEK_TIMEOUT_MS	30000	Таймаут запроса

Обновление API

npm run update:openapi
npm run build

Генератор берет текущий bundle документации WEEEK, находит модуль weeek.yaml-*.js, импортирует OpenAPI-объект и пересобирает src/generated/weeek-openapi.ts.

Проверка перед релизом

npm run update:openapi
npm run check
npm run build
npm pack --dry-run

Для проверки на реальном workspace:

WEEEK_API_TOKEN="your-token" npm run smoke:live

Smoke-тест поднимает MCP-сервер через stdio, проверяет список tools, делает read/write-запросы к Task Manager и CRM, а затем удаляет временные сущности с префиксом mcp-smoke-*.