# 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`.

## Установка

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

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

```bash
export WEEEK_API_TOKEN="your-token"
```

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

## Подключение

### Claude Desktop

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

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

```bash
WEEEK_API_TOKEN="your-token" npm start
```

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

```bash
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` — поиск по доступным операциям, тегу или тексту.

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

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

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

```json
{
  "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

```bash
npm run update:openapi
npm run build
```

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

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

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

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

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

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