Simula infraestrutura de IA, incluindo APIs de LLM, ferramentas MCP, bancos de dados vetoriais e protocolos de agentes para testes determinísticos de aplicações.
Também conhecido como CopilotKit/aimock, @copilotkit/aimock
- Stars
- 1.014
- Ferramentas
- —
- Downloads, 30 dias
- 1.921.458
- Versão mais recente
- —
- Último commit
- 13 de nov. de 2026
- Licença
- MIT
O que é o MCP aimock?
Simula infraestrutura de IA, incluindo APIs de LLM, ferramentas MCP, bancos de dados vetoriais e protocolos de agentes para testes determinísticos de aplicações.
Resumo gerado a partir do README do projeto
Sobre o MCP server de aimock
Desenvolvedores que constroem aplicações de IA podem usar o aimock para criar um ambiente de teste determinístico, apontando seus SDKs para uma única porta local. Esta ferramenta substitui serviços externos reais por mocks locais, eliminando a necessidade de chaves de API, conexões de rede ou custos inesperados. Ela abrange uma ampla gama de infraestrutura, incluindo provedores de LLM como OpenAI, Claude e Gemini, além de serviços especializados para geração de imagens, text-to-speech e geração de vídeo.
Além de simples chat completions, a suíte fornece mocks especializados para ferramentas MCP, protocolos de agente-para-agente via A2AMock e bancos de dados vetoriais compatíveis com Pinecone ou ChromaDB. Os usuários podem implementar a funcionalidade de record and replay para capturar interações reais de API como fixtures, permitindo testes repetíveis que preservam dados de tempo e uso de tokens. Também oferece suporte a chaos testing para simular rate limits, latência e respostas JSON malformadas, garantindo que as aplicações possam lidar com falhas do mundo real de forma resiliente.
O que você pode fazer com ele
- 1Testes de API determinísticosUm desenvolvedor pode apontar seu SDK existente para uma porta local para receber respostas previsíveis de vários provedores de LLM sem usar chaves reais.
- 2Validação de lógica de faturamentoGaranta que a carteira ou o fluxo de faturamento de uma aplicação esteja correto ao reproduzir dados gravados de uso de tokens e custos.
Escrito a partir do README do projeto. Cada caso de uso é verificado com uma citação dele.
Como instalar o MCP aimock
Formatos verificados em 10 nov 2026Adicionar ao CursorAdicionar ao GooseInstalar o MCP aimock no Claude Code
$ claude mcp add aimock -- npx -y @copilotkit/aimockInstalar o MCP aimock no Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"aimock": {
"command": "npx",
"args": [
"-y",
"@copilotkit/aimock"
]
}
}
}Instalar o MCP aimock no VS Code
.vscode/mcp.json
{
"servers": {
"aimock": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@copilotkit/aimock"
]
}
}
}Instalar o MCP aimock no VS Code CLI
$ code --add-mcp '{"name":"aimock","type":"stdio","command":"npx","args":["-y","@copilotkit/aimock"]}'Instalar o MCP aimock no Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"aimock": {
"command": "npx",
"args": [
"-y",
"@copilotkit/aimock"
]
}
}
}Instalar o MCP aimock no Codex
$ codex mcp add aimock -- npx -y @copilotkit/aimockInstalar o MCP aimock no Codex config.toml
~/.codex/config.toml
[mcp_servers.aimock] command = "npx" args = ["-y", "@copilotkit/aimock"]
Instalar o MCP aimock no Gemini CLI
$ gemini mcp add -s user aimock npx -- -y @copilotkit/aimockInstalar o MCP aimock no Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"aimock": {
"command": "npx",
"args": [
"-y",
"@copilotkit/aimock"
]
}
}
}Configuração
AIMOCK_API_KEYS
| Nome | Descrição | Tipo |
|---|---|---|
| AIMOCK_API_KEYS | — |
Verificações automatizadas
Executado em 13 de nov. de 2026Relatório completo →Passou em nossas verificações automatizadas. Isso não é uma auditoria de segurança: leia o código e dê ao servidor o acesso mais restrito de que ele precisa. Como as verificações funcionam
- Repositório de origem vinculado e acessívelPassou
- Licença de código aberto (OSI)Passou
- Commit ou release no último anoPassou
- Nome do pacote não é próximo a um pacote popularPassou
- O endpoint remoto usa HTTPSNão verificado
- Ferramentas destrutivas estão rotuladasNão verificado
- Sem instruções ocultas para o modeloPassou
- Nenhum aviso crítico no pacote ou em suas dependênciasNão verificado
README
Ver no GitHubaimock
Mock infrastructure for AI application testing — point your SDK at one local port and every provider, protocol, and service answers deterministically.
Quick start · The suite · Record & replay · Docs
https://github.com/user-attachments/assets/76815122-574a-48e1-b275-edae0a014667
One package, one port, zero dependencies. LLM APIs, image generation and editing, text-to-speech, transcription, audio translation and generation, video generation, embeddings, MCP tools, A2A agents, AG-UI event streams, vector databases, search, rerank, and moderation — no keys, no network, no surprise bills.
Quick Start
npm install @copilotkit/aimock
// The class is still named `LLMock` for back-compat after the v1.7.0 package
// rename from `@copilotkit/llmock` to `@copilotkit/aimock`.
import { LLMock } from "@copilotkit/aimock";
const mock = new LLMock({ port: 0 });
mock.onMessage("hello", { content: "Hi there!" });
await mock.start();
// Set env BEFORE importing/constructing the OpenAI (or other provider) client.
// Many SDKs cache the base URL at construction time — if the client is built
// before these are set, it will talk to the real API (surprise bills) instead
// of aimock.
process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
process.env.OPENAI_API_KEY = "mock"; // SDK requires a value, even when base URL is mocked
// ... run your tests ...
await mock.stop();
The aimock Suite
aimock mocks everything your AI app talks to:
| Tool | What it mocks | Docs |
|---|---|---|
| LLMock | OpenAI (Chat/Responses/Realtime GA/GPT-Live), Claude, Gemini (REST/Live/Interactions/Embeddings), Bedrock, Azure, Vertex AI, Ollama (chat/embeddings), Cohere (chat/embed), OpenRouter (chat/router/video), BytePlus Ark (chat/images/video), Grok (video), Veo (video), fal.ai, ElevenLabs (TTS/Voice Design/Scribe/Audio Isolation), BytePlus Seed Speech | Providers |
| MCPMock | MCP tools, resources, prompts with session management | MCP |
| A2AMock | Agent-to-agent protocol with SSE streaming and multi-turn conversations | A2A |
| AGUIMock | AG-UI agent-to-UI event streams for frontend testing | AG-UI |
| VectorMock | Pinecone, Qdrant, ChromaDB compatible endpoints | Vector |
| Services | Tavily search, Cohere rerank, OpenAI moderation | Services |
Run them all on one port with npx @copilotkit/aimock --config aimock.json, or use the programmatic API to compose exactly what you need.
Features
- Record & Replay — Proxy real APIs, save as fixtures, replay deterministically forever
- Timing-aware recording and replay — Recorded fixtures capture per-frame arrival timestamps; replay uses recorded timings for approximate timing reproduction based on recorded TTFT and inter-frame cadence (replay chunk count may differ from recording — TTFT and average pace are preserved, not per-token fidelity) with configurable
--replay-speedmultiplier - Recorded token usage and cost — Recording captures the final usage frame of a streaming completion, so replayed fixtures serve real
prompt_tokens/completion_tokensinstead of a length estimate; OpenRouter's provider-reportedusage.costand itscost_details/*_tokens_detailsbreakdowns are captured too, so an app that bills from real provider cost can e2e-test its wallet path from a tape - Multi-turn Conversations — Record and replay multi-turn traces with tool rounds; match distinct turns via
turnIndex,hasToolResult,toolCallId,toolResultContains(gate on the tool-result payload),sequenceIndex,systemMessage(gate on host-supplied agent context), or custom predicates - Ollama embedding recordings — Current
/api/embedcaptures retain input shape, dimensions and model in their match and stay separate from legacy/OpenAI embedding operations. - 11 providers across 22 API surfaces — OpenAI Chat, OpenAI Responses, OpenAI Realtime (GA; an
OpenAI-Beta: realtime=v1request gets the real sunset rejection), GPT-Live, Claude, Gemini REST, Gemini embedContent, Gemini Live, Gemini Interactions, Azure, Bedrock, Vertex AI, Ollama (chat + embeddings), Cohere (chat + embed), OpenRouter (chat + router failover), BytePlus Ark (OpenAI-compatible chat + images under/api/v3), ElevenLabs TTS and Voice Design — full streaming support Bedrock with the current AWS JavaScript SDK needsrequestHandler: new NodeHttpHandler()from@smithy/node-http-handlerfor aimock's HTTP/1 server. See SDK setup. - Multimedia APIs — image generation (
gpt-image-1default, Imagen;/v1/images/variationsreplays OpenAI's removal 404), image editing (/v1/images/edits), text-to-speech (OpenAI + ElevenLabs TTS and Voice Design, BytePlus Seed Speech), ElevenLabs Scribe and Audio Isolation (record/replay), audio transcription, audio translation (/v1/audio/translations), video generation, OpenRouter video generation (/api/v1/videos with async job lifecycle), Google Veo video generation (:predictLongRunning + /v1beta/operations async lifecycle), Grok Imagine video generation (/v1/videos/generations with async job lifecycle), BytePlus Ark video generation (Seedance, /api/v3/contents/generations/tasks with async task lifecycle), fal.ai (image / video / audio with queue lifecycle) - OpenAI platform APIs — Files (byte-exact uploads, purpose validation), Vector Stores (CRUD, file attach with deterministic poll progression, file batches, deterministic direct search; hosted
file_searchexecution is not supported), fine-tuning jobs (deterministic lifecycle, events, cursor pages) and Batches (/v1/batchescreate/list/retrieve/cancel with deterministic poll progression and real output files) - MCP / A2A / AG-UI / Vector — Mock every protocol your AI agents use
- MCP Scenario Fakes — An
mcpFakesblock in a fixture file scripts each test's MCP tool answers next to its LLM turns: ordered answers, exact or any-argument matching, scripted tool errors, and a closed-world mode that fails on any undeclared tool. Works with any MCP client over Streamable HTTP - MCP Recording — Record a live MCP server into
mcpFakesfiles (--mcp-record /mcp=<url>, orllm.record.mcpwithllm.enableMcpRecording: truein a config) and replay them offline, with the recorded tool list, progress notifications and timing; known secrets are redacted before anything is written - MCP Fake Reports —
GET /__aimock/mcp/fakes/reportlists each test's served, unused and failed fakes; withuseAimock({ fakesReport: "fail" })a swallowed fake error or an unused fake fails the test, andfakesFor()gives the MCP URL and headers for the current test. Works for agents, workflows and pipelines alike - Chaos Testing — 500 errors, malformed JSON, mid-stream disconnects and 429 rate limits (
--chaos-ratelimit, withRetry-After) at any probability, plus a fixed pre-handling delay (--chaos-latency <ms>); read, set and clear the rates at runtime viaGET/POST/DELETE /__aimock/chaos, scoped to the caller'sX-Test-Idso one test cannot destabilise the suite running beside it - Model Misbehavior — Test invalid tool arguments, schema violations, unknown tools, duplicate IDs, length stops, empty responses, refusals, content filtering, and reasoning-only responses. Supported wires include OpenAI Chat, Responses, Realtime GA, Anthropic, Bedrock InvokeModel and Converse, Gemini generateContent (including the Vertex wrapper), Gemini Live, Gemini Interactions, Cohere, and Ollama chat. Fault and mode support varies by wire. Azure and OpenRouter use the Chat wire. Seeded rates, per-test limits, and journal evidence apply across supported wires. See the reference for the support matrix, SDK behavior, and modeled contracts whose native occurrence remains unverified.
- Request journal —
GET /__aimock/journalreturns every recorded request, filterable bypath,method,status,service,testIdandrequestIdwithlimit/offsetpaging and anX-Total-Countheader carrying the pre-pagination total - HTTP route catalog —
GET /__aimock/openapi.jsonreturns OpenAPI 3.1;GET /__aimock/routesreturns{ count, routes }. For programmatic inspection, importbuildOpenApiDocument,CATALOG_ROUTESandROUTE_DEFINITIONS(withCatalogRoute/RouteDefinitiontypes) from@copilotkit/aimock. The catalog describes HTTP operations; streaming responses include media and framing metadata, not a complete-stream JSON body. - Request IDs — every response carries
X-Request-Id, echoing the caller's header or minting one; the journal stores it on each entry andGET /__aimock/journal?requestId=<id>returns that request. A minted id is never forwarded upstream in record/proxy mode - Per-Request Strict Mode —
X-AIMock-Strictheader overrides the server-level--strictflag per request (true/1= strict,false/0= lenient) - Required Header Policy — Opt-in
requiredHeaders: "enforce"(programmaticpolicy, configllm.policy, repeatable--policyon both CLIs, or theX-AIMock-Policyrequest header) rejects Anthropic HTTP requests (/v1/messages,/v1/messages/count_tokens, Anthropic-flavored/v1/models/{id}, and the/v1/modelslist withmodelCatalog: "native") that omitanthropic-versionwith a native 400. Off by default, and independent of strict mode - Native model catalogs and token counts — Anthropic
GET /v1/models(selected byanthropic-version, orx-api-keywithoutAuthorization; the list route needspolicy.modelCatalog: "native"and otherwise stays the OpenAI list) and GeminiGET /v1beta/modelslist and detail routes with provider paging, built from fixture model IDs with synthetic metadata;POST /v1/messages/count_tokensand Gemini:countTokensreturn a deterministic estimate of about 1 token per 4 characters of messages (plus tool definitions), minimum 1. These routes never proxy or record - Context-Based Fixture Routing —
X-AIMock-Contextheader scopes fixtures per integration; fixtures withmatch.contextonly match requests carrying that context, fixtures without it remain shared - Drift Detection — Daily CI validation against real APIs
- Streaming Physics — Configurable
ttft,tps, andjitter; opt in withnonStreamingTimingAllProviders: trueto give non-streaming replies the same timing on every LLM provider - Client Disconnects — When the client hangs up, every LLM provider (HTTP and WebSocket) stops sending and journals the request as
interrupted, so you can test cancel and abort paths - WebSocket APIs — OpenAI Realtime (GA protocol with models: gpt-realtime, gpt-realtime-2, gpt-realtime-1.5, gpt-realtime-mini; transcription/translation via gpt-4o-transcribe, gpt-4o-mini-transcribe, whisper-1; image input; commentary phase), Responses WS, Gemini Live
- GPT-Live — Mock, record, and replay primary WebSocket sessions at
/v1/live/sessionsin client and managed modes, with fixture-backed audio and backend tool continuation. Saved fixtures replay offline; aimock does not synthesize speech. This voice surface is separate from OpenAI text-model family support; WebRTC/SDP and sideband connections are outside this scope. - Prometheus Metrics — Request counts, latencies, fixture match rates
- Docker + Helm — Container image and Helm chart for CI/CD
- Vitest & Jest Plugins — Zero-config
useAimock()with auto lifecycle and env patching - Response Overrides — Control
id,model,usage,finishReasonin fixture responses - Citations and Generated Files — Fixture
citationsserve source citations on OpenAI Responses (URL and file), Chat Completions, Claude and Gemini; fixturefilesserve generated images on the Responses API and Gemini. Each uses the provider's own format, streaming and non-streaming - Raw Passthrough — A
rawfixture sends provider SSE events or JSON exactly as written on any HTTP LLM wire, for fields aimock does not model yet; timing, chaos and disconnects still apply - Ordered Blocks — A
blocksarray streams text and tool calls in any order (tool-first or interleaved); blocks-only fixtures are first-class, and the recorder captures order from genuinely tool-first/interleaved streams - Namespaced and Custom Tool Calls — Responses API fixtures can return namespaced function calls and custom tool calls (
custom_tool_call) over HTTP streaming, non-streaming and WebSocket, and can match ontoolNamespace. This lets you script OpenAI Codex CLI's namespaced MCP and sub-agent tools and its freeformapply_patchtool (with theresponsesTools: "extended"server option) - Streaming Usage Chunks —
stream_options.include_usagesupport emits a final chunk with token counts, matching OpenAI's streaming usage protocol - Rate Limiting Headers —
x-ratelimit-*headers on every response andRetry-Afteron 429 errors for testing retry/backoff logic - Zero dependencies — Everything from Node.js builtins
Model misbehavior requires aimock 1.45.0 or later. Older versions silently ignore the fixture's misbehavior field and serve its original response. Invalid configurations now fail during fixture loading or programmatic addition. See the model misbehavior reference for supported parameters and compatibility details.
GitHub Action
- uses: CopilotKit/aimock@v1
with:
fixtures: ./test/fixtures
- run: npm test
env:
OPENAI_BASE_URL: http://127.0.0.1:4010/v1
See the GitHub Action docs for all inputs and examples.
CLI
# LLM mocking only
npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures
# Remote fixtures — load JSON from an HTTPS URL (repeatable)
npx -p @copilotkit/aimock llmock -p 4010 \
-f https://raw.githubusercontent.com/acme/mocks/main/openai.json \
-f ./fixtures/local-overrides.json
# Full suite from config
npx @copilotkit/aimock --config aimock.json
# Record mode: proxy to real APIs, save fixtures
npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.com
# Record with extended timeout for reasoning models
npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.com \
--body-timeout-ms 180000
# Replay recorded fixtures at 2× speed
npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures --replay-speed 2
# Convert fixtures from other tools
npx @copilotkit/aimock convert vidaimock ./templates/ ./fixtures/vidaimock.json
npx @copilotkit/aimock convert mockllm ./config.yaml ./fixtures/mockllm.json
# Validate fixtures offline (file or directory, recursive)
npx @copilotkit/aimock validate ./fixtures/
# --strict on the whole shipped tree exits 1 (adk/mastra repeat a userMessage across files)
npx @copilotkit/aimock validate --strict --json ./fixtures/examples/llm/blocks-tool-first.json
# Docker
docker run -d -p 4010:4010 -v "$(pwd)/fixtures:/fixtures" ghcr.io/copilotkit/aimock -f /fixtures -h 0.0.0.0
Note on
llmockvsaimockCLIs. Thellmockbin is retained as a compat alias for users of the pre-1.7.0@copilotkit/llmockpackage. It runs a narrower flag-driven CLI without--configor theconvertandvalidatesubcommands. New projects should useaimock(ornpx @copilotkit/aimock) for full feature support.
Perguntas sobre o MCP aimock
Como adiciono o MCP aimock ao Claude Code?
Execute claude mcp add aimock -- npx -y @copilotkit/aimock no seu terminal. Adicione --scope user para torná-lo disponível em todos os projetos.
Como adiciono o MCP aimock ao Cursor?
Abra ~/.cursor/mcp.json e adicione o servidor em mcpServers, usando a configuração do Cursor mostrada na seção de instalação acima.