mcpmock

A Bun + TypeScript playground for rapidly prototyping Model Context Protocol (MCP) servers.
Describe your mock server in a single YAML file, run the CLI, and the server (stdio or HTTP) responds with mocked data. The goal is to help iterate on tool shapes and responses without building full backends.

Project status

• Single-file YAML configs (examples/basic/mock.yaml) load into a typed representation with clear errors.
• The CLI now spins up a mock MCP server:
  • transport: stdio (default) connects via stdin/stdout for agent integrations.
  • transport: http starts an Express server backed by StreamableHTTPServerTransport.
• Tool calls return the configured response as text (and structured content when applicable).

Installation

Once the package is published to npm you can install or run it instantly:

npm install -g mcpmock
# or run without installing
npx mcpmock ./examples/basic/mock.yaml

Usage

Point the CLI at any project YAML file:

npx mcpmock path/to/server.yaml

• transport: stdio (default) connects via stdin/stdout for agent integrations.
• transport: http starts an Express server backed by StreamableHTTPServerTransport.
• Cross-origin requests are enabled (with Mcp-Session-Id exposed) so browsers like MCP Inspector can connect directly.

If the configuration contains mistakes, the CLI prints readable error messages with annotated paths so coding agents (and humans) can quickly fix them.

Local development

To work on the CLI locally:

bun install
bun run build
node dist/index.js examples/basic/mock.yaml

The build step emits the Node-ready bundle (dist/index.js) and TypeScript declarations used when publishing to npm.

Configuration format

All configuration lives in one YAML file. Example (examples/basic/mock.yaml):

server:
  name: demo-mock
  transport: stdio
  description: Minimal mock MCP server example

tools:
  - name: echo
    description: Returns the provided message
    input_schema:
      type: object
      properties:
        message:
          type: string
      required:
        - message
    response:
      message: default echo

Response templating

Within response values you can reference tool arguments using {{ args.* }} expressions. Strings are interpolated at call time and work inside nested objects and arrays. For example:

tools:
  - name: echo
    response:
      message: "You said: {{ args.message }}"

If a referenced argument is missing, the tool call raises an error to make debugging easier.

Key rules:

• Every tool must have a unique name.
• input_schema follows JSON Schema conventions (currently a subset focused on objects, strings, numbers, booleans, arrays).
• response can be any JSON value (plain strings work too if you want Markdown).

Roadmap

1. Harden the HTTP transport (SSE sessions, resumability, auth helpers).
2. Provide richer response scripting options (multiple scenarios, templating).
3. Build a companion MCP client CLI to run scripted interactions, log tool calls, and support lightweight evals.
4. Support optional multi-file layouts for large projects.
5. Package for npm distribution and provide compiled binaries with bun build --compile.

Contributions, ideas, and feedback are welcome! Feel free to sketch new formats in examples/ and iterate on the CLI.***