When building Model Context Protocol (MCP) servers or AI agents that consume them, traditional API testing tools fall short. An MCP server isn't just a basic REST endpoint—it's a dynamic interface exposed to non-deterministic LLMs through stdio, HTTP, or SSE transports.
Testing tool schemas, transient network failures, and agent behaviors usually requires writing a mountain of boilerplate.
I built bubblemcp-test-kit to eliminate that friction: no backend accounts, no complex test setup, and zero instrumentation required.
What is bubblemcp-test-kit?
bubblemcp-test-kit is a lightweight, standalone testing toolkit designed specifically for MCP server developers and AI agent engineers.
Key features include:
Transport Agnostic: Work with stdio, HTTP, or SSE behind a unified API.
Fluent Assertions: Native matchers tailored for MCP response structures and JSON Schemas.
Mocking & Replay: Fabricate tool outputs locally or record real server runs to replay in offline CI environments.
Agent Trace & Fault Injection: Test if your AI agent calls tools in the right order and handles errors properly.
Quickstart Example
You can run a complete mock test suite without spinning up a live server:
import {
createMockMcpClient,
expectMcp,
validateAgainstSchema,
withRecording,
createReplayClient,
} from 'bubblemcp-test-kit'
// 1. Define your tool contract
const healthCheckTool = {
name: 'health_check',
description: 'Reports service health',
inputSchema: {
type: 'object',
properties: { service: { type: 'string' } },
required: ['service'],
},
outputSchema: {
type: 'object',
properties: {
service: { type: 'string' },
status: { type: 'string', enum: ['ok', 'degraded', 'down'] },
latencyMs: { type: 'number' },
},
required: ['service', 'status', 'latencyMs'],
},
}
// 2. Set up a mock MCP client
const mock = createMockMcpClient({ tools: [healthCheckTool] })
mock.mockTool('health_check').resolves({ service: 'weather', status: 'ok', latencyMs: 12 })
mock.mockTool('flaky_tool').rejects('rate limited')
// 3. Chain fluent assertions
const result = await mock.callTool('health_check', { service: 'weather' })
expectMcp(result)
.toBeValidMcpResponse()
.not.toBeError()
.toContainText('weather')
.toMatchOutputSchema(healthCheckTool)
// 4. Validate schema violations locally
const badPayload = { service: 'weather', status: 'invalid-status', latencyMs: 'slow' }
const validation = validateAgainstSchema(badPayload, healthCheckTool.outputSchema)
console.log('Schema valid?', validation.valid) // false
// 5. Record & Replay for CI
const FIXTURE = './fixtures/health-check.json'
const recording = withRecording(mock, FIXTURE)
await recording.callTool('health_check', { service: 'weather' })
// Replay offline inside CI pipelines
const replay = await createReplayClient(FIXTURE)
const replayed = await replay.callTool('health_check', { service: 'weather' })
expectMcp(replayed).toBeValidMcpResponse()
Instant CLI Smoke Testing
If you just want to run an instant health check on an existing MCP server, use the CLI directly:
npx bubblemcp-test-kit test --url http://localhost:3000/mcp --security
It discovers your tools, validates outputs against declared JSON Schemas, scans for prompt poisoning or credential leaks, and outputs a formatted pass/fail report.
Check out the full repository and let me know what you think in the comments!
Top comments (0)