jira-alerts-mcp

Jira Service Management Operations REST API용 MCP 서버 — 알림(alerts) 및 온콜(on-call) 기능을 제공합니다.

왜 필요한가

알림은 작업 항목(work item)이 아닙니다. 알림은 /jsm/ops/api라는 별도의 API(리호스팅된 Opsgenie 표면) 뒤에 있으며, 고유한 스코프, 고유한 ID 형식, 고유한 비동기 쓰기 의미론을 가집니다. MCP Registry에는 30개의 Jira 서버가 등록되어 있는데, 그 모두가 작업 항목만 다룹니다. 그중 어느 것도 지금 당신에게 페이지(paging)를 보내는 대상을 알려주지 못합니다.

공식 Atlassian MCP 서버도 이 격차를 메우지 못합니다. atlassian/atlassian-mcp-server는 Jira, Confluence, Jira Service Management 요청, Bitbucket, Compass 및 Teamwork Graph를 다룹니다. 알림, 일정 또는 온콜을 위한 도구는 없습니다. 또한 호스팅된 폐쇄형 서버이므로 — 저장소에는 핸들러가 아닌 매니페스트와 스킬만 들어 있습니다 — 이 격차는 기여로 해결할 수 있는 것이 아니라 Atlassian이 해결해야 할 문제입니다.

실제로 존재하는 Opsgenie MCP 서버들은 종료일이 정해진 API를 사용합니다. giantswarm/mcp-opsgenie, burakdirin/opsgenie-mcp-server, daviddykeuk/opsgenie-mcp는 모두 GenieKey로 api.opsgenie.com을 호출합니다. Opsgenie는 2025년 6월 4일 판매 종료, 2027년 4월 5일 서비스 종료되었으며, 그 시점부터 해당 REST API는 응답을 중단합니다. 해당 기능은 Jira Service Management로 이전되었습니다.

이 서버는 그 기능을 대체하는 표면을 대상으로 합니다: OAuth 또는 Atlassian API 토큰을 사용하는 api.atlassian.com/jsm/ops/api/{cloudId}. 알림 검색, 메모 및 활동 타임라인 읽기, 확인(acknowledge) / 종료(close) / 주석(annotate) / 응답자 추가, 그리고 현재 및 다음 온콜 담당자 조회를 지원합니다.

Related MCP server: Jira & Confluence MCP Server

호환성

JSM Operations가 있는 Atlassian Cloud 테넌트 — 즉, 독립형 Opsgenie에서 이미 마이그레이션했거나 병합 이후에 프로비저닝된 사이트 — 를 대상으로 합니다. 팀이 여전히 app.opsgenie.com에 로그인하고 GenieKey로 인증한다면, 이 서버는 데이터에 접근할 수 없습니다. 위에 나열된 Opsgenie 서버 중 하나가 2027년까지는 그 역할을 할 수 있습니다.

기본 URL: https://api.atlassian.com/jsm/ops/api/{cloudId}/v1

도구

의도적으로 구현하지 않은 것: DELETE /v1/alerts/{id} 및 알림 생성. 알림 삭제는 실행 취소가 없는 감사 기록을 파괴하며, 알림 생성은 대화형 에이전트가 아닌 통합 API(/jsm/ops/integration/v2/alerts)와 통합 키에 속합니다. 구체적인 필요가 있다면 이슈를 열어 주세요.

도구 설명에 인코딩된 세 가지 API 동작

이것들은 순진한 통합을 조용히 깨뜨리는 것들이므로, 모델이 실제로 읽을 도구 설명에 명시되어 있습니다:

1. 쓰기는 비동기입니다. 모든 변경 엔드포인트는 즉시 { result, requestId, took }를 반환하고 변경 사항을 대역 외로 적용합니다. 알림을 확인(ack)한 직후 다시 읽으면 여전히 미확인 상태로 보이는 경우가 많습니다. jsm_get_request_status가 올바른 검증 경로이며, 각 쓰기 도구가 이를 가리킵니다.

2. tinyId는 ID가 아닙니다. JSM UI의 짧은 숫자(#4821)는 /v1/alerts/{id}에서 거부되며, 전체 uuid-timestamp ID만 허용합니다. 별칭은 완전히 다른 엔드포인트(/v1/alerts/alias?alias=)가 필요합니다. 스키마 설명과 404 핸들러 모두 이를 명시적으로 언급하므로, 모델은 같은 호출을 재시도하는 대신 스스로 수정합니다.

3. 검색 창은 20,000으로 제한됩니다. offset + limit는 그 아래에 있어야 합니다. jsm_list_alerts는 더 깊은 페이지네이션을 로컬에서 거부하며, 모델에게 쿼리를 좁히라고 알리는 메시지를 반환합니다. 보장된 400에 왕복을 낭비하지 않도록 하기 위함입니다.

설정

Node ≥ 22가 필요합니다.

git clone https://github.com/rrvrs/jira-alerts-mcp.git
cd jira-alerts-mcp
npm install
npm run build

구성

참고용으로 .env.example을 복사하세요. 서버는 자체적으로 .env를 읽지 않습니다 — MCP 서버는 클라이언트가 시작하며, 환경은 클라이언트가 소유합니다. 파일을 클라이언트의 env 블록에 대한 체크리스트로 사용하거나, 로컬 개발에서는 set -a; source .env; set +a를 사용하세요.

자격 증명은 시작 시 검증되므로, 잘못된 구성은 첫 도구 호출이 아닌 즉시 실행 가능한 메시지로 실패합니다.

클라우드 ID 찾기. 로그인한 상태에서 https://<your-site>.atlassian.net/_edgeAuth/tenantInfo를 열거나, 토큰으로 GET https://api.atlassian.com/oauth/token/accessible-resources를 호출하세요.

필요한 스코프. 읽기 도구는 read:ops-alert:jira-service-management가 필요하고, 쓰기 도구는 write:ops-alert:jira-service-management가 필요합니다. 읽기 스코프만 부여하는 것도 지원되는 구성입니다 — 쓰기 도구는 누락된 스코프를 명시하는 403으로 실패합니다.

계정에는 관련 팀에 대한 JSM Operations 접근 권한도 필요합니다. 알림과 일정은 팀의 Operations 페이지에 연결되므로, 팀을 볼 수 없는 자격 증명은 오류가 아닌 빈 목록을 얻게 됩니다.

Claude Code에 연결

claude mcp add jsm-alerts \
  --env JSM_CLOUD_ID='your-cloud-id' \
  --env JSM_EMAIL='you@example.com' \
  --env JSM_API_TOKEN="${JSM_API_TOKEN}" \
  -- node /absolute/path/to/jira-alerts-mcp/dist/index.js

사람들이 자주 실수하는 두 가지: 서버 이름은 플래그보다 앞에 오는 첫 번째 위치 인수이며, zsh에서는 ${VAR}에 따옴표가 필요합니다. GUI로 시작된 세션의 경우 토큰은 ~/.claude/settings.json의 env 블록에 있어야 합니다 — 셸 환경은 상속되지 않습니다.

테스트

npm test           # offline test suite — no network, no tenant
npm run inspect    # MCP Inspector against dist/index.js — needs credentials

실제 확인을 위해 jsm_list_schedules로 시작하세요. ID가 필요 없으며 인증, 스코프 및 팀 가시성을 한 번에 확인합니다.

엔드포인트 검증 상태

경로는 추측이 아닌 JSM ops REST API 참조를 기준으로 확인되었습니다:

• 게시된 문서에서 확인됨: /v1/alerts, /v1/alerts/{id}, /v1/alerts/alias, /v1/alerts/requests/{id}, /v1/alerts/{id}/acknowledge, /v1/alerts/{id}/close, /v1/alerts/{id}/responders, /v1/alerts/{id}/notes, /v1/schedules/{id}/on-calls, /v1/schedules/{id}/next-on-calls.

• Opsgenie와 동일, 첫 실행 시 확인할 가치 있음: GET /v1/alerts/{id}/logs 및 노트/로그 페이지네이션의 정확한 쿼리 매개변수(order, offset 커서). JSM Operations는 Opsgenie API의 리호스팅이며 여기서는 변경되지 않았지만, 문서 사이트는 클라이언트 측 렌더링이라 끝까지 읽을 수 없었습니다.

• 컬렉션 래퍼: Atlassian은 컬렉션이 data 아래에 오는지 values 아래에 오는지 일관성이 없습니다. JsmClient.getCollection은 둘 다 허용하고 정규화하므로 어느 쪽이든 변경이 필요 없습니다 — 하지만 목록 도구가 존재하는 데이터에 대해 0개 항목을 반환한다면, 그 정규화기가 가장 먼저 살펴볼 곳입니다.

아키텍처

src/
├── index.ts                 # transports and startup credential validation
├── server.ts                # assembles the tool domains
├── constants.ts             # API root, limits
├── types.ts                 # JSM API interfaces
├── schemas/common.ts        # Zod fragments shared across domains
├── services/
│   ├── client.ts            # auth, request, envelope normalisation, error mapping
│   └── format.ts            # markdown rendering, truncation, result envelopes
└── tools/
    ├── define.ts            # defineTool() + registerTools()
    ├── list-executor.ts     # the shared list pipeline
    ├── alerts/              # read tools — one file per tool, plus shapes.ts
    ├── actions/             # write tools, all via execute-action.ts
    └── oncall/              # schedules and on-call

도구당 파일 하나. 도구 모듈은 입력 형태, 설명 및 핸들러만 소유하며 그 외에는 아무것도 없습니다 — 가장 큰 것은 약 100줄입니다. server.ts는 세 도메인의 내보낸 배열을 연결하고, index.ts는 전송만 알고 있습니다.

확장할 때 보존할 가치가 있는 세 가지 규칙:

• 모든 목록 도구는 executeList를 거칩니다 (tools/list-executor.ts). 이 함수가 가져오기, 빈 결과 분기, 25,000자로의 잘림, 페이지네이션 블록 및 형식 전환을 소유합니다. 이 로직의 도구별 복사본에 두 가지 버그가 있었습니다 — 빈 페이지가 SDK가 거부하는 결과를 반환했고, next_offset가 잘림이 버린 레코드를 건너뛰었습니다. 이제 의도적으로 하나의 복사본만 있습니다.

• 모든 쓰기는 executeAction을 거칩니다 (tools/actions/execute-action.ts), 따라서 비동기 수신 계약이 네 개의 쓰기 도구 사이에서 어긋날 수 없습니다.

• 페이지네이션은 가져온 것이 아니라 전달된 것을 보고합니다. count와 next_offset는 실제 응답에 있는 레코드를 설명하며, truncated는 API가 맞는 것보다 더 많이 반환했을 때 표시됩니다.

inputSchema에 대한 참고

MCP TypeScript SDK의 registerTool은 원시 Zod 형태(Zod 유형의 일반 객체)를 기대하며, z.object(...)가 아닙니다. 일부 예제에서 보여주는 것처럼 z.object를 전달하면 실패합니다. 여기의 도구는 일반 형태를 정의하고 z.infer<z.ZodObject<typeof shape>>로 입력 유형을 파생합니다. 한 가지 결과: .strict()는 원시 형태에 적용할 수 없으므로, 알 수 없는 키는 거부되는 대신 제거됩니다.

관련하여, ToolResult는 인터페이스가 아닌 유형 별칭입니다: SDK의 CallToolResult는 인덱스 시그니처를 가지며, TypeScript는 유형 별칭에만 암시적 인덱스 시그니처를 부여합니다.

기여

개발 루프, 보존할 가치가 있는 규칙, 도구 추가 방법은 CONTRIBUTING.md를 참조하세요. 이슈와 PR에는 클라우드 ID, 토큰 또는 실제 알림 데이터가 포함되어서는 안 됩니다.

보안

이 서버는 Atlassian 자격 증명을 보유하며, HTTP 전송은 자체 인증을 수행하지 않습니다 — 위협 모델, 강화 노트 및 취약점을 비공개로 신고하는 방법은 SECURITY.md를 참조하세요.

라이선스

Apache-2.0