3D engine that AI agents drive
Smoke the MCP server through the Inspector CLI and the Python SDK
Nguyen Xuan An03f627232e6c
diff --git a/changes/69-mcp-clients.md b/changes/69-mcp-clients.mdnew file mode 100644index 00000000..8f8b1515--- /dev/null+++ b/changes/69-mcp-clients.md@@ -0,0 +1 @@+- Add `npm run smoke:mcp-clients` (issue #69). It drives the CPU MCP server through the pinned MCP Inspector CLI 2.13.0 and the official Python SDK 2.3.0. Both list 22 tools and create a scene, and the Python client gets a PNG back from `scene_look`. The Inspector CLI cannot, because it starts a new server per command, and `docs/mcp.md` records that.diff --git a/docs/mcp.md b/docs/mcp.mdindex cf7a7c2c..f491a851 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -74,7 +74,8 @@ Every recorded agent run used Claude Code. This table says what was tried elsewh| Client or check | Result ||---|---|| Official MCP SDK client over stdio (`npm run smoke:mcp-package`) | Passes. |-| MCP Inspector CLI (`npx @modelcontextprotocol/inspector --cli node node_modules/67js/bin/67js-mcp.mjs --method tools/list`) | Lists all 22 tools. A `tools/call` of `scene_create` with a box recipe returned a session and inspection. |+| MCP Inspector CLI 2.13.0 (`npm run smoke:mcp-clients`) | Passes, 2026-11-03, Windows, `--backend cpu`. Lists all 22 tools through `tools/list` in 7 s. `tools/call` of `scene_create` with the lamp recipe succeeds in 10 s. The CLI starts a new server for every command and the scene lives in the server, so it cannot follow with `scene_look`. That call fails with "No scene is active" and returns no image. The preview image is not testable through this CLI. |+| Official MCP Python SDK 2.3.0 (`npm run smoke:mcp-clients`) | Passes, 2026-11-03, Windows, `--backend cpu`. Initialize, `tools/list` (22 tools), `scene_create` and `scene_look` in one session. `scene_look` returns a 20480 byte PNG. 11 s including the first `uv` download. || JSON Schema 2020-12 validator with strict mode (Ajv 8), run in `npm test` | Every tool input schema compiles. || Tool names and descriptions | Names are 9 to 24 characters from `[a-z_]`, within the 64-character limit OpenAI, Gemini and Anthropic share. No description is over 1024 characters. || Cursor, Gemini CLI, Claude Desktop, VS Code, any OpenAI or Gemini model | Not run. No account or client was available. Configure them with the same `command` and `args` as above, which is unverified. |diff --git a/package.json b/package.jsonindex bb456aba..5fe0aa8b 100644--- a/package.json+++ b/package.json@@ -105,6 +105,7 @@"mcp": "node bin/67js-mcp.mjs","smoke:mcp": "node scripts/smoke-mcp.mjs","smoke:mcp-package": "node scripts/smoke-mcp-package.mjs",+ "smoke:mcp-clients": "node scripts/smoke-mcp-clients.mjs","smoke:kernel-workers": "node scripts/smoke-kernel-workers.mjs","smoke:agent-topology": "node scripts/smoke-agent-topology.mjs","smoke:agent-look": "node scripts/smoke-agent-look.mjs",diff --git a/scripts/smoke-mcp-clients.mjs b/scripts/smoke-mcp-clients.mjsnew file mode 100644index 00000000..c7989e8d--- /dev/null+++ b/scripts/smoke-mcp-clients.mjs@@ -0,0 +1,76 @@+import assert from 'node:assert/strict';+import { spawnSync } from 'node:child_process';+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { dirname, join, resolve } from 'node:path';+import { createAgentPreviewFixture } from './agent-preview-fixture.mjs';++// Pinned so a client release cannot change the result unnoticed.+const INSPECTOR_VERSION = '2.13.0';+const PYTHON_SDK_VERSION = '2.3.0';+const EXPECTED_TOOL_COUNT = 22;+const COMMAND_TIMEOUT_MS = 240000;+// Run npx's own script with node so no shell has to quote the JSON arguments.+const npxCli = resolve(dirname(process.execPath), process.platform === 'win32'+ ? 'node_modules/npm/bin/npx-cli.js'+ : '../lib/node_modules/npm/bin/npx-cli.js');++const serverScript = resolve('scripts/mcp-server.mjs');+const pythonClientScript = resolve('scripts/smoke-mcp-python-client.py');+// The clients run from an empty folder so they cannot pick up this repo's files.+const workFolder = mkdtempSync(join(tmpdir(), '67js-mcp-clients-'));+const recipePath = join(workFolder, 'recipe.json');+writeFileSync(recipePath, JSON.stringify(createAgentPreviewFixture()));+const results = [];++function run(command, args) {+ const started = Date.now();+ const outcome = spawnSync(command, args, {+ cwd: workFolder,+ encoding: 'utf8',+ timeout: COMMAND_TIMEOUT_MS,+ maxBuffer: 64 * 1024 * 1024,+ });+ return { ...outcome, seconds: Number(((Date.now() - started) / 1000).toFixed(1)) };+}++function inspector(...methodArguments) {+ return run(process.execPath, [+ npxCli, '-y', `@modelcontextprotocol/inspector@${INSPECTOR_VERSION}`, '--cli',+ process.execPath, serverScript, '--backend', 'cpu', '--memory', '192', ...methodArguments,+ ]);+}++function record(client, version, step, passed, seconds, note = '') {+ results.push({ client, version, step, passed, seconds, note });+}++try {+ const listed = inspector('--method', 'tools/list');+ assert.equal(listed.status, 0, listed.stderr);+ const toolCount = JSON.parse(listed.stdout).tools.length;+ assert.equal(toolCount, EXPECTED_TOOL_COUNT);+ record('MCP Inspector CLI', INSPECTOR_VERSION, 'tools/list', true, listed.seconds, `${toolCount} tools`);++ const recipeArgument = `recipe=${JSON.stringify(createAgentPreviewFixture())}`;+ const called = inspector('--method', 'tools/call', '--tool-name', 'scene_create', '--tool-arg', recipeArgument);+ assert.equal(called.status, 0, called.stderr);+ assert.notEqual(JSON.parse(called.stdout).isError, true);+ record('MCP Inspector CLI', INSPECTOR_VERSION, 'tools/call scene_create', true, called.seconds);++ // The Inspector CLI starts a new server for each command, and the scene lives in the+ // server process, so scene_look cannot see the scene made above. Record what it does.+ const looked = inspector('--method', 'tools/call', '--tool-name', 'scene_look');+ assert.ok(!(looked.stdout + looked.stderr).includes('"type": "image"'), 'scene_look unexpectedly returned an image');+ record('MCP Inspector CLI', INSPECTOR_VERSION, 'tools/call scene_look in a fresh server', false, looked.seconds, 'no scene in a new process, so no image');++ const python = run('uv', ['run', '--no-project', '--with', `mcp==${PYTHON_SDK_VERSION}`,+ 'python', '-I', pythonClientScript, process.execPath, serverScript, recipePath]);+ assert.equal(python.status, 0, python.stderr);+ const summary = JSON.parse(python.stdout.trim().split('\n').pop());+ assert.equal(summary.tools, EXPECTED_TOOL_COUNT);+ record('MCP Python SDK', PYTHON_SDK_VERSION, 'initialize, tools/list, scene_create, scene_look PNG', true, python.seconds, `${summary.pngBytes} byte PNG`);+} finally {+ rmSync(workFolder, { recursive: true, force: true });+ console.table(results);+}diff --git a/scripts/smoke-mcp-python-client.py b/scripts/smoke-mcp-python-client.pynew file mode 100644index 00000000..637edea4--- /dev/null+++ b/scripts/smoke-mcp-python-client.py@@ -0,0 +1,45 @@+"""Drive scripts/mcp-server.mjs through the official MCP Python SDK client.++Usage: python -I smoke-mcp-python-client.py <node> <server script> <recipe json>+"""+import asyncio+import base64+import json+import sys+import time++import mcp+from mcp.client.stdio import stdio_client++EXPECTED_TOOL_COUNT = 22+PNG_SIGNATURE = bytes([137, 80, 78, 71, 13, 10, 26, 10])+++async def run(node_path, server_script, recipe_path):+ with open(recipe_path, encoding="utf-8") as recipe_file:+ recipe = json.load(recipe_file)+ parameters = mcp.StdioServerParameters(+ command=node_path,+ args=[server_script, "--backend", "cpu", "--memory", "192"],+ )+ async with stdio_client(parameters) as (read_stream, write_stream):+ async with mcp.ClientSession(read_stream, write_stream) as session:+ await session.initialize()+ listing = await session.list_tools()+ assert len(listing.tools) == EXPECTED_TOOL_COUNT, len(listing.tools)+ created = await session.call_tool("scene_create", {"recipe": recipe})+ assert not created.is_error, created.content+ look = await session.call_tool("scene_look", {"width": 256, "height": 192})+ assert not look.is_error, look.content+ images = [block for block in look.content if block.type == "image"]+ assert len(images) == 1, "scene_look returned no image"+ assert images[0].mime_type == "image/png"+ png_bytes = base64.b64decode(images[0].data)+ assert png_bytes[:8] == PNG_SIGNATURE+ return {"tools": len(listing.tools), "pngBytes": len(png_bytes)}+++started = time.time()+outcome = asyncio.run(run(*sys.argv[1:4]))+outcome["seconds"] = round(time.time() - started, 1)+print(json.dumps(outcome))