observer-launch-mcp

Observe 데이터에 대해 Claude에게 질문하세요 -- 최근 오류, 흔한 실패, 포드별 로그 볼륨 등을 OPAL을 직접 작성하지 않고도 알 수 있습니다. 이 MCP 서버는 Claude에게 Observe 테넌트에 대한 직접적이고 실시간 액세스를 제공합니다.

설정 (2단계)

1. 설정 마법사를 실행하세요. Observe 자격 증명과 데이터셋 별칭을 묻고, Claude Code에 자동으로 등록합니다:

npx @aryanbansal-launch/observer-launch-mcp init

다음 항목을 입력하라는 메시지가 표시됩니다:

• Observe 고객 ID -- 숫자이며, Observe URL에서 찾을 수 있습니다.

• Observe API 키 -- 계정 관리 → 내 API 토큰에서 생성하세요. (수집/데이터스트림 토큰이 아닙니다 -- 비슷해 보이지만 여기서는 작동하지 않습니다.)

• 클러스터 -- 예: eu-1. 기본 US 테넌트를 사용하는 경우 비워 두세요.

• 데이터셋 별칭 (선택 사항) -- 자주 질문할 데이터셋의 친숙한 이름, 예: launch-management → 41249178. ID는 Observe UI에서 찾을 수 있습니다: 데이터셋을 열면 URL에 있습니다. 이 단계를 건너뛰고 원시 데이터셋 ID를 사용하거나 나중에 별칭을 추가할 수 있습니다.

2. Claude Code를 다시 시작 (또는 새 세션 시작)하여 새 서버를 인식하게 하세요. 작동하는지 확인하세요:

Is the Observe connection working?

이것으로 끝입니다 -- 아래의 다른 도구들이 이제 채팅에서 사용 가능합니다.

claude mcp add observe -s user \
  -e OBSERVE_CUSTOMER_ID=<your id> \
  -e OBSERVE_API_KEY=<your token> \
  -e OBSERVE_CLUSTER=eu-1 \
  -e OBSERVE_DATASETS='{"launch-management":"41249178"}' \
  -- node <path to installed server.js>

절대 경로만 원한다면 먼저 npx @aryanbansal-launch/observer-launch-mcp init을 한 번 실행하세요 -- 실행 직전에 실행할 정확한 명령을 출력합니다. 최종 항목으로 npx <package>가 아닌 직접 node <path> 명령을 사용하세요 -- Claude Code는 등록된 서버를 빈 환경(PATH 없음)으로 실행하며, npx의 shebang은 node를 찾기 위해 PATH가 필요하므로, npx-as-command는 조용히 "Failed to connect."를 표시합니다. 마법사는 이미 이를 피해 줍니다.

Related MCP server: Fathom AI MCP Server

무엇을 물어볼 수 있나요

설정이 완료되면 Claude에게 자연스럽게 말하세요:

• "Observe 연결이 작동하나요?"

• "어떤 서비스/데이터셋 별칭이 구성되어 있나요?"

• "지난 1시간 동안 launch-management의 최근 오류를 보여줘"

• "이번 주 launch-nginx에서 가장 흔한 오류는 무엇인가요?"

• "지금 launch-management-bg에서 가장 많이 로그를 기록하는 포드는 무엇인가요?"

• "launch-nginx가 지난 6시간 동안 얼마나 많은 stderr 출력을 생성하나요?"

• "지난 1시간 동안 launch-telemetry에서 포드별 로그 줄 수를 세어줘"

• "launch-logs-bg-exporter에서 마지막 20개의 원시 로그 줄을 가져와"

특정 질문 형태로 다루지 않는 모든 것에 대해, 원하는 것을 설명하기만 하면 됩니다 -- Claude가 일반 쿼리 도구를 사용하여 OPAL 파이프라인을 작성할 것입니다.

도구 참조

get_error_summary와 get_log_stats는 서버 측에서 집계하므로 시간 창에 관계없이 빠릅니다. get_service_errors와 run_opal_query는 집계 없이 6시간 이상의 창을 쿼리하면 경고를 추가합니다. 넓은 창에서 원시 행 덤프는 Observe의 100k 행 제한에 걸릴 수 있기 때문입니다.

로그 형식

한 테넌트의 데이터셋은 로그 스키마를 공유하는 경우가 드물므로, get_service_errors와 get_error_summary는 데이터셋별로 형식을 감지하고 (프로세스당 한 번) 일치하는 쿼리를 구성합니다:

모든 결과는 감지된 형식을 알려줍니다. 프로브를 건너뛰려면 데이터셋 구성에 선언하세요:

{ "launch-nginx": { "id": "41250854", "shape": "http" } }

일반 "alias": "id" 항목은 여전히 작동하며 자동 감지됩니다.

적용 범위는 보고되며 숨겨지지 않습니다. level 데이터셋에서 일부 줄에는 구문 분석 가능한 level 필드가 없으며(스택 추적, 단순 문자열, 비-JSON 출력) 심각도 필터가 이를 볼 수 없습니다. 그 비율이 1%를 초과하면 도구가 이를 알려줍니다:

Note: 529 of 2136 rows (24.8%) have no parseable "level" field and were not
scanned. Pass includeUnparsed=true to keyword-match those too.

includeUnparsed=true는 해당 줄을 키워드 스캔합니다. 키워드 일치는 "error"라는 단어를 포함하는 info 줄도 표시하므로 선택 사항입니다.

구성 참조

데이터셋 ID는 테넌트별로 다르며 의도적으로 이 패키지에 포함되지 않습니다. 구성된 것이 없으면 별칭 조회는 대체되고 원시 숫자 데이터셋 ID를 모든 도구에 직접 전달할 수 있습니다.

문제 해결

• 상태 확인 실패 → API 키가 계정 관리 → 내 API 토큰의 토큰이 아니라 수집/데이터스트림 토큰일 가능성이 높습니다. 다시 생성하세요.

• 수동으로 등록한 항목에서 claude mcp list가 "Failed to connect"를 표시 → 명령이 node <path>인지 확인하세요. npx <package>가 아닌지 (위의 콜아웃 참조).

• 도구가 "Unknown service/dataset"을 반환 → list_known_services를 실행하여 구성된 것을 확인하거나 원시 숫자 데이터셋 ID를 전달하세요.

• get_service_errors/get_error_summary가 유용한 것을 반환하지 않음 → 결과의 "Detected log format" 메모를 확인하세요. 잘못 추측한 경우 {"alias": {"id": "...", "shape": "http"}}로 형식을 명시적으로 고정하세요 (로그 형식 참조). text라고 표시되면 로그에 심각도 필드가 없으며 일치는 키워드 기반입니다.

• Observe UI에서 볼 수 있는 오류가 결과에 누락됨 → 적용 범위 메모를 찾으세요. 구문 분석 가능한 level이 없는 줄은 기본적으로 건너뜁니다. includeUnparsed=true를 전달하세요.

기여

npm install
npm run build   # tsc, then chmod +x on the bin entry
npm publish      # only if you intend to ship a new version

src/run-server.ts의 get_error_summary/get_log_stats 패턴을 복사하여 다른 반복 OPAL 쿼리(예: 서비스별 비용, 지연 시간 백분위수)에 사용하세요 -- 도구에 설명적인 이름/설명을 지정하여 Claude가 적절할 때 run_opal_query 대신 선택하도록 하세요.