Skip to main content
Glama
deenjakoruzh
jovial-liu

mcpstub

by jovial-liu
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

mcpstub

一个由真实契约生成的模拟 MCP 服务器。

mcpstub 可将 mcpdoctor 报告或一份小型 JSON fixture 转换为确定性的 stdio 服务器。无需真实凭据、不依赖不稳定的 API，也无需手写 JSON-RPC 通信代码，即可测试 MCP 客户端、网关和 agent 测试框架。

mcpstub 将契约转换为确定性的现代或旧版测试服务器

$ mcpstub from mcpdoctor.json --out fixtures/docs.json
mcpstub: wrote fixtures/docs.json (14 tools)

$ mcpstub check fixtures/docs.json
✓ valid mcpstub fixture: fixtures/docs.json

$ mcpstub serve fixtures/docs.json
# speaks MCP on stdin/stdout until the client disconnects

实用的开发闭环

检查真实服务器一次，审查契约，然后针对本地 stub 进行测试：

# 1. Inventory the server. mcpdoctor never calls its tools.
npx --yes github:jovial-liu/mcpdoctor#v1 inspect \
  --format json --out mcpdoctor.json -- \
  npx -y @modelcontextprotocol/server-filesystem /tmp

# 2. Generate a safe starting fixture from the advertised contract.
npx --yes github:jovial-liu/mcpstub#v1 from mcpdoctor.json --out fixtures/files.json

# 3. Point an MCP client at the deterministic fixture server.
npx --yes github:jovial-liu/mcpstub#v1 serve fixtures/files.json

生成的 fixture 保留工具名称、描述、schema、注解、资源、模板、提示词和服务器身份。它生成的是占位结果——绝不包含生产环境工具的输出。

手写场景

Fixture 就是普通但可审阅的 JSON。可以按参数指定场景，直接加到某个工具上：

{
  "schema": "mcpstub/v1",
  "server": { "name": "weather-fixture", "version": "1.0.0" },
  "tools": [
    {
      "name": "get_weather",
      "description": "Get a fixture forecast",
      "inputSchema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      },
      "cases": [
        {
          "when": { "city": "Paris" },
          "result": { "content": [{ "type": "text", "text": "Paris: 21°C, clear" }] }
        },
        {
          "when": { "city": "Atlantis" },
          "error": { "code": -32004, "message": "Fixture city not found" }
        }
      ],
      "result": { "content": [{ "type": "text", "text": "Fixture forecast unavailable" }] }
    }
  ]
}

when 对参数对象执行递归子集匹配。对象型场景可以忽略无关字段；数组型场景按长度和位置匹配。先命中第一个匹配的场景，没有则回退到 result。如果二者都没有，mcpstub 会返回一个确定性的生成结果，其中包含工具名和参数。

试试我们维护好的示例：

npx --yes github:jovial-liu/mcpstub#v1 check examples/weather.json
npx --yes github:jovial-liu/mcpstub#v1 serve examples/weather.json

实现内容

  • 现代协议 2026-07-28 的 server/discover、结果判别器和缓存元数据；

  • 旧版 initialize 协商，默认版本 2025-11-25；

  • tools/list 以及确定性的 tools/call 结果或 JSON-RPC 错误；

  • 资源与资源模板列表，外加 resources/read；

  • 提示词列表，外加 prompts/get；

  • ping、未知方法错误和解析错误；

  • 可选地把对 stub 发起的调用记录为 JSONL。

两种协议时代都可在同一个 fixture 进程中使用。现代客户端从 server/discover 开始，旧客户端从 initialize 开始。

可选的调用断言

记录被测系统向 stub 要求执行了哪些操作：

mcpstub serve fixture.json --log calls.jsonl

日志包含时间戳、工具名和参数。它默认关闭，因为参数可能包含机密或私有数据。除非经过审查和脱敏，否则不要将调用日志放入版本控制。

CLI

mcpstub from <mcpdoctor.json> [--out mcpstub.json]
mcpstub check <fixture.json> [--json]
mcpstub serve <fixture.json> [--log calls.jsonl]
mcpstub --version

fixture 格式由 schema/fixture.schema.json 管理版本。check 也会以稳定的 finding 错误码拒绝重名和畸形场景。

安全与限制

mcpstub 不会启动真正的 MCP 服务器，不会调用真实工具，不会执行 shell，不会加载环境凭据，也不会发出网络请求。因此 只读取 您指定的 fixture 内容，不会主动输出任何内容，除非写入路径是明确给出的。

它是协议级的 fixture，而不是安全沙箱，也不是完整的服务器模拟器：

  • 支持 stdio；不支持 Streamable HTTP 和鉴权；

  • 不模拟多轮请求往返、订阅、sampling、elicitation 和扩展等功能；

  • 对外公布的 JSON Schema 不会实现调用参数的校验；

  • 生成的 fixtures 只有契约和占位响应，没有行为记录；

  • 恶意构造的 fixture 可以将恶意文本返回给您正在测试的客户端，因此审查第三方 fixture 时须当作代码一样的测试数据。

如果是需要回放真实会话、期望 cassettes 数据，请使用 cassette 风格的录制器。mcpstub 刻意是契约驱动的：最小的 fixture、明确场景、确定性结果。

开发

git clone https://github.com/jovial-liu/mcpstub.git
cd mcpstub
npm run check

Node.js 20 以上，零运行时依赖。参看 CONTRIBUTING.md 和 SECURITY.md。

License

MIT

This server cannot be installed

-
license - not tested
Not graded
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • saagarpatel.dev Portfolio

    Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.

  • mockmcp

    Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.

  • AgentLux

    Hosted AgentLux MCP server for marketplace, identity, creator, services, and social flows.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jovial-liu/mcpstub'

If you have feedback or need assistance with the MCP directory API, please join our Discord server