swapi_mcp

관측 가능한 AI 에이전트를 구축하기 위한 작은 종단 간(end-to-end) 참조 프로젝트로, MCP 서버가 Star Wars API를 감싸고, 이를 구동하는 Claude 에이전트와 웹 채팅 UI를 포함합니다 — 모두 OpenTelemetry와 Grafana Cloud(분산 추적, RED 메트릭, 프론트엔드 RUM, AI/에이전트 관측성)로 계측되어 있습니다.

이 프로젝트의 목적은 하나의 실행 가능한 코드베이스에서 MCP 도구 경계, 에이전트의 도구 사용 루프, 그리고 브라우저 클릭에서 업스트림 HTTP 호출까지 내려갔다가 다시 돌아오는 전체 스택 추적이 어떻게 맞물리는지 보여주는 것입니다.

구성 요소

MCP(stdio)를 통해 서로 통신하는 두 부분으로 구성됩니다:

MCP 서버 (src/index.ts, src/tools/) — Star Wars API를 6개 리소스(people, planets, films, species, vehicles, starships)에 걸쳐 18개 도구로 감쌉니다: 리소스당 search_, get-all, get-by-id 도구입니다. 순수한 도구 제공자일 뿐이며 어떤 결정도 내리지 않습니다.

에이전트 (src/agent/) — 의사 결정자:

• mcpClient.ts — 빌드된 서버를 stdio로 실행(spawn)하고 MCP 클라이언트로 연결합니다.

• agent.ts — 수동 도구 사용 루프: 질문과 서버의 도구를 Claude에 보내고, MCP를 통해 요청된 각 도구를 실행한 뒤 결과를 다시 피드백하고, 완료될 때까지 반복합니다.

• main.ts — CLI 진입점입니다.

• server.ts + public/index.html — HTTP 서버와 단일 페이지 채팅 UI입니다.

Related MCP server: SWAPI MCP Server

관측성

아래의 모든 기능은 선택 사항이며 환경 변수로 제어됩니다 — 에이전트는 이 중 어떤 것도 없이도 정상적으로 실행됩니다.

• 분산 추적 (OpenTelemetry → Tempo): 하나의 추적이 browser → POST /ask → agent.turn → llm.request / tool.call → tool.execute → swapi.fetch 체인을 세 개의 서비스(swapi-web, swapi-agent, swapi-mcp-server)에 걸쳐 관통합니다. 추적 컨텍스트는 요청 _meta를 통해 MCP 경계를 넘어 전파됩니다.

• RED 메트릭 (→ Mimir): 도구별 및 LLM 호출별 rate / errors / duration 히스토그램과 비용 산정용 토큰 사용량 카운터로, model, error, error.type 태그가 지정됩니다.

• 프론트엔드 RUM (Grafana Faro): Web Vitals, JS 오류, 브라우저→백엔드 추적 전파.

• AI / 에이전트 관측성 (@grafana/agent-o11y): 정규화된 LLM 생성 및 도구 실행.

• 데모 장애 주입 (src/chaos.ts): 선택적으로 한 리소스가 시뮬레이션된 503을 반환하고 다른 리소스는 50% 느리게 실행되도록 하여, 대시보드에 실제 오류 및 지연 신호가 표시되게 합니다.

사전 요구 사항

• Node.js 22+ (--env-file 사용)

• Yarn 4 (Corepack 경유)

• Anthropic API 키 (에이전트용)

• Grafana Cloud 계정 (선택 사항 — 관측성 기능에만 필요)

설정

yarn install
yarn build

MCP 서버 직접 사용하기 (예: Claude Desktop)

MCP 클라이언트를 빌드된 서버에 연결하세요:

{
  "mcpServers": {
    "swapi": { "command": "node", "args": ["/absolute/path/to/swapi_mcp/build/index.js"] }
  }
}

에이전트 실행

최소한 Anthropic 키를 포함한 .env 파일을 생성하세요(git-ignored):

ANTHROPIC_API_KEY=sk-ant-...

그런 다음:

yarn dev                              # build + serve the web UI at http://localhost:8787
yarn ask "Who is Luke's homeworld?"   # one-shot CLI

환경 변수

참고 사항

학습/데모용 프로젝트입니다. 데이터는 SWAPI의 정적 미러에서 가져온 것으로, SWAPI는 동작(actions)이 아닌 연관 관계(캐릭터가 영화에 "출연한다")를 모델링합니다 — 따라서 답변도 그에 맞게 표현됩니다.

라이선스

MIT