atlassian-proxy

本地 stdio MCP 代理，位于 Atlassian 托管的 Rovo MCP 服务器（https://mcp.atlassian.com/v1/mcp）之前，并针对 Claude Code 进行精简。

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

它的作用：

• 仅暴露 index.js 中 ALLOWED_TOOLS 列出的工具（jira-ops/jira-reviewer 实际使用的那些）——上游的其他所有内容都从 tools/list 中隐藏。

• 自动将 cloudId、contentFormat、responseContentFormat 注入到每次调用中，并从 Claude 看到的 schema 中移除这些参数，因此 Claude 无需知道它们。

• 在返回每个工具结果之前，递归地移除嘈杂的键（avatarUrls、self、iconUrl、_links、expand、browseUrl 等）。

要求

• Node.js（任何支持原生 ESM / type: "module" 的版本）。

• PATH 中可用的 npx（用于生成 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

这会从 package.json 安装 @modelcontextprotocol/sdk 和 mcp-remote。

独立运行（手动冒烟测试）

node index.js

它通过 stdio 使用 MCP 协议，因此直接运行它只会阻塞等待 stdin 上的客户端。在首次调用任何 Jira/Confluence 工具时，它会生成 npx -y mcp-remote https://mcp.atlassian.com/v1/mcp 作为子进程，该进程会打开浏览器窗口进行 Atlassian OAuth 登录。一旦授权，mcp-remote 会缓存令牌，因此后续运行无需重新认证。stderr 上的 [atlassian-proxy] ready 表示它已连接到上游并正在提供过滤后的工具列表。

注册到 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": {}
  }
}

如果真正的 atlassian MCP 服务器也已注册，请禁用它（不要移除），以便仅此代理的过滤工具处于活动状态：在 Claude Code 中运行 /mcp，选择 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）：代理代表 Claude 注入的常量参数（cloudId、contentFormat、responseContentFormat）。

要实时查看，请打开一个单独的终端并跟踪摘要文件：

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

故障排除

• 挂起且没有 ready 消息：npx -y mcp-remote ... 可能正在等待 OAuth 浏览器流程——检查是否有浏览器窗口/提示。

• Claude 中工具不可用：确认工具名称在 index.js 的 ALLOWED_TOOLS 中；未列出的任何内容都会从 tools/list 中过滤掉，并在 tools/call 中被拒绝。

过期/失效的认证（401 Unauthorized，或 could not resolve cloudId from getAccessibleAtlassianResources）

Claude Code 的 /mcp 重新连接只会重启 node index.js stdio 进程——它不会强制重新认证。实际的 OAuth 令牌位于下一层，由 mcp-remote 子进程缓存在磁盘上，路径为 ~/.mcp-auth/mcp-remote-<version>/<server-hash>_tokens.json，以上游服务器 URL 为键。如果该令牌已过期（过期、被撤销，或在 node 进程重启之前就已过期），无论你在 Claude Code 中重新连接多少次，每次工具调用都会以 401/could not resolve cloudId 失败，因为重新连接永远不会触及该缓存。

完整步骤，按顺序：

1. 清除缓存：rm -rf ~/.mcp-auth（Windows：C:\Users\<you>\.mcp-auth）。这会清除机器上每个由 mcp-remote 支持的服务器缓存的客户端注册、PKCE 验证器和令牌——安全，它纯粹是 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

   让它在前台（或你可以观察的后台 shell）运行，并按自己的节奏完成浏览器登录。不要先尝试在 Claude Code 中重新连接 atlassian-proxy 来重新认证——Claude Code 自身的连接设置超时与交互式 OAuth 流程竞争，因为 index.js 的 main() 在完整的上游 mcp-remote 连接（包括你点击浏览器）解析之前不会打开自己的 stdio 端。如果 Claude Code 先放弃，它会在握手过程中杀死 index.js 及其 mcp-remote 子进程——浏览器可能仍显示“Authorization successful!”，但令牌交换在 tokens.json 写入之前被切断（你只剩下 ~/.mcp-auth 中的 client_info.json/code_verifier.txt，没有令牌——如果发生这种情况，请检查）。先独立运行 mcp-remote 可以完全消除这种竞争；一旦它打印 Proxy established successfully（退出代码 0），令牌就已安全缓存。

3. 然后才在 Claude Code（/mcp）中重新连接 atlassian-proxy。它会生成相同的 mcp-remote，找到现在有效的缓存令牌，并立即连接，无需浏览器步骤。

--host 127.0.0.1 在 index.js 的 spawn 参数中（不是上游 mcp-remote 默认值）在 Windows 上是必需的：mcp-remote 的本地 OAuth 回调服务器仅绑定 127.0.0.1，但其默认的 redirect_uri 主机名是 localhost。在 localhost 首先解析为 ::1 的 Windows 机器上（用 Resolve-DnsName localhost 检查），浏览器登录后的重定向会命中一个没有监听的地址——回调页面显示“Unable to connect”，认证代码被搁置。不要移除此标志。

回调端口上的 EADDRINUSE（例如 listen EADDRINUSE: 127.0.0.1:3736）在之前的认证尝试被中断后：Windows 上的 npx 在其父进程被取消时并不总是杀死完整的子进程树，因此之前的 mcp-remote 可能成为孤儿进程，仍然占用端口。在重试之前找到并杀死它：

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