atlassian-proxy

Atlassian의 호스팅 Rovo MCP 서버(https://mcp.atlassian.com/v1/mcp) 앞에 위치하는 로컬 stdio 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가 보는 스키마에서 해당 매개변수를 제거하여 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이 아닌 atlassian-proxy라는 이름으로 등록하세요 — 실제 호스팅 Atlassian/Rovo MCP 서버가 atlassian으로도 등록되어 있는 경우 충돌을 방지합니다.

프로젝트의 Claude Code 구성(mcpServers 블록)에 stdio MCP 서버로 추가하세요:

{
  "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).

실시간으로 보려면 별도의 터미널을 열고 요약 파일을 tail하세요:

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

   포그라운드(또는 볼 수 있는 백그라운드 셸)에서 실행하고 브라우저 로그인을 원하는 속도로 완료하세요. 먼저 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에서 atlassian-proxy를 재연결하세요(/mcp). 동일한 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