atlassian-proxy

Proxy local stdio MCP que se sitúa delante del servidor MCP Rovo alojado de Atlassian (https://mcp.atlassian.com/v1/mcp) y lo simplifica para Claude Code.

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

Lo que hace:

• Expone únicamente las herramientas incluidas en ALLOWED_TOOLS en index.js (las que jira-ops/jira-reviewer usan realmente); todo lo demás de upstream queda oculto en tools/list.

• Inyecta automáticamente cloudId, contentFormat, responseContentFormat en cada llamada y elimina esos parámetros del esquema que ve Claude, para que Claude nunca tenga que conocerlos.

• Elimina recursivamente las claves ruidosas (avatarUrls, self, iconUrl, _links, expand, browseUrl, ...) de cada resultado de herramienta antes de devolverlo.

Requisitos

• Node.js (cualquier versión compatible con ESM nativo / type: "module").

• npx disponible en PATH (se usa para lanzar mcp-remote).

Related MCP server: JIRA MCP Server

Instalación

Comprueba primero si Node.js ya está instalado; si lo está y node_modules ya existe en esta carpeta, npm install no es necesario:

node -v

Si eso falla (no se encuentra Node), instala Node.js primero y después:

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

Esto instala @modelcontextprotocol/sdk y mcp-remote desde package.json.

Ejecución independiente (prueba de humo manual)

node index.js

Habla MCP sobre stdio, así que ejecutarlo directamente solo queda bloqueado esperando a un cliente en stdin. En la primera llamada a cualquier herramienta de Jira/Confluence lanza npx -y mcp-remote https://mcp.atlassian.com/v1/mcp como proceso hijo, que abre una ventana del navegador para iniciar sesión con Atlassian OAuth. Una vez autorizado, mcp-remote guarda el token en caché, así que en ejecuciones posteriores no hace falta volver a autenticarse. [atlassian-proxy] ready en stderr significa que se ha conectado con upstream y está sirviendo la lista de herramientas filtrada.

Registro en Claude Code

Registra este proxy con el nombre atlassian-proxy, no con atlassian; así no entrará en conflicto con el servidor MCP real alojado de Atlassian/Rovo si ese otro también está registrado como atlassian.

Añádelo como servidor MCP stdio del proyecto, por ejemplo en la configuración de Claude Code de ese proyecto (bloque mcpServers):

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

Si el servidor MCP real atlassian también está registrado, desactívalo (no lo elimines) para que solo estén activas las herramientas filtradas de este proxy: ejecuta /mcp en Claude Code, selecciona el servidor atlassian y elige la opción de desactivar. Vuelve a activarlo ahí cuando necesites recuperar el conjunto completo de herramientas de upstream sin filtrar.

Reinicia o vuelve a conectar Claude Code (o la conexión MCP) después de registrarlo para que detecte el nuevo servidor. Las herramientas de este proxy aparecerán con el prefijo atlassian-proxy (p. ej. mcp__atlassian-proxy__getJiraIssue), ya limitadas a ALLOWED_TOOLS y sin cloudId/contentFormat/responseContentFormat.

Estadísticas de ahorro de tokens

Como Claude Code ejecuta este proxy oculto y su stderr no es visible en el chat, los ahorros se escriben en archivos:

• logs/token-savings.log — JSONL, una línea por evento de tools/list/tools/call (tokensSavedIn, tokensSavedOut, totales acumulados).

• logs/stats-summary.txt — se sobrescribe tras cada evento con los totales acumulados actuales.

Se controlan dos cifras (ambas son estimaciones — número de caracteres / 4, no un tokenizador real, porque no hay ningún tokenizador de Claude conectado):

• Lo que no ha llegado al contexto de Claude (tokensSavedIn): el recorte de la lista de herramientas (ALLOWED_TOOLS) más el ruido eliminado de los resultados de herramientas (stripNoise).

• Lo que Claude no ha tenido que generar (tokensSavedOut): los parámetros constantes (cloudId, contentFormat, responseContentFormat) que el proxy inyecta en nombre de Claude.

Para verlo en directo, abre una terminal aparte y haz tail al archivo de resumen:

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

Solución de problemas

• Se cuelga sin mensaje ready: npx -y mcp-remote ... está probablemente esperando el flujo de navegador de OAuth; comprueba si hay una ventana o aviso del navegador.

• La herramienta no está disponible en Claude: confirma que el nombre de la herramienta está en ALLOWED_TOOLS en index.js; cualquier cosa no listada se filtra de tools/list y se rechaza en tools/call.

Autenticación obsoleta o caducada (401 Unauthorized, o could not resolve cloudId from getAccessibleAtlassianResources)

La reconexión con /mcp de Claude Code solo reinicia el proceso stdio node index.js; no fuerza la reautenticación. El token OAuth real está un nivel más abajo, guardado en disco por el proceso hijo mcp-remote en ~/.mcp-auth/mcp-remote-<version>_tokens.json, clasificado por la URL del servidor upstream. Si ese token está caducado (expirado, revocado o ya estaba caducado antes de que el propio proceso node reiniciara), cualquier llamada falla con 401/couldDeteccio cloudId sin importar cuántas veces reconectes en Claude Code, porque reconectar nunca toca esa caché.

Receta completa, en orden:

1. Vacía la caché: rm -rf ~/.mcp-auth (en Windows: C:\Users\<you>\.mcp-auth). Esto borra el registro de cliente, el verificador PKCE y el token de todos los servidores respaldados por mcp-remote en la máquina; es seguro, porque es solo estado de cliente OAuth y nada más depende de él.

2. Vuelve a autenticarte de forma independiente, sin Claude Code, en su propia terminal:

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

   Déjalo corriendo en primer plano (o en un shell de fondo que puedas vigilar) y completa el inicio de sesión el navegador a tu ritmo. No intentes reautenticarte reconectando atlassian-proxy dentro de Claude Code primero: el límite de tiempo para establecer la conexión de Claude Code compite con el flujo OAuth interactivo, ya que main() de index.js no abre su propio lado de stdio hasta que se ha resuelto toda la conexión mcp-remote con upstream (incluido que hagas clic en el navegador). Si Claude Code se rinde antes, mata index.js y a su hijo mcp-remote en plena negociación: el navegador puede mostrar "Authorization successful", pero el intercambio de tokens el corte antes de que se escriba tokens.json (te queda solo client_info.json/code_verifier.txt en ~/.mcp-auth, sin token; compruébalo si ocurre). Ejecutar mcp-remote solo antes elimina esa comprotación por completo; una vez que imprima Proxy established successfully (código de salida 0), el token queda correctamente en caché.

3. Solo después reconecta atlassian-proxy en Claude Code (/mcp). Lanza el mismo mcp-remote, encuentra el token en caché ahora válido y se conecta inmediatamente, sin paso por el navegador.

--host 127.0.0.1 in dalam argumentos de spawn de index.js (y el valor predeterminado de mcp-remote upstream no) es obligatorio en Windows: el servidor local de callback de OAuth de mcp-remote solo se vincula a 127.0.0.1, pero su hostname redirect_uri predeterminado es localhost. En una máquina Windows donde localhost resuelva primero como ::1 (compruébalo con Resolve-DnsName localhost), el redireccionamiento del navegador tras el login apunta a una dirección en la que no hay nada escuchado; la página de callback muestra "Unable to connect" y el código de autenticación se queda atrapado. No elimines esta opción.

EADDRINUSE en el puerto del callback (p. ej. listen EADDRINUSE:127.0.0.1:3736) después de dejar a medias un intento de autenticación anterior: npx en Windows no siempre los procesos hijos de su árbol cuando se cancela el proceso padre, así que un mcp-remote anterior puede quedar huérfano y seguir ocupando el puerto. Encontrar sino y Matalo antes de reintentar:

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