Mcp Autotest

以语言无关的方式对 MCP 服务进行自动化测试

mcp-autotest

安装 ⚙ 用法 ⚙ 快速演示 ⚙ 动态匹配

这是一个简单的工具，可让你通过定义包含请求和响应的 YAML 文件，使用 MCP 协议测试 MCP 服务。

MCP 测试用例文件是一个多文档 YAML 文件，其中每个测试用例都定义为一个独立文档，如下所示：

case: Listing tools
in: { "jsonrpc": "2.0", "method": "tools/list", "id": 1 }
out:
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result":
      {
        "tools":
          [
            {
              "description": "Run a read-only SQL query",
              "inputSchema":
                {
                  "type": "object",
                  "properties": { "sql": { "type": "string" } },
                },
              "name": "query",
            },
          ],
      }
  }

---
# next case...

文件名必须以 _test.yaml 为后缀，才能被识别为测试用例文件。

安装

npm

npm install -g mcp-autotest

Github Releases

从 releases 页面下载预构建二进制文件，并将其放入 PATH 中。

从源代码构建

go install github.com/strowk/mcp-autotest@latest

用法

mcp-autotest [flags] run path/to/tests/folder [--] command-to-run-server [server-args]

示例：

# start go MCP server and test via stdio transport
mcp-autotest run testdata go run main.go
# start Postgres MCP server and test via stdio transport
mcp-autotest run -v testdata -- npx -y @modelcontextprotocol/server-postgres localhost:5432
# start go MCP server and test via Streamable HTTP transport
mcp-autotest run --url http://localhost:8080/mcp testdata go run main.go

传输方式

mcp-autotest 默认使用 stdio 传输方式。如果要改用 HTTP 传输方式，可以使用 --url 标志指定 MCP 服务的 URL。 URL 格式必须为 http://host:port/path 或 https://host:port/path。

目前，Streamable HTTP 仅支持 POST 方法，未来计划支持通过 GET 进行测试。

快速演示

在 bash shell 中运行以下命令

# create folder for test data
mkdir -p testdata

# create test cases file
cat << EOF > testdata/list_tools_test.yaml
# This is a test cases file. It contains a list of test cases in YAML format.
# Each test case has variable number of inputs (keyst starting with 'in') and outputs (keys starting with 'out').
# The test cases are separated by '---' (three dashes) on a new line, making it multi-document YAML file.
# File name must end with '_test.yaml' to be recognized as a test cases file.

case: List tools

# requesting list of tools
in: { "jsonrpc": "2.0", "method": "tools/list", "id": 1 }

# expect one tool in the list
out:
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result":
      {
        "tools":
          [
            {
              "description": "Run a read-only SQL query",
              "inputSchema":
                {
                  "type": "object",
                  "properties": { "sql": { "type": "string" } },
                },
              "name": "query",
            },
          ],
      }
  }
EOF

# Now running autotest
npx mcp-autotest run testdata -- npx -y @modelcontextprotocol/server-postgres localhost:5432

输出应只显示一个单词：PASS。

现在，如果你修改 "description": "Run a read-only SQL query", 这一行中的内容，例如改为 "description": "Run a read-only SQL query 2"，然后再次运行上一条命令，就会看到如下输出：

2025/03/31 22:23:39 actual json did not match expectation,
 got: '{"id":1,"jsonrpc":"2.0","result":{"tools":[{"description":"Run a read-only SQL query","inputSchema":{"properties":{"sql":{"type":"string"}},"type":"object"},"name":"query"}]}}'
 diff with expected:
  "result": {
    "tools": {
      "0": {
        "description": {
        ^ value mismatch,
expected string: 'Run a read-only SQL query 2',
     got string: 'Run a read-only SQL query'
FAIL

动态匹配

有时，响应中包含动态值，你可能会想使用正则表达式来匹配它们。可以在预期输出中使用 !!re 标签来实现。例如：

case: List tools
in_list_tools: {"jsonrpc":"2.0","method":"tools/list","id":1}
out_list_tools: {"jsonrpc":"2.0","result":{"tools":[ { "name": !!re "list-[a-z]+" } ]},"id":1}

这个示例经过了一定简化。在实际使用中，你可能会将 !!re 用于时间戳、UUID 或其他动态值，而不是工具名称。 不过，这个示例说明了带有 !!re 标签的字符串会被视为正则表达式，并通过正则表达式匹配而不是字符串相等来与实际值进行匹配。

请参阅测试 postgres server 的可运行示例。

嵌入式正则表达式

嵌入式正则表达式就是嵌入在字符串中的正则表达式，用于匹配字符串的一部分。例如：

case: List tools
in_list_tools: {"jsonrpc":"2.0","method":"tools/list","id":1}
out_list_tools: {"jsonrpc":"2.0","result":{"tools":[ { "name": !!ere "list-/[a-z]+/-tool" } ]},"id":1}

本质上，!!ere 允许你将字符串的大部分视为普通字符串，同时将其中一部分（或多部分）视为正则表达式。 斜杠 / 内的所有内容都会被视为正则表达式。在此例中，"list-" 和 "-tool" 是普通字符串，而 [a-z]+ 是正则表达式，可匹配任意非空的小写字母字符串，因此它可以匹配 "list-abc-tool"、"list-xyz-tool" 等。

这种方法让你无需考虑如何转义字符串其余部分中的正则表达式语法，只需匹配需要动态变化的部分即可。

转义正斜杠

对于嵌入式正则表达式，可能需要在字符串中需要使用斜杠 /、但不想将其指定为正则表达式的地方转义斜杠，例如："url": !! "https:\\/\\/github.com\\//[a-z]+/" 可以匹配 "url": "https://github.com/strowk"。 这里使用 \\/ 表示 /，并使用 [a-z]+ 匹配任意非空的小写字母字符串。之所以有两个反斜杠 \\，是因为在 YAML 字符串中，反斜杠是转义字符；因此，要在字符串中使用单个反斜杠，就需要再用一个反斜杠对其进行转义。