Полная библиотека оценки для серверов протокола Model Context Protocol (MCP). Тестируйте и проверяйте свои MCP-серверы с полным покрытием спецификаций MCP, включая инструменты с детерминированными показателями, проверку безопасности и дополнительную оценку на основе LLM.

Статус: MVP - API стабильный, незначительные изменения, возможные до 1.0.0

##0 Быстрый старт

###1 Установка

###2. Создайте файл конфигурации

Создайте файл конфигурации (например, mcp-eval.config.ts):

###3.Провести оценку

##1 Основные понятия

MCPVals обеспечивает комплексное тестирование для всех примитивов спецификации MCP:

1. Инструментальное тестирование здоровья: напрямую вызывает отдельные инструменты с конкретными аргументами для проверки их правильности, производительности и обработки ошибок. Это идеально подходит для модульного тестирования и проверки регрессии.

2. Оценка рабочего процесса: использует большую языковую модель (LLM) для интерпретации подсказок естественного языка и выполнения ряда вызовов инструментов для достижения цели. Это проверяет интеграцию ваших MCP-примитивов с точки зрения LLM.

##2 Требования к установке и времени выполнения

1. Node.js ≥ 18 — мы полагаемся на родные fetch, EventSource и fs/promises.

MCPVals

A comprehensive evaluation library for Model Context Protocol (MCP) servers. Test and validate your MCP servers with complete MCP specification coverage including Tools with deterministic metrics, security validation, and optional LLM-based evaluation.

Status: MVP – API stable, minor breaking changes possible before 1.0.0

---

0. Quick Start

1. Installation

# Install – pick your favourite package manager
pnpm add -D mcpvals            # dev-dependency is typical

2. Create a config file

Create a config file (e.g., mcp-eval.config.ts):

import type { Config } from "mcpvals";

export default {
  server: {
    transport: "stdio",
    command: "node",
    args: ["./example/simple-mcp-server.js"],
  },

  // Test individual tools directly
  toolHealthSuites: [
    {
      name: "Calculator Health Tests",
      tests: [
        {
          name: "add",
          args: { a: 5, b: 3 },
          expectedResult: 8,
          maxLatency: 500,
        },
        {
          name: "divide",
          args: { a: 10, b: 0 },
          expectedError: "division by zero",
        },
      ],
    },
  ],

  // Test multi-step, LLM-driven workflows
  workflows: [
    {
      name: "Multi-step Calculation",
      steps: [
        {
          user: "Calculate (5 + 3) * 2, then divide by 4",
          expectedState: "4",
        },
      ],
      expectTools: ["add", "multiply", "divide"],
    },
  ],

  // Optional LLM judge
  llmJudge: true,
  openaiKey: process.env.OPENAI_API_KEY,
  passThreshold: 0.8,
} satisfies Config;

3. Run Evaluation

# Required for workflow execution
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional for LLM judge
export OPENAI_API_KEY="sk-..."

# Run everything
npx mcpvals eval mcp-eval.config.ts

# Run only tool health tests
npx mcpvals eval mcp-eval.config.ts --tool-health-only

# Run with LLM judge and save report
npx mcpvals eval mcp-eval.config.ts --llm-judge --reporter json > report.json

---

1. Core Concepts

MCPVals provides comprehensive testing for all MCP specification primitives:

1. Tool Health Testing: Directly calls individual tools with specific arguments to verify their correctness, performance, and error handling. This is ideal for unit testing and regression checking.

2. Workflow Evaluation: Uses a large language model (LLM) to interpret natural language prompts and execute a series of tool calls to achieve a goal. This tests the integration of your MCP primitives from an LLM’s perspective.

---

2. Installation & Runtime Requirements

1. Node.js ≥ 18 – we rely on native fetch, EventSource, and fs/promises.
2. pnpm / npm / yarn – whichever you prefer, MCPVals is published as an ESM‐only package.
3. MCP Server – a local stdio binary or a remote Streaming-HTTP endpoint.