atlassian-proxy

Локальный stdio MCP-прокси, который располагается перед размещённым Rovo MCP-сервером Atlassian (https://mcp.atlassian.com/v1/mcp) и урезает его для Claude Code.

Claude Code (stdio) -> index.js -> mcp-remote (subprocess, OAuth) -> https://mcp.atlassian.com/v1/mcp

Что он делает:

• Открывает только те инструменты, которые перечислены в ALLOWED_TOOLS в index.js (те, что реально используют jira-ops/jira-reviewer) — всё остальное вышестоящее скрыто из tools/list.

• Автоматически подставляет cloudId, contentFormat, responseContentFormat в каждый вызов и убирает эти параметры из схемы, которую видит Claude, так что Claude никогда не должен о них знать.

• Рекурсивно удаляет шумные ключи (avatarUrls, self, iconUrl, _links, expand, browseUrl, ...) из каждого результата инструмента перед возвратом.

Требования

• Node.js (любая версия, поддерживающая нативный ESM / type: "module").

• npx доступен в PATH (используется для запуска mcp-remote).

Related MCP server: JIRA MCP Server

Установка

Сначала проверьте, установлен ли Node.js — если да, и node_modules уже присутствует в этой папке, npm install не нужен:

node -v

Если это не сработало (Node не найден), сначала установите Node.js, затем:

cd C:\Users\Dz\oktanetest\atlassian-proxy
npm install

Это установит @modelcontextprotocol/sdk и mcp-remote из package.json.

Запуск в автономном режиме (ручной смоук-тест)

node index.js

Он говорит по MCP через stdio, поэтому прямой запуск просто блокирует ожидание клиента на stdin. При первом вызове любого инструмента Jira/Confluence он запускает npx -y mcp-remote https://mcp.atlassian.com/v1/mcp как дочерний процесс, который открывает окно браузера для OAuth-входа Atlassian. После авторизации mcp-remote кэширует токен, так что последующие запуски не требуют повторной аутентификации. [atlassian-proxy] ready в stderr означает, что он подключился к вышестоящему серверу и обслуживает отфильтрованный список инструментов.

Регистрация в Claude Code

Зарегистрируйте этот прокси под именем atlassian-proxy, а не atlassian — это предотвращает конфликт с реальным размещённым Atlassian/Rovo MCP-сервером, если тот также зарегистрирован под именем atlassian.

Добавьте его как stdio MCP-сервер для проекта, например, в конфиге Claude Code этого проекта (блок mcpServers):

{
  "atlassian-proxy": {
    "type": "stdio",
    "command": "node",
    "args": ["<path-to-atlassian-proxy>\\index.js"],
    "env": {}
  }
}

Если реальный MCP-сервер atlassian также зарегистрирован, отключите его (не удаляйте), чтобы активными были только отфильтрованные инструменты этого прокси: запустите /mcp в Claude Code, выберите сервер atlassian и выберите опцию отключения. Позже вы сможете снова включить его там, если вам понадобится полный, нефильтрованный набор инструментов вышестоящего сервера.

Перезапустите/переподключите Claude Code (или MCP-соединение) после регистрации, чтобы он подхватил новый сервер. Инструменты этого прокси появятся с префиксом atlassian-proxy (например, mcp__atlassian-proxy__getJiraIssue), уже ограниченные ALLOWED_TOOLS и лишённые cloudId/contentFormat/responseContentFormat.

Статистика экономии токенов

Поскольку Claude Code запускает этот прокси скрыто и его stderr не виден в чате, экономия записывается в файлы:

• logs/token-savings.log — JSONL, одна строка на событие tools/list/tools/call (tokensSavedIn, tokensSavedOut, нарастающие итоги).

• logs/stats-summary.txt — перезаписывается после каждого события с текущими нарастающими итогами.

Отслеживаются два числа (оба являются оценками — количество символов / 4, а не настоящий токенизатор, так как токенизатор Claude не подключён):

• Исключено из контекста Claude (tokensSavedIn): урезание списка инструментов (ALLOWED_TOOLS) плюс шум, удалённый из результатов инструментов (stripNoise).

• Claude не пришлось генерировать (tokensSavedOut): постоянные параметры (cloudId, contentFormat, responseContentFormat), которые прокси подставляет от имени Claude.

Чтобы наблюдать за этим в реальном времени, откройте отдельный терминал и выполните tail для файла сводки:

Get-Content logs\stats-summary.txt -Wait

Устранение неполадок

• Зависание без сообщения ready: npx -y mcp-remote ... скорее всего ожидает OAuth-поток в браузере — проверьте наличие окна/запроса браузера.

• Инструмент недоступен в Claude: убедитесь, что имя инструмента есть в ALLOWED_TOOLS в index.js; всё, что не перечислено, отфильтровывается из tools/list и отклоняется при tools/call.

Устаревшая/истёкшая аутентификация (401 Unauthorized или could not resolve cloudId from getAccessibleAtlassianResources)

Переподключение /mcp в Claude Code перезапускает только stdio-процесс node index.js — оно не принудительно выполняет повторную аутентификацию. Сам OAuth-токен находится уровнем ниже, кэшируется на диске дочерним процессом mcp-remote по пути ~/.mcp-auth/mcp-remote-<version>/<server-hash>_tokens.json, ключом является URL вышестоящего сервера. Если этот токен устарел (истёк, отозван или был уже устаревшим до перезапуска процесса node), каждый вызов инструмента завершается ошибкой 401/could not resolve cloudId, независимо от того, сколько раз вы переподключаетесь в Claude Code, потому что переподключение никогда не затрагивает этот кэш.

Полный рецепт, по порядку:

1. Очистите кэш: rm -rf ~/.mcp-auth (Windows: C:\Users\<you>\.mcp-auth). Это стирает кэшированную регистрацию клиента, PKCE-верификатор и токен для каждого сервера на базе mcp-remote на машине — безопасно, это чисто состояние OAuth-клиента, ничто другое от него не зависит.

2. Повторно аутентифицируйтесь автономно, вне Claude Code, в отдельном терминале:

   cd C:\Users\Dz\oktanetest\atlassian-proxy
   npx -y mcp-remote https://mcp.atlassian.com/v1/mcp --host 127.0.0.1

   Дайте этому выполниться на переднем плане (или в фоновой оболочке, за которой можно наблюдать) и завершите вход в браузере в своём темпе. Не пытайтесь повторно аутентифицироваться, сначала переподключая atlassian-proxy внутри Claude Code — таймаут установки соединения Claude Code конкурирует с интерактивным OAuth-потоком, поскольку main() в index.js не открывает свою сторону stdio, пока не разрешится всё подключение вышестоящего mcp-remote (включая ваши клики в браузере). Если Claude Code сдастся первым, он убьёт index.js и его дочерний mcp-remote на середине рукопожатия — браузер может всё ещё показывать "Authorization successful!", но обмен токеном будет прерван до записи tokens.json (у вас останутся только client_info.json/code_verifier.txt в ~/.mcp-auth, без токена — проверьте это, если так произошло). Запуск mcp-remote автономно сначала полностью устраняет эту гонку; как только он выведет Proxy established successfully (код выхода 0), токен безопасно кэширован.

3. Только после этого переподключите atlassian-proxy в Claude Code (/mcp). Он запускает тот же mcp-remote, находит теперь действительный кэшированный токен и подключается немедленно, без шага с браузером.

--host 127.0.0.1 в аргументах запуска index.js (не по умолчанию вышестоящего mcp-remote) обязателен на Windows: локальный OAuth-сервер обратного вызова mcp-remote привязывается только к 127.0.0.1, но его имя хоста по умолчанию для redirect_uri — localhost. На машине с Windows, где localhost сначала разрешается в ::1 (проверьте с помощью Resolve-DnsName localhost), перенаправление браузера после входа попадает на адрес, где ничего не слушает — страница обратного вызова показывает "Unable to connect", и код аутентификации остаётся неиспользованным. Не удаляйте этот флаг.

EADDRINUSE на порту обратного вызова (например, listen EADDRINUSE: 127.0.0.1:3736) после прерванной предыдущей попытки аутентификации: npx на Windows не всегда убивает всё дерево дочерних процессов, когда его родитель отменяется, поэтому предыдущий mcp-remote может остаться осиротевшим и продолжать удерживать порт. Найдите и убейте его перед повторной попыткой:

Get-NetTCPConnection -LocalPort <port> | Select-Object OwningProcess
Stop-Process -Id <pid> -Force