Backlog Remote MCP Server

Backlog для удалённого MCP-сервера (Model Context Protocol). Можно развернуть либо на Cloudflare Workers, либо на AWS.

English | 日本語

Возможности

• Multi-space — обслуживание нескольких пространств (spaces) Backlog с одного сервера

• Режим только для чтения — пометка общего пространства как readOnly отклоняет любые записывающие вызовы API

• OAuth 2.1 + PKCE — поддержка Dynamic Client Registration (DCR), поэтому MCP-клиенты подключаются напрямую

• Список разрешённых email — ограничение круга пользователей сервера

• Два окружения выполнения — одна и та же бизнес-логика работает на Cloudflare или AWS

Related MCP server: backlog-mcp-server

Выбор варианта развёртывания

Инструменты и их поведение в обоих вариантах идентичны.

Оценочная стоимость

Примечание Это лишь ориентировочные цифры. Фактические расходы зависят от региона, объёмов использования и изменений в тарифах. Для реальной оценки пользуйтесь официальными калькуляторами.

• Cloudflare Zero Trust Pricing — цены

• Cloudflare Workers Pricing — цены

• AWS Pricing Calculator — калькулятор AWS

Допущения

Личное использование или небольшая команда.

Фиксированные расходы (даже при отсутствии нагрузки)

Основные фиксированные расходы на AWS — практически только Secrets Manager, который тарифицируется за каждый секрет в месяц, независимо от того, используется ли он. Cloudflare не имеет фиксированных расходов, поскольку секреты Workers бесплатны.

Что оплачивается по факту

| Запросы | Workers | Lambda + API Gateway | | Хранение состояний | Durable Objects + KV | DynamoDB | | Логи | Workers Logs | CloudWatch Logs |

При предполагаемом объёме (~3 000 запросов/месяц) где оба варианта остаются в пределах бесплатных лимитов. У HTTP API API Gateway нет постоянного бесплатного тарифа, поэтому AWS начисляет небольшую сумму (примерно $1 за миллион запросов).

О порогах, которые стоит знать

Cloudflare — лимит 50 пользователей в Zero Trust

Zero Trust (Access) бесплатен для групп до 50 пользователей. Дальше требуется переход на платный тариф с тарификацией за каждого пользователя в месяц. Именно эти расходы растут вместе с числом сотрудников.

Cloudflare — лимиты бесплатного тарифа Workers

Этот проект использует Durable Objects на базе SQLite, которые доступны на бесплатном тарифе Workers. Бесплатный тариф ограничивает суточное число запросов и другие параметры использования, а при превышении лимита возвращаются ошибки. Для постоянной нагрузки стоит рассмотреть платный тариф Workers (от $5/мес).

AWS — бесплатный тариф Lambda бессрочен

Lambda включает бессрочный бесплатный тариф: 1 миллион запросов и 400 000 ГБ-секунд в месяц. API Gateway и Secrets Manager не имеют бессрочного бесплатного тарифа.

AWS — CloudWatch Logs

Логи оплачиваются по объёму принятых данных. В этом шаблоне срок хранения задаётся явно через LogRetentionDays (по умолчанию 30), поэтому логи не копятся бесконечно.

Сводка

Для небольших команд Cloudflare дешевле и не имеет фиксированных расходов. AWS несёт фиксированные расходы на Secrets Manager, но это оправдано, если вы хотите вписаться в существующую инфраструктуру AWS или управлять доступом через IAM.

Настройка

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

Node.js версии 20 или более поздняя.

git clone <this-repo>
cd backlog-remote-mcp-server
npm install

Дополнительные инструменты зависят от выбранного варианта развёртывания:

Порядок действий

1. Ключи API Backlog и настройка пространства — общие для обеих платформ

2. Выберите поставщика учётных записей (identity provider)

   • Google Cloud

   • Microsoft Entra ID

3. Выберите вариант развёртывания

   • Cloudflare Workers

   • AWS

Если что-то пошло не так

Раздел по устранению неполадок находится в конце каждого руководства по развёртыванию.

• Cloudflare

• AWS

Архитектура

MCP client (Claude, Kiro, Cursor, ...)
    ↓ Streamable HTTP + OAuth
Runtime (Cloudflare Workers or AWS Lambda)
    ↓ Upstream IdP (Cloudflare Access or Amazon Cognito)
    ↓ Email allowlist check
    ↓ Backlog API key routing
Backlog space A / B / C ...

Структура каталогов

Бизнес-логика отделена от привязки к среде выполнения.

src/
  core/                    Runtime-independent
    backlog-client.ts      Backlog API client (including the readOnly guard)
    tools/                 40 MCP tools
    create-server.ts       MCP server assembly and authorization
  platforms/
    cloudflare/            Cloudflare Workers wiring
    aws/                   AWS Lambda wiring
infra/
  aws/                     SAM template and parameters

src/coreзависит только от @modelcontextprotocol/sdk и zod и не ссылается на API среды выполнения. Добавление новой платформы — это добавление адаптера в src/platforms/ с повторным использованием тех же реализаций инструментов.

Подключение MCP-клиентов

Claude Desktop / Kiro / Cursor (через прокси mcp-remote)

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<MCP_HOSTNAME>/mcp"
      ]
    }
  }
}

При первом подключении для аутентификации открывается окно браузера.

MCP Inspector (для тестирования)

npx @modelcontextprotocol/inspector@latest

Введите https://<MCP_HOSTNAME>/mcp в инспекторе и завершите OAuth-проход через OAuth Settings (настройки OAuth).

Использование

Указание пространства

Все инструменты принимают необязательный параметр space:

# Use default space
"Show me the issues for PROJECT-KEY"

# Specify a particular space
"List projects in the PERSONAL space"
→ space: "PERSONAL"

Примеры

# List configured spaces
"What Backlog spaces are available?" → list_spaces

# List projects
"Show COMPANY_A projects" → get_project_list(space: "COMPANY_A")

# Create an issue
"Create a new bug issue in PROJECT-KEY" → add_issue(...)

# List pull requests
"Show open PRs in repo-name" → get_pull_requests(...)

Доступные инструменты

add_*, update_* и delete_* — операции, изменяющие данные. Вызов их для пространства с readOnly: true отклоняется ещё до отправки запроса к Backlog API. Через list_spaces можно увидеть статус readOnly каждого пространства.

Безопасность

• Аутентификация: Cloudflare Access → Google / Microsoft Entra ID. Весь процесс OAuth управляется Cloudflare

• Авторизация: ALLOWED_EMAILS задаёт список разрешённых адресов на уровне пользовательского уровня

• Двойная проверка обнаружения: политика доступа (на стороне Cloudflare) + список разрешённых внутри приложения (на стороне Worker)

• Защита API-ключей: ключи API Backlog хранятся в Cloudflare Secrets и никогда не передаются клиентам

• PKCE + CSRF: OAuth защищается PKCE (S256) и CSRF-токенами

• Согласие клиента: Dynamic Client Registration открыта для всех, поэтому авторизация требует экрана согласия, где указан клиент и его redirect-цель, а подтверждение требует подтверждения CSRF-защиты. Одобренные заявки привязаны к паре client_id + redirect_uri, поэтому повторная регистрация с другим redirect_uri не наследует предыдущее согласие

• Защита от записи: пространства с readOnly: true отклоняют все записи, кроме GET. Проверка находится в слое вызовов API в src/core/backlog-client.ts, поэтому она не зависит от отдельных инструментов

• Изоляция конфигурации: все значения окружения хранятся в .dev.vars (не отслеживаются). В репозитории есть только заполнители.

Эксплуатационные заметки

• ALLOWED_EMAILS — фактическая граница авторизации для этого сервера. Перед Worker нет приложения Access на уровне зоны

• npm run deploy перезаписывает production-секреты значениями из .dev.vars. Если локально и в production нужны разные значения, используйте deploy:no-secrets для обычных развёртываний и явно отправляйте секреты через secrets:push.

• Ключ Backend API несёт все права своего владельца. Для пространств, где запись не нужна, используйте ключ только для чтения и укажите readOnly: true.

Локальная разра разработка

Локальные запуски используют сборку Cloudflare Workers (wrangler dev). Поскольку бизнес-логика находится в src/core, всё, что проверяется здесь, касается и развёртывания на AWS.

cp .dev.vars.example .dev.vars   # fill in your values
npm run dev
# Server starts at http://localhost:8788/mcp

wrangler dev локально эмулирует KV и Durable Objects, поэтому не затрагивает реальные ресурсы Cloudflare.

Проверка настройки

Запустите полную проверку от OAuth до вызова инструмента одной командой:

npm run check:local

Он выполняется автоматически, при этом часть процесса открывается браузер для входа: ...

1. Получить метаданные сервера авторизации

2. Динамическая регистрация клиента

3. Подтвердить в браузере → вход в IdP

4. Обмен токена с PKCE

5. initialize / tools/list

6. Вызвать get_space и показать реальный ответ от Backlog

Если tools/list возвращает только access_denied, значит, email, с которым вы вошли, отсутствует в списке разрешённых.

Это также работает с развёрнутым endpoint:

npm run check:local -- --base https://your-deployed-host

Работа по HTTPS

Используйте это, когда IdP не принимает URL перенаправления http://.

npm run dev:https
# Server starts at https://localhost:8788/mcp (self-signed certificate)

Проверка типов и тесты

Типы разделены по платформам, поэтому неправильное использование глобала Workers в коде AWS (или наоборот) является ошибкой типов.

npm run type-check   # both tsconfig.cloudflare.json and tsconfig.aws.json
npm test             # runs all suites below

Ни один из них не обращается к внешним сервисам — DynamoDB и вышестоящий IdP заменены заглушками.

Файлы конфигурации

См. руководства по развёртыванию, чтобы узнать, как их заполнить.

Лицензия

MIT