convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
Youzi9601

MCP TestKit

Youzi9601/mcp-testkit

Framework de testes integrado para servidores MCP com Vitest

Ver no GitHub
InicialPluginScore · de 0 a 100

Kit de testes nativo para servidores Model Context Protocol, integrado com Vitest e TypeScript. Oferece API de primeira classe com matchers customizados, suporte a snapshots e abstrações de transporte, eliminando a necessidade de dependências externas do SDK.

Instalação

$npx convez-ai Youzi9601/mcp-testkit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
—
Issues abertas
4
Contribuidores
1

Casos de uso

  • Testar servidores MCP em produção com testes unitários e de integração
  • Validar schemas de ferramentas e recursos via snapshot testing
  • Automatizar testes em pipelines CI/CD com reporter JUnit

Veredito

Solução madura e bem integrada ao ecossistema Vitest/TypeScript para testes de servidores MCP. Preenche genuinamente uma lacuna na toolchain de desenvolvimento, com suporte a múltiplos transportes e CI/CD nativo.

README

A tradução para o português deste README ainda está na fila.

mcp-testkit

The missing test kit for Model Context Protocol servers. Vitest-native · TypeScript-first · Snapshot support · Zero SDK dependency

npm version Test License: MIT


Why mcp-testkit?

Every MCP server needs tests. Existing tools are CLI wrappers (mcp-jest), framework-agnostic utility dumps (mcp-testing-kit), or LLM-dependent evaluators. None of them feel like a real testing library integrated into your workflow.

mcp-testkit is what Vitest is to JavaScript testing: a first-class, framework-integrated experience with TypeScript types you can actually rely on.


Packages

PackageDescription
@youzi9601/mcp-testkitCore API — createMcpServer, custom matchers, transport abstraction
@youzi9601/mcp-testkit-vitestVitest plugin — auto-registers all custom matchers
@youzi9601/mcp-testkit-httpHTTP transport for MCP test servers
@youzi9601/mcp-testkit-snapshotSnapshot testing — detect breaking tool schema changes
@youzi9601/mcp-testkit-reporter-junitJUnit XML reporter for CI pipelines

Core concepts

Install

npm install -D @youzi9601/mcp-testkit @youzi9601/mcp-testkit-vitest vitest

Configure

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import mcpTestkit from '@youzi9601/mcp-testkit-vitest'

export default defineConfig({
  plugins: [mcpTestkit()],
  test: {
    pool: 'forks',
    poolOptions: { forks: { singleFork: true } },
  },
})

createMcpServer — spawn your MCP server in tests

Start a real MCP server process and control it from tests.

import { createMcpServer } from '@youzi9601/mcp-testkit'

test('my server exposes getWeather tool', async () => {
  const server = await createMcpServer({
    command: 'node',
    args: ['./dist/server.js'],
  })

  const tools = await server.listTools()
  expect(tools).toHaveTool('getWeather')

  await server.close()
})

Two transport modes — swap with one line:

// Stdio (default)
const server = await createMcpServer({ command: 'node', args: ['./dist/server.js'] })

// HTTP
import { HttpTransport } from '@youzi9601/mcp-testkit-http'
const transport = new HttpTransport({ url: 'http://localhost:3000/mcp' })
const server = await createMcpServer({ transport })

MockMcpServer — pure in-process mock, no subprocess

Pre-program mock JSON-RPC responses without spawning any process.

import { MockMcpServer } from '@youzi9601/mcp-testkit/test-utils'

const mock = new MockMcpServer({
  responses: [
    {
      jsonrpc: '2.0',
      id: 1,
      result: {
        tools: [{ name: 'echo', description: 'Echo input' }],
        resources: [],
        prompts: [],
      },
    },
  ],
})

const { command, args } = mock.getSpawnCommand()
const server = await createMcpServer({ command, args })

Custom matchers — assertions built for MCP

MatcherWhat it checks
.toHaveTool(name)A tool with this name exists
.toHaveTool({ name, description })Tool exists with exact properties
.toMatchMcpTool()Tool shape matches MCP spec
.toMatchMcpResponse()Valid JSON-RPC 2.0 response
.toContainText(text)Text appears in response content
.toContainText(text, { exact: true })Text is the only content
.toMatchSnapshot(name?)Matches stored snapshot (snapshot package)
// Tool existence
expect(tools).toHaveTool('getWeather')
expect(tools).toHaveTool({ name: 'getWeather', description: 'Get weather for a city' })

// Tool response
const result = await server.callTool('getWeather', { city: 'Taipei' })
expect(result).toMatchMcpResponse()
expect(result).toContainText('Taipei')

Snapshot testing — catch breaking schema changes

npm install -D @youzi9601/mcp-testkit-snapshot
// vitest.setup.ts
import { setup } from '@youzi9601/mcp-testkit-snapshot'
setup('./test-snapshots')
test('tool list snapshot', async () => {
  const server = await createMcpServer({ command: 'node', args: ['./dist/server.js'] })
  const result = await server.listTools()
  await expect(result).toMatchSnapshot({ name: 'my-tools' })
  await server.close()
})

HTTP integration testing

import { createHttpMcpServer } from '@youzi9601/mcp-testkit-http'

test('HTTP server exposes readFile tool', async () => {
  const server = await createHttpMcpServer({
    url: 'http://localhost:3000/mcp',
    startServer: {
      command: 'node',
      args: ['./dist/http-server.js'],
      readinessUrl: 'http://localhost:3000/health',
    },
  })

  const tools = await server.listTools()
  expect(tools).toHaveTool('readFile')

  await server.close()
})

JUnit reporter — drop into any CI

import { JUnitReporter } from '@youzi9601/mcp-testkit-reporter-junit'

export default defineConfig({
  reporters: [new JUnitReporter({ outputFile: 'junit.xml' })],
})

Requirements

  • Node.js 18+
  • Vitest 2.x

License

MIT

Ver o original no GitHub

Bom para

Relacionados