用 TypeScript SDK 构建并验证 Node.js MCP 客户端

{
  "name": "mcp-node-client",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": { "node": ">=20" },
  "scripts": {
    "build": "tsc"
  },
  "dependencies": {
    "@modelcontextprotocol/client": "2.4.0",
    "@modelcontextprotocol/server": "2.4.0",
    "zod": "4.6.7"
  },
  "devDependencies": {
    "@types/node": "26.6.5",
    "typescript": "7.0.2"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "types": ["node"],
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}

import { Client, ProtocolError, SdkError, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

export type Transport = StdioClientTransport | StreamableHTTPClientTransport;

/** How a tool call ended, in the four ways a caller has to tell apart. `sdk-error` is the SDK giving up: a timeout or a closed connection. */
export type ToolOutcome =
  | { kind: "ok"; text: string; structured?: unknown }
  | { kind: "tool-error"; text: string }
  | { kind: "protocol-error"; code: number; message: string }
  | { kind: "sdk-error"; code: string; message: string };

function textOf(content: ReadonlyArray<{ type: string; text?: string }>): string {
  return content
    .filter((block) => block.type === "text")
    .map((block) => block.text ?? "")
    .join("\n");
}

export class McpToolClient {
  private readonly client: Client;

  /**
   * With `auto` the client probes with `server/discover` and falls back to `initialize`.
   * Without it the SDK sends `initialize` only, which a server of revision 2026-07-28 or later may refuse.
   */
  constructor(name: string, options: { auto?: boolean } = {}) {
    this.client = new Client({ name, version: "1.0.0" }, options.auto ? { versionNegotiation: { mode: "auto" } } : {});
  }

  async connect(transport: Transport): Promise<void> {
    await this.client.connect(transport);
  }

  get protocolVersion(): string | undefined {
    return this.client.getNegotiatedProtocolVersion();
  }

  async toolNames(): Promise<string[]> {
    const { tools } = await this.client.listTools();
    return tools.map((tool) => tool.name);
  }

  async callTool(name: string, args: Record<string, unknown>, timeoutMs = 5000): Promise<ToolOutcome> {
    try {
      const result = await this.client.callTool({ name, arguments: args }, { timeout: timeoutMs });
      const text = textOf(result.content);
      if (result.isError) {
        return { kind: "tool-error", text };
      }
      return result.structuredContent === undefined
        ? { kind: "ok", text }
        : { kind: "ok", text, structured: result.structuredContent };
    } catch (error) {
      if (ProtocolError.isInstance(error)) {
        return { kind: "protocol-error", code: error.code, message: error.message };
      }
      if (SdkError.isInstance(error)) {
        return { kind: "sdk-error", code: error.code, message: error.message };
      }
      throw error;
    }
  }

  async close(): Promise<void> {
    await this.client.close();
  }
}

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

// serveStdio calls this whenever it needs an instance, so every call must return a fresh server.
function createServer() {
  const server = new McpServer({ name: "fixture", version: "1.0.0" });

  server.registerTool(
    "add",
    {
      description: "Add two numbers",
      inputSchema: z.object({ a: z.number(), b: z.number() }),
      outputSchema: z.object({ sum: z.number() }),
    },
    async ({ a, b }) => ({
      content: [{ type: "text", text: String(a + b) }],
      structuredContent: { sum: a + b },
    }),
  );

  server.registerTool("fail", { description: "Always throws", inputSchema: z.object({}) }, async () => {
    throw new Error("boom");
  });

  server.registerTool(
    "slow",
    { description: "Answers after a delay", inputSchema: z.object({ ms: z.number() }) },
    async ({ ms }) => {
      await new Promise((resolve) => setTimeout(resolve, ms));
      return { content: [{ type: "text", text: "done" }] };
    },
  );

  server.registerTool("crash", { description: "Exits the server process", inputSchema: z.object({}) }, async () => {
    process.exit(1);
  });

  return server;
}

serveStdio(createServer, { onerror: (error) => console.error("fixture server error:", error) });
console.error("fixture server running on stdio");

import { fileURLToPath } from "node:url";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { McpToolClient, type ToolOutcome } from "./client.js";

const serverPath = fileURLToPath(new URL("./server.js", import.meta.url));

function stdio(command = process.execPath, args = [serverPath]) {
  return new StdioClientTransport({ command, args, stderr: "ignore" });
}

function show(outcome: ToolOutcome): string {
  switch (outcome.kind) {
    case "ok":
      return `ok text=${JSON.stringify(outcome.text)}` + (outcome.structured === undefined ? "" : ` structured=${JSON.stringify(outcome.structured)}`);
    case "tool-error":
      return `tool-error text=${JSON.stringify(outcome.text)}`;
    case "protocol-error":
      return `protocol-error code=${outcome.code} message=${JSON.stringify(outcome.message)}`;
    case "sdk-error":
      return `sdk-error code=${outcome.code}`;
  }
}

async function main(): Promise<void> {
  // 1. The same server, connected the SDK's default way and with version negotiation.
  for (const auto of [false, true]) {
    const probe = new McpToolClient("scenario-probe", { auto });
    await probe.connect(stdio());
    console.log(`connect ${auto ? "auto   " : "default"}: protocol ${probe.protocolVersion}, tools ${(await probe.toolNames()).join(", ")}`);
    await probe.close();
  }

  // 2. Tool calls over one negotiated connection.
  const client = new McpToolClient("scenario-client", { auto: true });
  await client.connect(stdio());
  const calls: Array<[string, Record<string, unknown>, number?]> = [
    ["add", { a: 2, b: 3 }],
    ["add", { a: "2", b: 3 }],
    ["nosuch", {}],
    ["fail", {}],
    ["slow", { ms: 3000 }, 300],
    ["slow", { ms: 50 }, 2000],
    ["crash", {}],
  ];
  for (const [name, args, timeoutMs] of calls) {
    const label = `${name}(${JSON.stringify(args)})${timeoutMs === undefined ? "" : ` timeout=${timeoutMs}ms`}`;
    console.log(`${label} -> ${show(await client.callTool(name, args, timeoutMs))}`);
  }
  await client.close();

  // 3. A server command that does not exist.
  const missing = new McpToolClient("scenario-missing", { auto: true });
  try {
    await missing.connect(stdio("mcp-server-that-does-not-exist", []));
    console.log("missing command -> connected (unexpected)");
  } catch (error) {
    console.log(`missing command -> connect rejected: ${error instanceof Error ? error.message : String(error)}`);
  }
}

main().catch((error: unknown) => {
  console.error("scenario run failed:", error);
  process.exit(1);
});

connect default: protocol 2025-11-25, tools add, fail, slow, crash
connect auto   : protocol 2026-07-28, tools add, fail, slow, crash
add({"a":2,"b":3}) -> ok text="5" structured={"sum":5}
add({"a":"2","b":3}) -> tool-error text="Input validation error: Invalid arguments for tool add: a: Invalid input: expected number, received string"
nosuch({}) -> protocol-error code=-32602 message="Tool nosuch not found"
fail({}) -> tool-error text="boom"
slow({"ms":3000}) timeout=300ms -> sdk-error code=REQUEST_TIMEOUT
slow({"ms":50}) timeout=2000ms -> ok text="done"
crash({}) -> sdk-error code=CONNECTION_CLOSED
missing command -> connect rejected: spawn mcp-server-that-does-not-exist ENOENT

import { ProtocolError, SdkError, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
import { McpToolClient } from "./client.js";

// Usage: node build/probe-client.js default|auto PORT
const [mode, port] = process.argv.slice(2);
if ((mode !== "default" && mode !== "auto") || !/^\d+$/.test(port ?? "")) {
  console.error("usage: probe-client.js default|auto PORT");
  process.exit(2);
}

const client = new McpToolClient("probe-client", { auto: mode === "auto" });
try {
  await client.connect(new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${port}/mcp`)));
  const names = await client.toolNames();
  console.log(`connected: protocol ${client.protocolVersion}, ${names.length} tools`);
  await client.close();
} catch (error) {
  const reason = ProtocolError.isInstance(error)
    ? `ProtocolError ${error.code}`
    : SdkError.isInstance(error)
      ? error.code
      : error instanceof Error
        ? error.name
        : "unknown";
  console.log(`connect failed: ${reason}`);
}

#!/usr/bin/env python3
"""Connect the TypeScript SDK client (probe-client.js) to the probe server of the clients page, in both eras and in the
SDK's two connect modes, and run lifecycle_check over what the probe saw.

Usage: era_runs.py BUILD_DIR      BUILD_DIR = the directory that holds the compiled `build/probe-client.js`
Exit code 0 = each of the four runs ended as the table at the top of EXPECTED says; 2 = node or the build is missing.
Needs only the standard library, and two scripts from other pages saved next to this file: `client_probe_server.py`
(the probe server of the clients page) and `lifecycle_check.py` (the checker of the architecture page).
"""
import shutil
import subprocess
import sys
import threading
from pathlib import Path

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))
import client_probe_server  # noqa: E402
import lifecycle_check  # noqa: E402

PORT = 8246
# (SDK mode, probe era) -> (the client says, whether lifecycle_check must pass)
EXPECTED = {
    ("default", "legacy"): ("connected: protocol 2025-11-25, 0 tools", True),
    ("default", "modern"): ("connect failed:", False),
    ("auto", "legacy"): ("connected: protocol 2025-11-25, 0 tools", True),
    ("auto", "modern"): ("connected: protocol 2026-07-28, 0 tools", True),
}


def run(build, mode, era):
    records = []
    server = client_probe_server.serve(era, PORT, records.append)
    thread = threading.Thread(target=server.serve_forever, daemon=True)
    thread.start()
    try:
        done = subprocess.run([shutil.which("node"), str(build / "build" / "probe-client.js"), mode, str(PORT)],
                              capture_output=True, text=True, timeout=60, cwd=str(build))
    finally:
        server.shutdown()
        server.server_close()
        thread.join(timeout=5)
    return (done.stdout.strip() or done.stderr.strip()), records


def chain(records):
    return " -> ".join(r["method"] for r in records)


def main():
    if len(sys.argv) != 2 or not shutil.which("node") or not (Path(sys.argv[1]) / "build" / "probe-client.js").is_file():
        print("usage: era_runs.py BUILD_DIR (node on PATH, `npm run build` done in BUILD_DIR)", file=sys.stderr)
        return 2
    build = Path(sys.argv[1])
    bad = 0
    for (mode, era), (says, must_pass) in EXPECTED.items():
        output, records = run(build, mode, era)
        print("run: sdk-mode=%s probe=%s" % (mode, era))
        print("  client says: %s" % output)
        print("  requests: %s" % chain(records))
        ok = output.startswith(says)
        if must_pass:
            passed, warned, failed = lifecycle_check.summary(lifecycle_check.run_checks(records))
            print("  lifecycle_check: %d pass, %d warn, %d fail" % (passed, warned, failed))
            ok = ok and (warned, failed) == (0, 0)
        else:
            print("  lifecycle_check: not run (the connection failed)")
        print("  check: %s" % ("as expected" if ok else "UNEXPECTED"))
        bad += 0 if ok else 1
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main())

run: sdk-mode=default probe=legacy
  client says: connected: protocol 2025-11-25, 0 tools
  requests: initialize -> notifications/initialized -> tools/list
  lifecycle_check: 7 pass, 0 warn, 0 fail
  check: as expected
run: sdk-mode=default probe=modern
  client says: connect failed: ProtocolError -32601
  requests: initialize
  lifecycle_check: not run (the connection failed)
  check: as expected
run: sdk-mode=auto probe=legacy
  client says: connected: protocol 2025-11-25, 0 tools
  requests: server/discover -> initialize -> notifications/initialized -> tools/list
  lifecycle_check: 7 pass, 0 warn, 0 fail
  check: as expected
run: sdk-mode=auto probe=modern
  client says: connected: protocol 2026-07-28, 0 tools
  requests: server/discover -> tools/list
  lifecycle_check: 7 pass, 0 warn, 0 fail
  check: as expected