tiny-stdio-mcp-test-server 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,46 @@
+# tiny-stdio-mcp-test-server
+
+A deterministic MCP server for testing your MCP client integration end-to-end — no real APIs, no flaky responses. Every call returns the same predictable output, so you can assert with confidence.
+
+Built on [tiny-stdio-mcp-server](https://www.npmjs.com/package/tiny-stdio-mcp-server).
+
+## Quick start
+
+```sh
+npx tiny-stdio-mcp-test-server serve encrypt
+npx tiny-stdio-mcp-test-server serve word-of-the-day
+```
+
+## Configure with an MCP client
+
+Add to your agent's MCP config (e.g. Claude Code's `~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "test": {
+      "command": "npx",
+      "args": ["tiny-stdio-mcp-test-server", "serve", "word-of-the-day"]
+    }
+  }
+}
+```
+
+## Available tools
+
+| Tool | Description | Expected output |
+|------|-------------|-----------------|
+| `caesar_cipher_encrypt` | Caesar cipher (`text`, optional `shift`) | `"hello"` → `"khoor"` |
+| `word_of_the_day` | Fixed word of the day (no params) | `"Bumfuzzle - to confuse or fluster someone"` |
+
+## What to assert
+
+- **Tool discovery:** your client can list tools with correct names, descriptions, and JSON Schema
+- **Deterministic output:** `caesar_cipher_encrypt({ text: "hello" })` always returns `"khoor"`
+- **Optional parameters:** `caesar_cipher_encrypt({ text: "abc", shift: 1 })` returns `"bcd"`
+- **Zero-arg tools:** `word_of_the_day({})` always returns `"Bumfuzzle - to confuse or fluster someone"`
+- **Content format:** results are always `[{ type: "text", text: "..." }]`
+
+## License
+
+MIT

package/dist/cli.js

@@ -1,20 +1,33 @@
 #!/usr/bin/env node
 import { Command } from "commander";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { access } from "node:fs/promises";
+import packageJson from "../package.json" with { type: "json" };
 import { createEncryptServer, createWordOfTheDayServer, } from "./index.js";
 const program = new Command();
 program
     .name("tiny-stdio-mcp-test-server")
     .description("Test MCP server with example tools for integration testing")
-    .version("0.0.1");
+    .version(packageJson.version);
 program
     .command("serve")
     .description("Start an MCP server on stdin/stdout")
     .argument("<tool>", "Tool to serve (encrypt, word-of-the-day)")
     .action(async (tool) => {
-    const servers = {
+    recordProcessStart();
+    const startupDelayMs = Number(process.env.TOOLCRAFT_TEST_STARTUP_DELAY_MS ?? "0");
+    if (startupDelayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, startupDelayMs));
+    }
+    const startupGateFile = process.env.TOOLCRAFT_TEST_STARTUP_GATE_FILE;
+    if (startupGateFile !== undefined) {
+        await waitForFile(startupGateFile);
+    }
+    const servers = Object.create(null);
+    Object.assign(servers, {
         encrypt: () => createEncryptServer().listen(),
         "word-of-the-day": () => createWordOfTheDayServer().listen(),
-    };
+    });
     const start = servers[tool];
     if (!start) {
         const available = Object.keys(servers).join(", ");
@@ -24,3 +37,27 @@ program
     await start();
 });
 program.parse();
+function recordProcessStart() {
+    const countFile = process.env.TOOLCRAFT_TEST_SPAWN_COUNT_FILE;
+    if (countFile !== undefined) {
+        const previousCount = existsSync(countFile)
+            ? Number.parseInt(readFileSync(countFile, "utf8").trim() || "0", 10)
+            : 0;
+        writeFileSync(countFile, String(previousCount + 1));
+    }
+    const pidFile = process.env.TOOLCRAFT_TEST_WRAPPER_PID_FILE;
+    if (pidFile !== undefined) {
+        writeFileSync(pidFile, String(process.pid));
+    }
+}
+async function waitForFile(filePath) {
+    while (true) {
+        try {
+            await access(filePath);
+            return;
+        }
+        catch {
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+    }
+}

package/dist/index.js

@@ -1,4 +1,8 @@
 import { createServer, defineSchema } from "tiny-stdio-mcp-server";
+import { appendFileSync } from "node:fs";
+import packageJson from "../package.json" with { type: "json" };
+const SERVER_NAME = "tiny-stdio-mcp-test-server";
+const SERVER_VERSION = packageJson.version;
 const caesarCipherSchema = defineSchema({
     text: { type: "string", description: "The text to encrypt" },
     shift: {
@@ -8,14 +12,18 @@ const caesarCipherSchema = defineSchema({
     },
 });
 export function caesarEncrypt(text, shift) {
+    if (!Number.isInteger(shift)) {
+        throw new Error("Caesar cipher shift must be a finite integer");
+    }
+    const normalizedShift = ((shift % 26) + 26) % 26;
     return text
         .split("")
         .map((char) => {
         if (char >= "a" && char <= "z") {
-            return String.fromCharCode(((char.charCodeAt(0) - 97 + shift) % 26) + 97);
+            return String.fromCharCode(((char.charCodeAt(0) - 97 + normalizedShift) % 26) + 97);
         }
         if (char >= "A" && char <= "Z") {
-            return String.fromCharCode(((char.charCodeAt(0) - 65 + shift) % 26) + 65);
+            return String.fromCharCode(((char.charCodeAt(0) - 65 + normalizedShift) % 26) + 65);
         }
         return char;
     })
@@ -24,25 +32,32 @@ export function caesarEncrypt(text, shift) {
 const wordOfTheDaySchema = defineSchema({});
 export function createEncryptServer() {
     return createServer({
-        name: "tiny-stdio-mcp-test-server",
-        version: "0.0.1",
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
     }).tool("caesar_cipher_encrypt", "Encrypts text using the Caesar cipher", caesarCipherSchema, ({ text, shift }) => {
+        recordToolCall("caesar_cipher_encrypt");
         const actualShift = shift ?? 3;
         return caesarEncrypt(text, actualShift);
     });
 }
+function recordToolCall(name) {
+    const filePath = process.env.TOOLCRAFT_TEST_TOOL_CALL_FILE;
+    if (filePath !== undefined) {
+        appendFileSync(filePath, `${name}\n`);
+    }
+}
 export function createWordOfTheDayServer() {
     return createServer({
-        name: "tiny-stdio-mcp-test-server",
-        version: "0.0.1",
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
     }).tool("word_of_the_day", "Returns the word of the day", wordOfTheDaySchema, () => {
         return "Bumfuzzle - to confuse or fluster someone";
     });
 }
 export function createTestServer() {
     const server = createServer({
-        name: "tiny-stdio-mcp-test-server",
-        version: "0.0.1",
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
     });
     server.tool("caesar_cipher_encrypt", "Encrypts text using the Caesar cipher", caesarCipherSchema, ({ text, shift }) => {
         const actualShift = shift ?? 3;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-stdio-mcp-test-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Test MCP server with example tools for integration testing",
   "type": "module",
   "main": "dist/index.js",
@@ -15,14 +15,15 @@
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node ../../scripts/guard-package-dist.mjs && tsc",
+    "prepack": "node ../../scripts/set-bin-executable.mjs",
     "prepublishOnly": "tsc"
   },
   "files": [
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "repository": {
     "type": "git",
@@ -37,7 +38,7 @@
     "server"
   ],
   "dependencies": {
-    "tiny-stdio-mcp-server": "*",
+    "tiny-stdio-mcp-server": "^0.1.0",
     "commander": "^14.0.3"
   },
   "devDependencies": {