mcp-evals: LLM 기반 점수 평가 및 내장 관측성 지원 MCP 도구 구현을 위한 Node.js 패키지와 GitHub Action

LLM 기반 점수 평가로 MCP (Model Context Protocol) 도구 구현을 평가하는 Node.js 패키지 및 GitHub Action 으로, 내장 관측성 지원이 포함되어 있습니다. 이를 통해 MCP 서버의 도구가 올바르게 작동하고 성능이 좋으며 통합 모니터링과 지표를 통해 완전히 관측 가능하도록 보장합니다.

npm install mcp-evals

워크플레 파일에 다음을 추가하세요:

name: Run MCP Evaluations
on:
pull_request:
...

평가 구성은 TypeScript 또는 YAML 형식 중 하나를 사용하여 만들 수 있습니다.

TypeScript 형식을 사용하려면 (예: evals.ts):

import { EvalConfig } from 'mcp-evals';
import { openai } from "@ai-sdk/openai";
import { grade, EvalFunction} from "mcp-evals";
...

간단한 구성을 위해 YAML 형식 (예: evals.yaml) 을 사용할 수 있습니다:

# Model configuration
model:
provider: openai # 'openai' 또는 'anthropic'
...

TypeScript 또는 YAML 파일 중 하나를 사용하여 CLI 를 통해 평가 실행할 수 있습니다:

# TypeScript 구성 사용
npx mcp-eval path/to/your/evals.ts path/to/your/server.ts
# YAML 구성 사용
...

이 GitHub Action 은 자동으로 다음을 수행합니다:

• 평가를 실행합니다.
• PR 에 댓글로 결과를 게시합니다.
• PR 이 업데이트되면 댓글을 업데이트합니다.

각 평가는 다음 구조를 가진 객체를 반환합니다:

interface EvalResult {
accuracy: number; // 1-5 점수
completeness: number; // 1-5 점수
...

OPENAI_API_KEY: OpenAI 모델 (OpenAI 모델을 위해 필수) 의 OpenAI API 키

ANTHROPIC_API_KEY: Anthropic 모델 (Anthropic 모델을 위해 필수) 의 Anthropic API 키

참고

오픈소스 소프트웨어와 함께 이 GitHub Action 을 사용 중이라면, OpenAI billing dashboard 에서 데이터 공유를 활성화하여 하루에 250 만 개의 무료 GPT-4o mini 토큰을 청구할 수 있습니다. 이를 통해 이 Action 을 사실상 무료로 사용할 수 있습니다.

EvalConfig 인터페이스는 다음을 요구합니다:

model: 평가에 사용할 언어 모델 (예: GPT-4)

evals: 실행할 평가 함수 배열

각 평가 함수는 다음을 구현해야 합니다:

name: 평가 이름

description: 평가가 테스트하는 내용 설명

run: 모델과 EvalResult 를 반환하는 비동기 함수

YAML 구성 파일은 다음을 지원합니다:

모델 설정:

provider: 'openai' 또는 'anthropic'

name: 모델 이름 (예: 'gpt-4o', 'claude-3-opus-20240229')

api_key: 선택적 API 키 (기본값은 환경 변수 사용)

평가 설정:

name: 평가 이름 (필수)

description: 평가가 테스트하는 내용 설명 (필수)

prompt: MCP 서버에 보내는 프롬프트 (필수)

expected_result: 선택적 예상 동작 설명

지원 파일 확장자: .yaml, .yml

참고: 지표 기능은 아직 알파 단계입니다. 기능 및 API 가 변경될 수 있으며, 파기 변경이 발생할 수 있습니다.

• MCP 서버를 초기화하기 전에 다음을 애플리케이션에 추가하세요.

import { metrics } from 'mcp-evals';
metrics.initialize(9090, { enableTracing: true, otelEndpoint: 'http://localhost:4318/v1/traces' });

• 모니터링 스택을 시작하세요:

docker-compose up -d

• MCP 서버를 실행하면 모니터링 스택에 자동으로 연결됩니다.

Prometheus: http://localhost:9090

Grafana: http://localhost:3000 (사용자명: admin, 비밀번호: admin)

Jaeger UI: http://localhost:16686

Tool Calls: 도구 이름별 도구 호출 수

Tool Errors: 도구 이름별 오류 수

Tool Latency: 도구 이름별 지연 시간 분포

MIT