Freedcamp MCP Server

Сервер Model Context Protocol, который оборачивает REST API Freedcamp. Он позволяет любому MCP-совместимому LLM-клиенту (Claude Code, Claude Desktop и т. д.) управлять проектами, задачами, пользователями и комментариями Freedcamp с помощью естественного языка.

Возможности

• 17 инструментов, охватывающих проекты, задачи, пользователей, комментарии и проверку работоспособности

• Аутентификация HMAC-SHA1 — секретный ключ API никогда не покидает сервер; для каждого запроса отправляется только подписанный хеш

• Разрешение имен — передавайте имена пользователей, адреса электронной почты или названия проектов вместо необработанных числовых идентификаторов; сервер разрешает их автоматически с кэшированием на основе TTL

• Ограничение полей — запрашивайте только нужные поля с помощью точечной нотации (id,title,comments.created_ts) для уменьшения размера ответа

• Сопоставление меток статуса — принимаются понятные человеку строки, такие как "in progress" (в процессе), вместо числовых кодов

• Фильтрация ответов — внутренние поля API автоматически удаляются из ответов

• Корректное завершение работы — завершает выполнение текущих запросов перед выходом

• Повторные попытки + экспоненциальная задержка — повторные попытки при ошибках 429 и 5xx с экспоненциальной задержкой

• Без этапа сборки — запускает TypeScript напрямую через tsx

Related MCP server: toggl-mcp

Предварительные требования

• Node.js >= 18

• Учетная запись Freedcamp с учетными данными API (Настройки → API)

Установка

git clone https://github.com/mahrukh-n8n/freedcampMCP.git
cd freedcampMCP
npm install

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

Вариант A: файл .env

cp .env.example .env
# Edit .env with your Freedcamp API key and secret

Вариант B: настройки MCP для Claude Code

Файл .env не требуется — передайте учетные данные в виде переменных окружения:

claude mcp add freedcamp npx tsx /path/to/freedcampMCP/scripts/mcp-server.ts \
  -e FREEDCAMP_API_KEY=your_key \
  -e FREEDCAMP_API_SECRET=your_secret

Переменные окружения

Запуск

С помощью Claude Code (рекомендуется)

После добавления MCP-сервера с помощью claude mcp add просто начните диалог. Claude будет вызывать инструменты автоматически по мере необходимости.

С помощью MCP Inspector

npx @modelcontextprotocol/inspector npx tsx scripts/mcp-server.ts

Открывает интерфейс браузера, где можно вызвать каждый инструмент и изучить ответы.

Напрямую (stdio)

npx tsx scripts/mcp-server.ts

Сервер прослушивает stdin/stdout, используя транспорт MCP stdio. Хост-процесс (Claude Code, Claude Desktop) управляет его жизненным циклом.

Инструменты

Здоровье (Health)

Проекты

Задачи

Пользователи

Комментарии

Разрешение имен

Большинство параметров ID принимают имена, адреса электронной почты или числовые идентификаторы. Примеры:

• project_id: "Marketing" — разрешается в числовой ID проекта

• assigned_to_id: "alice@example.com" — разрешается в числовой ID пользователя

• assigned_to_id: ["Alice", 42] — принимаются смешанные списки

Результаты разрешения кэшируются с настраиваемым TTL (CACHE_TTL_MS).

Сопоставление статусов

Статус задачи принимает как числовые коды, так и строковые метки:

Пример: status: "in progress" эквивалентно status: 1.

Ограничение полей

Все инструменты списка и получения принимают параметр fields с путями в точечной нотации:

fields="id,title,priority,comments.created_ts"

Это уменьшает размер ответа и фокусирует LLM на релевантных данных. Вложенные массивы сохраняются — comments.created_ts для [{created_ts: 1}] дает [{created_ts: 1}], а не плоский список.

Константы App ID (для комментариев)

Аутентификация

Сервер использует аутентификацию HMAC-SHA1. При каждом запросе:

1. Генерируется метка времени Unix

2. Вычисляется хеш: HMAC-SHA1(secret, apiKey + timestamp)

3. Параметры аутентификации отправляются в строке запроса: ?api_key=...&timestamp=...&hash=...

Секретный ключ никогда не передается по сети. При загрузке сервер проверяет учетные данные с помощью GET /api_key/check.

Коды ошибок

Разработка

# Type check
npx tsc --noEmit

# Run tests
npx vitest run

# Watch mode
npx vitest

# Run server in dev mode
npm run dev

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

Набор тестов использует Vitest с имитацией ответов API:

npx vitest run           # Single run
npx vitest               # Watch mode
npx vitest --coverage    # With coverage

Структура проекта

scripts/mcp-server.ts              Entry point
src/lib/freedcamp/
  api-client.ts                    HTTP client with HMAC auth, retry, filtering
  register-tools.ts                Wire all tools to the MCP registry
  auth/hmac.ts                     HMAC-SHA1 computation
  auth/hmac-validator.ts           Boot-time credential validation
  tools/
    health.ts                      health.check
    projects.ts                    project.list/get/create/update
    tasks.ts                       task.list/get/create/update/delete/assign
    users.ts                       user.list/get/current/create/update_current
    comments.ts                    comment.add/update/delete
  utils/
    name-resolver.ts               Name/email → ID resolution with caching
    response-filter.ts             Strip internal fields from API responses
    field-limiter.ts               Dot-notation field extraction
    date-utils.ts                  Date validation and formatting
    resolution-cache.ts            TTL-based LRU cache
    logger.ts                      Structured logging with verbose mode
    validation.ts                  Input validation helpers
src/modules/mcp/
  registry/tool-registry.ts        MCP tool registry
  services/create-mcp-server.ts    MCP server factory
  services/stdio-transport.ts      Stdio transport
  types.ts                         MCP result types
  utils/serialize.ts               Result envelope helpers (dataResult, commitResult, etc.)

Лицензия

MIT