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 リリース

リリースページからビルド済みバイナリをダウンロードし、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 シェルで次を実行します。

# 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 の1語だけが表示されます。

次に、"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}

この例はかなり単純化されています。実際には、ツール名ではなくタイムスタンプや UUID、その他の動的な値に !!re を使うことが多いでしょう。 ただし、!!re タグを付けた文字列が正規表現として扱われ、文字列の完全一致ではなく、正規表現マッチングによって実際の値と照合されることを示しています。

Postgres サーバーのテスト例をご覧ください。

埋め込み正規表現

埋め込み正規表現とは、文字列の一部に埋め込まれた正規表現です。文字列の一部分にマッチさせるために使います。例：

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]+ は1文字以上の小文字にマッチする正規表現なので、「list-abc-tool」や「list-xyz-tool」などにマッチします。

この方法を使うと、文字列の残りの部分で正規表現構文をエスケープする方法を考える必要がなく、動的にしたい部分だけをマッチさせられます。

スラッシュのエスケープ

埋め込み正規表現では、正規表現として指定せずに文字列の一部として / を使用したい箇所で、スラッシュをエスケープする必要がある場合があります。たとえば、"url": !! "https:\\/\\/github.com\\//[a-z]+/" は "url": "https://github.com/strowk" に一致します。 ここでは、\\/ を / にし、[a-z]+ を空でない小文字の文字列に一致させるために使用しています。バックスラッシュが2つある \\ 理由は、YAML の文字列ではバックスラッシュがエスケープ文字であるためです。文字列内にバックスラッシュを1つ含めるには、もう1つのバックスラッシュでエスケープする必要があります。