Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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.json
index 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.mjs
new file mode 100644
index 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.py
new file mode 100644
index 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))