Building an MCP Server

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"terminal","version":"0.0.1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_room_status","arguments":{"roomId":"huddle-2"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_room_status","arguments":{"roomId":"lobby"}}}

room-tools 0.1.0 ready on stdio
{"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"room-tools","version":"0.1.0"}},"jsonrpc":"2.0","id":1}
{"result":{"content":[{"type":"text","text":"{\"roomId\":\"huddle-2\",\"inCall\":true,\"camera\":\"on\",\"mic\":\"unmuted\",\"firmware\":\"4.3.1\"}"}]},"jsonrpc":"2.0","id":2}
{"result":{"content":[{"type":"text","text":"No room called lobby. Known rooms: huddle-2, board-1."}],"isError":true},"jsonrpc":"2.0","id":3}

// The host's side of the first server: spawn it, list its tools, call one. One file, so it runs anywhere.
import { fileURLToPath } from "node:url";

if (process.argv[2] === "serve") {
  // ---- server.mjs, unchanged ----
  const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
  const { z } = await import("zod");
  const rooms = {
    "huddle-2": { inCall: true, camera: "on", mic: "unmuted", firmware: "4.3.1" },
    "board-1": { inCall: false, camera: "off", mic: "muted", firmware: "4.2.0" },
  };
  const server = new McpServer({ name: "room-tools", version: "0.1.0" });
  server.registerTool("get_room_status", {
    title: "Get room status",
    description: "Live status of one meeting-room device: in a call or not, camera, mic and firmware version. " +
      "Read-only. Room ids look like huddle-2 or board-1.",
    inputSchema: { roomId: z.string().describe("Room id, for example huddle-2") },
    annotations: { readOnlyHint: true },
  }, async ({ roomId }) => {
    const room = rooms[roomId];
    if (!room) return { isError: true, content: [{ type: "text", text: `No room called ${roomId}. Known rooms: ${Object.keys(rooms).join(", ")}.` }] };
    return { content: [{ type: "text", text: JSON.stringify({ roomId, ...room }) }] };
  });
  await server.connect(new StdioServerTransport());
  console.error("room-tools 0.1.0 ready on stdio");
} else {
  // ---- what a host does with it ----
  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
  const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
  const transport = new StdioClientTransport({
    command: process.execPath, // the same "node" that runs this file
    args: [fileURLToPath(import.meta.url), "serve"],
    stderr: "pipe", // keep the server's logs apart from the protocol
  });
  let serverLog = "";
  transport.stderr.on("data", (d) => (serverLog += d));
  const client = new Client({ name: "tiny-host", version: "1.0.0" });
  await client.connect(transport); // spawns the process and runs initialize
  console.log("connected to", client.getServerVersion().name, client.getServerVersion().version);
  console.log("capabilities:", JSON.stringify(client.getServerCapabilities()));

  const { tools } = await client.listTools();
  console.log("tools:", tools.map((t) => t.name).join(", "));

  for (const roomId of ["huddle-2", "lobby"]) {
    const result = await client.callTool({ name: "get_room_status", arguments: { roomId } });
    console.log(`${roomId}: isError=${result.isError ?? false} ${result.content[0].text}`);
  }
  await client.close(); // closes stdin; the server process exits
  console.log("server's stderr:", JSON.stringify(serverLog));
}

connected to room-tools 0.1.0
capabilities: {"tools":{"listChanged":true}}
tools: get_room_status
huddle-2: isError=false {"roomId":"huddle-2","inCall":true,"camera":"on","mic":"unmuted","firmware":"4.3.1"}
lobby: isError=true No room called lobby. Known rooms: huddle-2, board-1.
server's stderr: "room-tools 0.1.0 ready on stdio\n"

// The data layer. Here it's an in-memory fake; in production it would call the device REST API.
export function createFakeRooms(seed = {
  "huddle-2": { inCall: true, camera: "on", mic: "unmuted", firmware: "4.3.1" },
  "board-1": { inCall: false, camera: "off", mic: "muted", firmware: "4.2.0" },
}) {
  const rooms = structuredClone(seed);
  return {
    async list() { return Object.keys(rooms); },
    async get(roomId) { return rooms[roomId] ? { roomId, ...rooms[roomId] } : undefined; },
  };
}

// What the server offers. No transport and no process wiring here, so tests can use it directly.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function createServer({ rooms }) {
  const server = new McpServer({ name: "room-tools", version: "0.2.0" });

  server.registerTool(
    "list_rooms",
    {
      title: "List rooms",
      description: "Ids of every meeting room this server knows. Call this first when the user names a room you don't have an id for.",
      outputSchema: { roomIds: z.array(z.string()) },
      annotations: { readOnlyHint: true },
    },
    async () => {
      const roomIds = await rooms.list();
      return { content: [{ type: "text", text: roomIds.join(", ") }], structuredContent: { roomIds } };
    },
  );

  server.registerTool(
    "get_room_status",
    {
      title: "Get room status",
      description:
        "Live status of one meeting-room device: in a call or not, camera, mic and firmware version. " +
        "Read-only. Room ids look like huddle-2 or board-1.",
      inputSchema: { roomId: z.string().describe("Room id, for example huddle-2") },
      outputSchema: {
        roomId: z.string(), inCall: z.boolean(), camera: z.enum(["on", "off"]),
        mic: z.enum(["muted", "unmuted"]), firmware: z.string(),
      },
      annotations: { readOnlyHint: true },
    },
    async ({ roomId }) => {
      const room = await rooms.get(roomId);
      if (!room) {
        const known = await rooms.list();
        return { isError: true, content: [{ type: "text", text: `No room called ${roomId}. Known rooms: ${known.join(", ")}.` }] };
      }
      return { content: [{ type: "text", text: JSON.stringify(room) }], structuredContent: room };
    },
  );

  return server;
}

#!/usr/bin/env node
// The entry point a host launches. It only wires the server to stdin/stdout.
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createServer } from "./server.mjs";
import { createFakeRooms } from "./rooms.mjs";

const server = createServer({ rooms: createFakeRooms() });
await server.connect(new StdioServerTransport());
console.error("room-tools 0.2.0 ready on stdio");

npm pkg set bin.room-tools=src/stdio.mjs scripts.test="node --test" scripts.start="node src/stdio.mjs" scripts.smoke="sh scripts/smoke.sh"
chmod +x src/stdio.mjs
npm install -D @modelcontextprotocol/inspector@2.12.0

{
  "name": "room-tools",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "node --test",
    "start": "node src/stdio.mjs",
    "smoke": "sh scripts/smoke.sh"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.32.2",
    "zod": "^4.6.7"
  },
  "bin": {
    "room-tools": "src/stdio.mjs"
  },
  "devDependencies": {
    "@modelcontextprotocol/inspector": "^2.12.0"
  }
}

// One wrapper for every tool: expected failures become guidance for the model,
// unexpected ones become a short reference while the details go to the server's log.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { z } from "zod";

class ToolFailure extends Error {} // "the model can act on this message"
const log = []; // stands in for console.error / your log pipeline
let incidents = 0;

function safe(handler) {
  return async (args, extra) => {
    try {
      return await handler(args, extra);
    } catch (err) {
      if (err instanceof ToolFailure) return { isError: true, content: [{ type: "text", text: err.message }] };
      const ref = `E${++incidents}`;
      log.push(`${ref} request ${extra.requestId}: ${err.stack.split("\n")[0]}`);
      return { isError: true, content: [{ type: "text", text: `Internal error (ref ${ref}). Don't retry; tell the user the room service failed.` }] };
    }
  };
}

const speakers = { "huddle-2": 40, "board-1": 55 };
const inCall = new Set(["huddle-2"]);
const server = new McpServer({ name: "room-tools", version: "0.3.0" });
server.registerTool("set_volume", {
  description: "Set a room's speaker volume (0-100). Changes the device.",
  inputSchema: {
    roomId: z.string(),
    level: z.number().int().min(0).max(100),
    duringCall: z.boolean().default(false).describe("Set true only after the user confirms changing a live call"),
  },
  annotations: { destructiveHint: false, idempotentHint: true },
}, safe(async ({ roomId, level, duringCall }) => {
  if (roomId === "board-1") throw new Error("connect ECONNREFUSED 10.0.4.17:443"); // the device API is down
  if (!(roomId in speakers))
    throw new ToolFailure(`${roomId} has no speaker. Rooms with speakers: ${Object.keys(speakers).join(", ")}.`);
  if (inCall.has(roomId) && !duringCall)
    throw new ToolFailure(`${roomId} is in a call. Ask the user to confirm, then call again with duringCall: true.`);
  speakers[roomId] = level;
  return { content: [{ type: "text", text: `${roomId} volume is now ${level}.` }] };
}));

const client = new Client({ name: "host", version: "1.0.0" });
const [c, s] = InMemoryTransport.createLinkedPair();
await server.connect(s);
await client.connect(c);
for (const args of [
  { roomId: "lobby", level: 30 },
  { roomId: "huddle-2", level: 30 },
  { roomId: "huddle-2", level: 30, duringCall: true },
  { roomId: "board-1", level: 30 },
]) {
  const r = await client.callTool({ name: "set_volume", arguments: args });
  console.log(`${JSON.stringify(args).padEnd(52)} ${r.isError ? "isError" : "ok"} | ${r.content[0].text}`);
}
console.log("server log:", log);
await client.close();

{"roomId":"lobby","level":30}                        isError | lobby has no speaker. Rooms with speakers: huddle-2, board-1.
{"roomId":"huddle-2","level":30}                     isError | huddle-2 is in a call. Ask the user to confirm, then call again with duringCall: true.
{"roomId":"huddle-2","level":30,"duringCall":true}   ok | huddle-2 volume is now 30.
{"roomId":"board-1","level":30}                      isError | Internal error (ref E1). Don't retry; tell the user the room service failed.
server log: [ 'E1 request 4: Error: connect ECONNREFUSED 10.0.4.17:443' ]

// Keep results small: page long lists with a cursor, and link big content instead of pasting it.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { z } from "zod";

const roomIds = Array.from({ length: 23 }, (_, i) => `room-${String(i + 1).padStart(2, "0")}`);
const logLines = Array.from({ length: 5000 }, (_, i) => `2026-10-27T09:${String(i % 60).padStart(2, "0")} audio: frame ${i}`);
const encode = (offset) => Buffer.from(JSON.stringify({ offset })).toString("base64url");
const decode = (cursor) => JSON.parse(Buffer.from(cursor, "base64url").toString()).offset;

const server = new McpServer({ name: "room-tools", version: "0.3.0" });
server.registerTool("list_rooms", {
  description: "Room ids, 10 per page. If nextCursor is set, call again with it to get the next page.",
  inputSchema: { cursor: z.string().optional().describe("nextCursor from the previous page") },
  outputSchema: { roomIds: z.array(z.string()), nextCursor: z.string().optional() },
  annotations: { readOnlyHint: true },
}, async ({ cursor }) => {
  const offset = cursor ? decode(cursor) : 0;
  const page = { roomIds: roomIds.slice(offset, offset + 10) };
  if (offset + 10 < roomIds.length) page.nextCursor = encode(offset + 10);
  return { content: [{ type: "text", text: JSON.stringify(page) }], structuredContent: page };
});
server.registerTool("get_room_logs", {
  description: "The last lines of a room's device log, plus a link to the full log.",
  inputSchema: { roomId: z.string(), lines: z.number().int().min(1).max(50).default(3) },
  annotations: { readOnlyHint: true },
}, async ({ roomId, lines }) => ({
  content: [
    { type: "text", text: logLines.slice(-lines).join("\n") },
    { type: "resource_link", uri: `rooms://${roomId}/logs`, name: `${roomId} full log`, mimeType: "text/plain",
      description: `${logLines.length} lines; read it only if the last lines don't explain the problem` },
  ],
}));

const client = new Client({ name: "host", version: "1.0.0" });
const [c, s] = InMemoryTransport.createLinkedPair();
await server.connect(s);
await client.connect(c);

let cursor;
do {
  const r = await client.callTool({ name: "list_rooms", arguments: cursor ? { cursor } : {} });
  const { roomIds: ids, nextCursor } = r.structuredContent;
  console.log(`page: ${ids[0]}…${ids.at(-1)} (${ids.length}) nextCursor=${nextCursor ?? "none"}`);
  cursor = nextCursor;
} while (cursor);

const logs = await client.callTool({ name: "get_room_logs", arguments: { roomId: "huddle-2" } });
for (const block of logs.content) console.log(block.type, "→", block.type === "text" ? block.text.split("\n").length + " lines" : block.uri);
console.log("characters returned:", JSON.stringify(logs).length, "instead of", logLines.join("\n").length);
await client.close();

page: room-01…room-10 (10) nextCursor=eyJvZmZzZXQiOjEwfQ
page: room-11…room-20 (10) nextCursor=eyJvZmZzZXQiOjIwfQ
page: room-21…room-23 (3) nextCursor=none
text → 3 lines
resource_link → rooms://huddle-2/logs
characters returned: 336 instead of 173889

// Tools can appear and disappear at runtime; the client is told and lists again.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

const server = new McpServer({ name: "room-tools", version: "0.4.0" });
server.registerTool("get_room_status", { description: "Live status of one room", inputSchema: { roomId: z.string() } },
  async ({ roomId }) => ({ content: [{ type: "text", text: `${roomId}: idle` }] }));
const reboot = server.registerTool("reboot_room", {
  description: "Reboot a room's device. Drops any call in progress. Ask the user first.",
  inputSchema: { roomId: z.string() },
  annotations: { destructiveHint: true },
}, async ({ roomId }) => ({ content: [{ type: "text", text: `${roomId} rebooting` }] }));

const client = new Client({ name: "host", version: "1.0.0" });
const names = async () => (await client.listTools()).tools.map((t) => t.name).join(", ");
client.setNotificationHandler(ToolListChangedNotificationSchema, async () => console.log("  ← notifications/tools/list_changed; host re-lists:", await names()));
const [c, s] = InMemoryTransport.createLinkedPair();
await server.connect(s);
await client.connect(c);

console.log("at start:", await names());
console.log("firmware rollout begins: reboot_room.disable()");
reboot.disable();
await new Promise((r) => setTimeout(r, 10)); // let the notification arrive
const r = await client.callTool({ name: "reboot_room", arguments: { roomId: "huddle-2" } });
console.log("calling it anyway:", r.isError, r.content[0].text);
console.log("rollout done: reboot_room.enable()");
reboot.enable();
await new Promise((r) => setTimeout(r, 10));
await client.close();

at start: get_room_status, reboot_room
firmware rollout begins: reboot_room.disable()
  ← notifications/tools/list_changed; host re-lists: get_room_status
calling it anyway: true MCP error -32602: Tool reboot_room disabled
rollout done: reboot_room.enable()
  ← notifications/tools/list_changed; host re-lists: get_room_status, reboot_room

$ npm test

> room-tools@1.0.0 test
> node --test

▶ room-tools over MCP
  ✔ lists exactly the tools we mean to publish (8.809042ms)
  ✔ returns structured status for a known room (1.937834ms)
  ✔ answers an unknown room with a tool error that names the valid ids (0.361208ms)
  ✔ rejects a missing argument before the handler runs (0.542875ms)
✔ room-tools over MCP (23.439083ms)
✔ starts as a host would start it, and answers over stdio (172.330292ms)
✔ tool surface (21.4785ms)
ℹ tests 6
ℹ suites 1
ℹ pass 6
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 326.912875

// room-tools' protocol tests in one file. In the project they live in test/server.test.mjs and run with `node --test`.
import { describe, it, before, after, run } from "node:test";
import assert from "node:assert/strict";
import { fileURLToPath } from "node:url";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { z } from "zod";

// ---- src/server.mjs (trimmed): the factory under test ----
function createServer({ rooms }) {
  const server = new McpServer({ name: "room-tools", version: "0.2.0" });
  server.registerTool("get_room_status", {
    description: "Live status of one meeting-room device: in a call or not, camera, mic and firmware version.",
    inputSchema: { roomId: z.string() },
    outputSchema: { roomId: z.string(), inCall: z.boolean(), firmware: z.string() },
    annotations: { readOnlyHint: true },
  }, async ({ roomId }) => {
    const room = await rooms.get(roomId);
    if (!room) return { isError: true, content: [{ type: "text", text: `No room called ${roomId}. Known rooms: ${(await rooms.list()).join(", ")}.` }] };
    return { content: [{ type: "text", text: JSON.stringify(room) }], structuredContent: room };
  });
  return server;
}
const fakeRooms = (data) => ({ list: async () => Object.keys(data), get: async (id) => (data[id] ? { roomId: id, ...data[id] } : undefined) });

// ---- test/server.test.mjs ----
async function connect(rooms) {
  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
  await createServer({ rooms }).connect(serverSide);
  const client = new Client({ name: "test", version: "0.0.0" });
  await client.connect(clientSide);
  return client;
}

if (process.env.NODE_TEST_CONTEXT) describe("room-tools over MCP", () => {
  let client;
  before(async () => (client = await connect(fakeRooms({ "huddle-2": { inCall: true, firmware: "4.3.1" } }))));
  after(() => client.close());

  it("publishes get_room_status as read-only", async () => {
    const [tool] = (await client.listTools()).tools;
    assert.equal(tool.name, "get_room_status");
    assert.equal(tool.annotations.readOnlyHint, true);
  });
  it("returns structured status", async () => {
    const r = await client.callTool({ name: "get_room_status", arguments: { roomId: "huddle-2" } });
    assert.deepEqual(r.structuredContent, { roomId: "huddle-2", inCall: true, firmware: "4.3.1" });
  });
  it("tells the model which rooms exist", async () => {
    const r = await client.callTool({ name: "get_room_status", arguments: { roomId: "lobby" } });
    assert.equal(r.isError, true);
    assert.match(r.content[0].text, /Known rooms: huddle-2/);
  });
  it("catches a bad shape from the data layer", async () => {
    const broken = await connect(fakeRooms({ "huddle-2": { inCall: "yes", firmware: "4.3.1" } }));
    const r = await broken.callTool({ name: "get_room_status", arguments: { roomId: "huddle-2" } });
    assert.equal(r.isError, true, "outputSchema should catch inCall: 'yes'");
    await broken.close();
  });
  it("deliberately failing: board-1 is not in this fake", async () => {
    const r = await client.callTool({ name: "get_room_status", arguments: { roomId: "board-1" } });
    assert.equal(r.isError, undefined, r.content[0].text);
  });
});
else {
  // Not part of a real test file: print node:test's results without its timings, so this page's output is stable.
  for await (const { type, data } of run({ files: [fileURLToPath(import.meta.url)] })) {
    if (type === "test:pass" && data.details.type !== "suite") console.log(`✔ ${data.name}`);
    if (type === "test:fail" && data.details.type !== "suite") console.log(`✖ ${data.name}\n    ${data.details.error.cause.message.split("\n")[0]}`);
  }
}

✔ publishes get_room_status as read-only
✔ returns structured status
✔ tells the model which rooms exist
✔ catches a bad shape from the data layer
✖ deliberately failing: board-1 is not in this fake
    No room called board-1. Known rooms: huddle-2.

import { it } from "node:test";
import assert from "node:assert/strict";
import { fileURLToPath } from "node:url";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const entry = fileURLToPath(new URL("../src/stdio.mjs", import.meta.url));

it("starts as a host would start it, and answers over stdio", async () => {
  const transport = new StdioClientTransport({ command: process.execPath, args: [entry], stderr: "pipe" });
  let stderr = "";
  transport.stderr.on("data", (d) => (stderr += d));
  const client = new Client({ name: "e2e", version: "0.0.0" });
  await client.connect(transport);
  let result;
  try {
    result = await client.callTool({ name: "list_rooms", arguments: {} });
  } finally {
    await client.close(); // ends stdin; waits for the process to exit
  }
  assert.deepEqual(result.structuredContent, { roomIds: ["huddle-2", "board-1"] });
  assert.match(stderr, /ready on stdio/); // the log went to stderr, not into the protocol
});

import { test } from "node:test";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { createServer } from "../src/server.mjs";
import { createFakeRooms } from "../src/rooms.mjs";

// The tool list is everything the model knows about this server. Changing it should be a reviewed decision.
test("tool surface", async (t) => {
  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
  await createServer({ rooms: createFakeRooms() }).connect(serverSide);
  const client = new Client({ name: "snapshot", version: "0.0.0" });
  await client.connect(clientSide);
  const { tools } = await client.listTools();
  await client.close();
  t.assert.snapshot(tools);
});

$ npx mcp-inspector --cli node server.mjs --method tools/list
room-tools 0.1.0 ready on stdio
{
  "tools": [
    {
      "name": "get_room_status",
      "title": "Get room status",
      "description": "Live status of one meeting-room device: in a call or not, camera, mic and firmware version. Read-only. Room ids look like huddle-2 or board-1.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "roomId": {
            "type": "string",
            "description": "Room id, for example huddle-2"
          }
        },
        "required": [
          "roomId"
        ],
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "annotations": {
        "readOnlyHint": true
      },
      "execution": {
        "taskSupport": "forbidden"
      }
    }
  ]
}
$ npx mcp-inspector --cli node server.mjs --method tools/call --tool-name get_room_status --tool-arg roomId=lobby
room-tools 0.1.0 ready on stdio
{
  "content": [
    {
      "type": "text",
      "text": "No room called lobby. Known rooms: huddle-2, board-1."
    }
  ],
  "isError": true
}
{"error":{"code":"tool_is_error","message":"Tool 'get_room_status' returned isError:true."}}
$ echo $?
5

#!/bin/sh
# Smoke test: start the real entry point over stdio, check the tool list and one call.
set -eu
inspect() { npx --no-install mcp-inspector --cli -q --format json node src/stdio.mjs "$@"; }

inspect --method tools/list | jq -e '[.result.tools[].name] | sort == ["get_room_status","list_rooms"]' >/dev/null
inspect --method tools/call --tool-name get_room_status --tool-arg roomId=huddle-2 \
  | jq -e '.result.structuredContent.firmware == "4.3.1"' >/dev/null

status=0
inspect --method tools/call --tool-name get_room_status --tool-arg roomId=lobby >/dev/null 2>&1 || status=$?
[ "$status" -eq 5 ] || { echo "expected exit 5 (tool error) for an unknown room, got $status"; exit 1; }
echo "smoke: ok"

name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: "24"
          cache: npm
      - run: npm ci
      - name: Protocol and stdio tests
        run: npm test
      - name: Smoke test with the MCP Inspector CLI
        run: npm run smoke

{
  "mcpServers": {
    "room-tools": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/you/code/room-tools/src/stdio.mjs"],
      "env": {
        "ROOMS_API_URL": "https://rooms.example.test"
      }
    }
  }
}

{
  "mcpServers": {
    "room-tools": {
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR:-.}/src/stdio.mjs"],
      "env": {
        "ROOMS_API_URL": "${ROOMS_API_URL:-https://rooms.example.test}",
        "ROOMS_API_TOKEN": "${ROOMS_API_TOKEN}"
      }
    }
  }
}

# Everything after -- is the server's own command line.
claude mcp add --env ROOMS_API_URL=https://rooms.example.test --transport stdio --scope project \
  room-tools -- node src/stdio.mjs

claude mcp list            # status of every configured server
claude mcp get room-tools  # one server's details and any connection issue

$ claude mcp add --env ROOMS_API_URL=https://rooms.example.test --transport stdio --scope project room-tools -- node src/stdio.mjs
Added stdio MCP server room-tools with command: node src/stdio.mjs to project config
File modified: …/room-tools/.mcp.json
$ claude mcp list
Checking MCP server health…

room-tools: node src/stdio.mjs - ⏸ Pending approval (run `claude` to approve)
$ claude mcp get room-tools
room-tools:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: stdio
  Command: node
  Args: src/stdio.mjs
  Environment:
    ROOMS_API_URL=https://rooms.example.test

To remove this server, run: claude mcp remove room-tools -s project

// What a host does with an "mcpServers" config at startup, using the SDK's own stdio client.
import { fileURLToPath } from "node:url";

if (process.argv[2] === "serve") {
  const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
  const server = new McpServer({ name: "room-tools", version: "0.2.0" });
  server.registerTool("list_rooms", { description: "Ids of every meeting room" }, async () => ({ content: [{ type: "text", text: "huddle-2, board-1" }] }));
  await server.connect(new StdioServerTransport());
  console.error(`cwd=${process.cwd()} ROOMS_API_URL=${process.env.ROOMS_API_URL ?? "(unset)"} ROOMS_API_TOKEN=${process.env.ROOMS_API_TOKEN ? "(set)" : "(unset)"}`);
} else {
  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
  const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
  process.env.ROOMS_API_TOKEN = "secret-in-the-host-env"; // the host has it; will the server?

  const self = fileURLToPath(import.meta.url);
  const config = {
    mcpServers: {
      "room-tools": { command: process.execPath, args: [self, "serve"], env: { ROOMS_API_URL: "https://rooms.example.test" }, cwd: "/" },
      "typo-in-path": { command: process.execPath, args: ["/Users/me/room-tool/src/stdio.mjs"] },
      "not-installed": { command: "room-tools-cli" },
    },
  };

  for (const [name, entry] of Object.entries(config.mcpServers)) {
    const transport = new StdioClientTransport({ ...entry, stderr: "pipe" });
    let log = ""; // what Claude Desktop keeps in mcp-server-<name>.log
    transport.stderr.on("data", (d) => (log += d));
    const client = new Client({ name: "toy-host", version: "1.0.0" });
    try {
      await client.connect(transport, { timeout: 5000 });
      const { tools } = await client.listTools();
      console.log(`${name}: connected, ${tools.length} tool(s): ${tools.map((t) => t.name).join(", ")}`);
    } catch (e) {
      console.log(`${name}: FAILED: ${e.message}`);
    } finally {
      await client.close();
    }
    const lines = log.trim().split("\n");
    const shown = lines.find((l) => l.startsWith("Error")) ?? lines[0];
    if (shown) console.log(`  log | ${shown}`);
  }
}

room-tools: connected, 1 tool(s): list_rooms
  log | cwd=/ ROOMS_API_URL=https://rooms.example.test ROOMS_API_TOKEN=(unset)
typo-in-path: FAILED: MCP error -32000: Connection closed
  log | Error: Cannot find module '/Users/me/room-tool/src/stdio.mjs'
not-installed: FAILED: spawn room-tools-cli ENOENT

// When the host disconnects, does the server exit by itself? A background timer can keep it alive.
import { fileURLToPath } from "node:url";

if (process.argv[2] === "serve") {
  const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
  const server = new McpServer({ name: "room-tools", version: "0.2.0" });
  const poll = setInterval(() => {}, 1000); // e.g. refresh a device cache every second
  const shutdown = async (why) => {
    console.error(`shutting down: ${why}`);
    clearInterval(poll);
    await server.close();
    process.exit(0);
  };
  if (process.argv[3] === "handles-stdin-end") process.stdin.on("end", () => shutdown("stdin closed"));
  process.on("SIGTERM", () => shutdown("SIGTERM"));
  process.on("SIGINT", () => shutdown("SIGINT"));
  await server.connect(new StdioServerTransport());
} else {
  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
  const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
  for (const variant of ["timer-only", "handles-stdin-end"]) {
    const transport = new StdioClientTransport({ command: process.execPath, args: [fileURLToPath(import.meta.url), "serve", variant], stderr: "pipe" });
    let log = "";
    transport.stderr.on("data", (d) => (log += d));
    const client = new Client({ name: "host", version: "1.0.0" });
    await client.connect(transport);
    const started = performance.now();
    await client.close(); // SDK client: end stdin, wait up to 2 s, then SIGTERM, then SIGKILL
    const seconds = (performance.now() - started) / 1000;
    console.log(`${variant.padEnd(18)} ${log.trim()} (${seconds < 1 ? "under 1 s" : "about 2 s"})`);
  }
}

timer-only         shutting down: SIGTERM (about 2 s)
handles-stdin-end  shutting down: stdin closed (under 1 s)