f / f/mcptools

[Feature Request] Add support for using MCP Cases format to mock an MCP server

Open
#44 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
1.6k
Forks
127
PR merge metrics
No merged PRs in 30d

Description

**Summary**

Enhance the `mcptools` mock server (`mcp mock`) to optionally load its behavior from files conforming to the `MCP Cases` specification. This would allow developers to define mock server interactions declaratively using a standardized format, improving the development and testing workflow for MCP clients.

**Background**

* **[MCP Cases Format](https://mcp-cases.str4.io/):** The Model Context Protocol (MCP) Cases format defines a standard way to describe MCP client-server interactions using multi-document YAML files. Each document represents a 'case' with a name (optional `case:` key) and lists of client-to-server (`in:` prefixed keys) and server-to-client (`out:` prefixed keys) messages, typically JSON-RPC 2.0 objects. This format is designed for testing MCP servers, creating mock servers for client testing (contract testing), rapid prototyping, and documentation.
* **`mcptools` Mock Server:** `mcptools` currently provides a mock server mode (`mcp mock`) which allows users to simulate MCP servers by defining mock tools, resources, and prompts directly via command-line arguments.
* **[`mcptee`](https://github.com/strowk/mcptee):** The `mcptee` tool proxies and logs real MCP client-server communications, producing a YAML output file with `in:` and `out:` prefixes that visually resembles the structure used in MCP Cases, though not strictly conforming to the full specification (e.g., lacking the `case:` key).

**Problem/Motivation**

* Defining complex mock server behavior solely through CLI arguments in `mcp mock` can become cumbersome and difficult to manage.
* Developing robust programmatic MCP clients (e.g., using libraries like Pydantic AI) requires testing against realistic server responses and interaction flows, which are hard to simulate accurately with the current CLI-based mock definition.
* While `mcptee` can capture real interactions, and `MCP Cases` provides a format to formally define these interactions, there is currently no easy way to *use* an `MCP Cases` file to drive the behavior of the mock server. `mcptools` is well-positioned to support this use-case.

**Proposed Solution**

Introduce a new mechanism or option for the `mcp mock` command to load and utilize an `MCP Cases` YAML file. For example:

```bash
# Load mock behavior from a specified MCP Cases file
mcp mock --cases path/to/my_cases.yaml
```

When running with an `MCP Cases` file, the mock server should:
1. Parse the multi-document YAML file.
2. When it receives a request from a client matching an `in:` message within a defined case, it should respond with the corresponding `out:` message from that same case. (Handling multiple matching `in`/`out` sequences within a case would need definition, potentially requiring state or ordering logic based on the `MCP Cases` spec examples).

**Benefits**

* **Declarative Mocking:** Allows developers to define potentially complex and stateful mock interactions declaratively in a structured file, rather than imperatively via CLI arguments.
* **Realistic Testing:** Enables the creation of more realistic mock servers by using the `MCP Cases` format, potentially seeding these files from modified `mcptee` logs or defining expected interaction flows explicitly.
* **Contract Testing:** Facilitates contract testing where an `MCP Cases` file serves as the contract; clients can be tested against the `mcptools` mock server loaded with this contract to ensure compatibility.
* **Improved Client Development:** Streamlines the development and testing of programmatic MCP clients by providing a straightforward way to simulate specific server behaviors and responses during development, without needing a live server or complex setup.
* **Standard Alignment:** Aligns `mcptools` mocking capabilities more closely with the `MCP Cases` standard, promoting interoperability and reuse of test/mock definitions.

**Conclusion**

Integrating `MCP Cases` support into `mcptools mock` would significantly enhance its utility as a development and testing tool for the MCP ecosystem. It bridges the gap between capturing real interactions (`mcptee`), formally defining interaction contracts (`MCP Cases`), and simulating server behavior (`mcptools mock`), making it easier to build and test robust MCP clients.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.