npm package: @iflow-mcp/dimirolz-mcpmock
Description: Mock Model Context Protocol servers from a single YAML file.
Author: Dimirolz
Latest version: 0.1.3

# 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:

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

## Usage

Point the CLI at any project YAML file:

```bash
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:

```bash
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`):

```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:

```yaml
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.***