convez.ai
MCP ServerDesenvolvimento WebIntermediário
rogerchappel

MCPMock

rogerchappel/mcpmock

Mock MCP determinístico para testar agentes IA localmente

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que gera catálogos de ferramentas mock e transcrições determinísticas para testes de integração de agentes localmente. Permite validar esquemas, replayar interações e testar agentes sem tocar em serviços reais, eliminando custos, latência e não-determinismo.

Instalação

$npx convez-ai rogerchappel/mcpmock

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
100%
Último commit
há 4 semanas
Versão
—
Issues abertas
3
Contribuidores
2

Casos de uso

  • Testes de integração de agentes IA sem APIs reais
  • Validação de esquemas e respostas de ferramentas MCP
  • Replay determinístico de transcrições de chamadas
  • Desenvolvimento local de agentes com fixtures customizadas

Veredito

Ferramenta essencial para desenvolvedores que constroem agentes MCP. Reduz drasticamente tempo e custo de testes de integração ao fornecer mocks determinísticos e locais. Bem documentada com CLI clara e suporta workflow completo de desenvolvimento.

README

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

MCPMock

Fixture-backed mock MCP tool catalogs for deterministic agent testing 🎭

Test your agent integrations without touching real services.

MCPMock generates mock MCP tool catalogs and call transcripts so developers can test agent integrations, validate schemas, and replay interactions — all locally, all deterministic.

Why?

Building AI agents that use MCP tools means integration testing. But real services are:

  • Slow — network calls, rate limits, downtime
  • Expensive — API costs add up during development
  • Non-deterministic — different results each time = flaky tests

MCPMock gives you a local fixture-backed mock server where the same inputs always produce the same outputs. Write your tests once, run them forever.

Installation

npm install -g mcpmock
# or
npx mcpmock --help

Quick Start

1. Create a catalog

// my-tools.json
{
  "tools": [
    {
      "name": "search",
      "description": "Search the knowledge base",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      },
      "responses": {
        "default": {
          "content": [
            { "type": "text", "text": "Found 3 results for {query} 📚" }
          ]
        },
        "variants": {
          "empty": {
            "content": [
              { "type": "text", "text": "No results found for \"{query}\"" }
            ]
          }
        }
      }
    }
  ]
}

2. Validate it

mcpmock validate my-tools.json
✓ Catalog is valid: 1 tool(s) defined

3. List tools

mcpmock tools my-tools.json
search — Search the knowledge base

# Or get JSON
mcpmock tools my-tools.json --format json

4. Call a tool

mcpmock call my-tools.json search '{"query": "typescript patterns"}'
{
  "content": [
    { "type": "text", "text": "Found 3 results for typescript patterns 📚" }
  ]
}

5. Replay a transcript

Record calls and replay them deterministically:

mcpmock call my-tools.json search '{"query": "hello"}' --record
mcpmock replay transcript.jsonl

CLI Reference

mcpmock validate <catalog>

Validate a mock catalog against the schema.

mcpmock validate catalog.json       # text output
mcpmock validate catalog.json -o    # output validated schema

mcpmock tools <catalog>

List all tools defined in a catalog.

mcpmock tools catalog.json              # text output (default)
mcpmock tools catalog.json --format json  # JSON output

mcpmock call <catalog> <tool-name> <args-json>

Call a mock tool and get a deterministic response.

mcpmock call catalog.json search '{"query": "test"}'
mcpmock call catalog.json search '{"query": "test"}' --variant empty
mcpmock call catalog.json search '{"query": "test"}' --record
mcpmock call catalog.json search '{"query": "test"}' --record --output transcript.jsonl

mcpmock replay <transcript>

Replay a recorded transcript with timing simulation.

mcpmock replay transcript.jsonl          # with default timing
mcpmock replay transcript.jsonl --fast   # skip delays
mcpmock replay transcript.jsonl --speed 2  # 2x faster

Catalog Format

A catalog is a JSON file with a tools array. Each tool has:

FieldTypeRequiredDescription
namestring✅Unique tool identifier
descriptionstring✅Human-readable description
inputSchemaobject✅JSON Schema for input validation
responsesobject✅Response templates
responses.defaultobject✅Default response with content array
responses.variantsobject❌Named variant responses

Template Substitution

Response text supports {propertyName} substitution from input args:

{
  "content": [{ "type": "text", "text": "Hello, {name}!" }]
}

Transcript Format

Transcripts are newline-delimited JSON records:

{"timestamp": 1716489600000, "tool": "search", "args": {"query": "hello"}, "result": {"content": [...]}, "variant": "default", "latencyMs": 42}

Orchestration

MCPMock supports full conversation orchestration. See docs/ORCHESTRATION.md for multi-tool workflows and state machine patterns.

Development

npm install
npm run build
npm test
npm run smoke

Package contents

The npm package allowlist includes the built runtime files plus the public support documents needed for release review: README.md, LICENSE, SECURITY.md, CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, RELEASE_NOTES.md. Run npm run package:smoke or npm pack --dry-run before publishing to confirm those files are still present in the tarball.

License

MIT

Generated Catalog Example

{
  "name": "generated-catalog",
  "description": "Generated mock catalog with 3 tools",
  "tools": [
    {
      "name": "weather",
      "description": "Get current weather conditions for a location",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" },
          "units": { "type": "string", "enum": ["metric", "imperial"] }
        },
        "required": ["location"]
      },
      "responses": {
        "default": {
          "content": [{"type": "text", "text": "Mock response from weather"}]
        }
      }
    }
  ]
}

Run the release-readiness checks that match this package before publishing or opening a release PR.

  • npm run lint - run lint rules
  • npm run check - type-check the TypeScript sources
  • npm test - run the Vitest suite
  • npm run smoke - exercise the built CLI against fixtures
  • npm run package:smoke - build and dry-run the npm tarball
  • npm run release:check - run the full local release gate
Ver o original no GitHub

Bom para

Relacionados