@sriramadari/mcp-devkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sriramadari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# mcp-devkit
+
+A **zero-dependency testing & inspection toolkit for [Model Context Protocol](https://modelcontextprotocol.io) servers** — the things you reach for when you want to actually *test* an MCP server instead of clicking around an inspector:
+
+- 🔌 **In-memory & stdio test clients** — connect to an `McpServer` you built (no child process, no network) or launch any server binary over stdio
+- ✅ **Fluent, framework-agnostic assertions** — `expectToolResult(res).toSucceed().toHaveText(/…/).toMatchStructured({…})` — works in vitest, jest, or `node:test`
+- 🛡️ **Client-side input validation** — bad arguments fail loudly in your test (against the tool's own `inputSchema`) instead of silently in the server
+- 🧪 **Automated conformance checker** — catches the mistakes that make a server hard for an LLM to use: missing descriptions, malformed schemas, duplicate/illegal tool names, a server that crashes on an unknown tool
+- 🔎 **A CLI** — `inspect`, `check`, and `call` any stdio MCP server without writing a script
+
+The only runtime peer dependency is the MCP SDK itself.
+
+```bash
+npm install -D mcp-devkit
+# the MCP SDK is a peer dependency — install it if you haven't:
+npm install @modelcontextprotocol/sdk
+```
+
+> Requires Node ≥ 18 and `@modelcontextprotocol/sdk` ≥ 1.10. ESM + CJS, fully typed.
+
+---
+
+## Testing your own server (in-memory)
+
+No child process, no ports — the client and server talk over an in-process transport.
+
+```ts
+import { describe, it, beforeAll, afterAll, expect } from "vitest";
+import { createTestClient, expectToolResult, conformanceCheck } from "mcp-devkit";
+import { buildMyServer } from "../src/server"; // returns an McpServer
+
+let client;
+beforeAll(async () => { client = await createTestClient({ server: buildMyServer() }); });
+afterAll(async () => { await client.close(); });
+
+it("returns a forecast", async () => {
+  const res = await client.call("get_forecast", { city: "Paris", days: 3 });
+  expectToolResult(res)
+    .toSucceed()
+    .toHaveText(/Paris/)
+    .toMatchStructured({ city: "Paris", summary: "sunny" });
+});
+
+it("is well-formed", async () => {
+  expect((await conformanceCheck(client)).ok).toBe(true);
+});
+```
+
+`{ server }` also accepts a **factory** (`() => McpServer | Promise<McpServer>`) so each test gets a fresh instance.
+
+Prefer automatic cleanup? Use `withTestClient`, which always closes — even if the body throws:
+
+```ts
+import { withTestClient, expectToolResult } from "mcp-devkit";
+
+await withTestClient({ server: buildMyServer() }, async (client) => {
+  expectToolResult(await client.call("ping")).toSucceed();
+});
+```
+
+## Testing a server over stdio
+
+Point the client at a command; it's spawned as a child process and torn down on `close()`.
+
+```ts
+const client = await createTestClient({
+  command: "node",
+  args: ["dist/server.js"],
+  // env, cwd also supported
+});
+```
+
+---
+
+## The CLI
+
+Everything after `--` is the MCP server command to launch over stdio.
+
+```bash
+# Dump tools / resources / prompts (add --json for machine output)
+npx mcp-devkit inspect -- node dist/server.js
+
+# Run the conformance battery (exit code 1 if an error-severity check fails)
+npx mcp-devkit check -- npx -y @modelcontextprotocol/server-everything
+
+# Call a single tool
+npx mcp-devkit call --tool search --args '{"q":"mcp"}' -- node dist/server.js
+```
+
+`check` output:
+
+```
+✓ Server reports a name and version
+✓ tools/list responds  — 4 tool(s)
+✓ Tool names are unique
+✓ Tool names use a safe charset and length
+! Every tool has a description  — an LLM picks tools by their description
+    • legacy_export
+✓ Calling an unknown tool fails gracefully (no crash/hang)
+
+FAIL  6 passed, 1 failed, 0 skipped
+```
+
+---
+
+## API
+
+### `createTestClient(target, options?) → Promise<TestClient>`
+
+`target` is `{ server }` (in-memory) or `{ command, args?, env?, cwd? }` (stdio).
+`options`: `{ clientName?, clientVersion?, timeoutMs? }` (default timeout 10s).
+
+#### `TestClient`
+
+| Method | Description |
+| --- | --- |
+| `tools()` / `toolNames()` | List tools (cached; `refresh()` to re-fetch) |
+| `hasTool(name)` / `tool(name)` | Lookup helpers |
+| `call(name, args?, opts?)` | Call a tool. Validates `args` against the tool's `inputSchema` by default — pass `{ validate: false }` to skip, `{ timeoutMs }` to override |
+| `resources()` / `readResource(uri)` | Resources (empty list if unsupported) |
+| `prompts()` / `getPrompt(name, args?)` | Prompts (empty list if unsupported) |
+| `serverInfo()` / `capabilities()` | Server identity & advertised capabilities |
+| `ping()` | Liveness check |
+| `raw` | The underlying SDK `Client` — escape hatch |
+| `close()` | Tear down (idempotent) |
+
+### `expectToolResult(result) → ToolResultAssertion`
+
+Chainable, throws a plain `Error` on failure:
+
+`toSucceed()` · `toError()` / `toFail()` · `toHaveText(string | RegExp)` · `toHaveContentType(type)` · `toHaveContentCount(n)` · `toSatisfy(fn)` · `toMatchStructured(partial)` · `toMatchSchema(jsonSchema)` — plus terminal getters `text()`, `json<T>()`, `raw()`.
+
+### `conformanceCheck(client, options?) → Promise<ConformanceReport>`
+
+Runs the best-practices battery (see `listChecks()` for the full catalogue). `report.ok` is `true` unless an **error**-severity check fails. `options`: `{ skip?: string[], probeUnknownTool?: boolean }`.
+
+| Check | Severity |
+| --- | --- |
+| `server-identity` | warning |
+| `tools-listable` | error |
+| `unique-tool-names` | error |
+| `valid-tool-names` | error |
+| `tool-descriptions` | warning |
+| `description-quality` | info |
+| `tool-input-schema` | warning |
+| `required-props-exist` | error |
+| `unknown-tool-handled` | error |
+
+### `validateAgainstSchema(value, jsonSchema) → { valid, errors }`
+
+A small, dependency-free JSON Schema validator covering the subset MCP tools use (types, `required`, `enum`, nested objects/arrays, numeric/string bounds, `anyOf`/`oneOf`/`allOf`, `additionalProperties`). Returns **every** error, not just the first.
+
+### `mockServer(spec) → McpServer`
+
+Build a throwaway server for fixtures. Input schemas are passed straight to the SDK's `registerTool`, so they take a Zod raw-shape:
+
+```ts
+import { z } from "zod";
+import { mockServer, createTestClient } from "mcp-devkit";
+
+const server = mockServer({
+  name: "demo",
+  tools: [{
+    name: "echo",
+    description: "Echo the message back",
+    inputSchema: { message: z.string() },
+    handler: ({ message }) => `you said: ${message}`,
+  }],
+});
+
+const client = await createTestClient({ server });
+```
+
+A handler returns either a string (wrapped as one text block) or `{ content?, isError?, structuredContent? }`.
+
+---
+
+## License
+
+MIT © sriramadari

package/dist/chunk-EANYYOGZ.js

@@ -0,0 +1,437 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+// src/connect.ts
+async function openConnection(target, options = {}) {
+  const client = new Client({
+    name: options.clientName ?? "mcp-devkit",
+    version: options.clientVersion ?? "0.1.0"
+  });
+  if ("server" in target && target.server) {
+    const server = typeof target.server === "function" ? await target.server() : target.server;
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    return {
+      client,
+      close: async () => {
+        await client.close().catch(() => {
+        });
+        await server.close().catch(() => {
+        });
+      }
+    };
+  }
+  if ("command" in target && target.command) {
+    const transport = new StdioClientTransport({
+      command: target.command,
+      args: target.args ?? [],
+      env: target.env,
+      cwd: target.cwd
+    });
+    await client.connect(transport);
+    return {
+      client,
+      // Closing the client closes the transport, which terminates the child.
+      close: async () => {
+        await client.close().catch(() => {
+        });
+      }
+    };
+  }
+  throw new Error("openConnection: target must provide either `server` or `command`");
+}
+
+// src/schema.ts
+var TYPEOF = {
+  string: "string",
+  number: "number",
+  boolean: "boolean"
+};
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  const t = typeof value;
+  if (t === "object") return "object";
+  return TYPEOF[t] ?? "string";
+}
+function matchesType(value, type) {
+  switch (type) {
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "number":
+      return typeof value === "number";
+    case "null":
+      return value === null;
+    default:
+      return typeOf(value) === type;
+  }
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (typeof a !== "object") return false;
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every(
+    (k) => deepEqual(a[k], b[k])
+  );
+}
+function validateAgainstSchema(value, schema) {
+  const errors = [];
+  walk(value, schema, "", errors);
+  return { valid: errors.length === 0, errors };
+}
+function walk(value, schema, path, errors) {
+  if (!schema || typeof schema !== "object") return;
+  if ("const" in schema && !deepEqual(value, schema.const)) {
+    errors.push({ path: path || "/", message: `must equal ${JSON.stringify(schema.const)}` });
+  }
+  if (schema.enum && !schema.enum.some((e) => deepEqual(e, value))) {
+    errors.push({ path: path || "/", message: `must be one of ${JSON.stringify(schema.enum)}` });
+  }
+  if (schema.allOf) {
+    for (const sub of schema.allOf) walk(value, sub, path, errors);
+  }
+  if (schema.anyOf && !schema.anyOf.some((sub) => validateAgainstSchema(value, sub).valid)) {
+    errors.push({ path: path || "/", message: "did not match any schema in anyOf" });
+  }
+  if (schema.oneOf) {
+    const hits = schema.oneOf.filter((sub) => validateAgainstSchema(value, sub).valid).length;
+    if (hits !== 1) {
+      errors.push({ path: path || "/", message: `must match exactly one schema in oneOf (matched ${hits})` });
+    }
+  }
+  const types = schema.type === void 0 ? [] : Array.isArray(schema.type) ? schema.type : [schema.type];
+  if (types.length > 0 && !types.some((t) => matchesType(value, t))) {
+    errors.push({ path: path || "/", message: `expected type ${types.join(" | ")}, got ${typeOf(value)}` });
+    return;
+  }
+  const actual = typeOf(value);
+  if (actual === "string" && typeof value === "string") {
+    if (schema.minLength !== void 0 && value.length < schema.minLength) {
+      errors.push({ path: path || "/", message: `shorter than minLength ${schema.minLength}` });
+    }
+    if (schema.maxLength !== void 0 && value.length > schema.maxLength) {
+      errors.push({ path: path || "/", message: `longer than maxLength ${schema.maxLength}` });
+    }
+  }
+  if (actual === "number" && typeof value === "number") {
+    if (schema.minimum !== void 0 && value < schema.minimum) {
+      errors.push({ path: path || "/", message: `less than minimum ${schema.minimum}` });
+    }
+    if (schema.maximum !== void 0 && value > schema.maximum) {
+      errors.push({ path: path || "/", message: `greater than maximum ${schema.maximum}` });
+    }
+  }
+  if (actual === "object" && value && typeof value === "object") {
+    const obj = value;
+    for (const key of schema.required ?? []) {
+      if (!(key in obj)) {
+        errors.push({ path: `${path}/${key}`, message: "is required" });
+      }
+    }
+    if (schema.properties) {
+      for (const [key, sub] of Object.entries(schema.properties)) {
+        if (key in obj) walk(obj[key], sub, `${path}/${key}`, errors);
+      }
+    }
+    if (schema.additionalProperties === false && schema.properties) {
+      const allowed = new Set(Object.keys(schema.properties));
+      for (const key of Object.keys(obj)) {
+        if (!allowed.has(key)) {
+          errors.push({ path: `${path}/${key}`, message: "is not an allowed property" });
+        }
+      }
+    } else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+      const declared = new Set(Object.keys(schema.properties ?? {}));
+      for (const key of Object.keys(obj)) {
+        if (!declared.has(key)) {
+          walk(obj[key], schema.additionalProperties, `${path}/${key}`, errors);
+        }
+      }
+    }
+  }
+  if (actual === "array" && Array.isArray(value)) {
+    if (Array.isArray(schema.items)) {
+      schema.items.forEach((sub, i) => {
+        if (i < value.length) walk(value[i], sub, `${path}/${i}`, errors);
+      });
+    } else if (schema.items) {
+      value.forEach((item, i) => walk(item, schema.items, `${path}/${i}`, errors));
+    }
+  }
+}
+
+// src/client.ts
+var TestClient = class {
+  /** The underlying SDK client — escape hatch for anything not wrapped here. */
+  raw;
+  _close;
+  defaultTimeoutMs;
+  _tools;
+  _resources;
+  _prompts;
+  /** @internal — use {@link createTestClient}. */
+  constructor(raw, close, defaultTimeoutMs) {
+    this.raw = raw;
+    this._close = close;
+    this.defaultTimeoutMs = defaultTimeoutMs;
+  }
+  // ── server identity / capabilities ─────────────────────────────────────────
+  serverInfo() {
+    return this.raw.getServerVersion();
+  }
+  capabilities() {
+    return this.raw.getServerCapabilities();
+  }
+  // ── tools ───────────────────────────────────────────────────────────────────
+  /** List the server's tools (cached after the first call — see {@link refresh}). */
+  async tools() {
+    if (!this._tools) {
+      const res = await this.raw.listTools();
+      this._tools = res.tools ?? [];
+    }
+    return this._tools;
+  }
+  async toolNames() {
+    return (await this.tools()).map((t) => t.name);
+  }
+  async hasTool(name) {
+    return (await this.tools()).some((t) => t.name === name);
+  }
+  async tool(name) {
+    return (await this.tools()).find((t) => t.name === name);
+  }
+  /**
+   * Call a tool. By default the args are validated against the tool's declared
+   * `inputSchema` first; set `{ validate: false }` to send them as-is (e.g. to
+   * test how the server handles bad input).
+   */
+  async call(name, args = {}, options = {}) {
+    if (options.validate !== false) {
+      const info = await this.tool(name);
+      if (info?.inputSchema) {
+        const { valid, errors } = validateAgainstSchema(args, info.inputSchema);
+        if (!valid) {
+          const detail = errors.map((e) => `  ${e.path} ${e.message}`).join("\n");
+          throw new Error(`Arguments for tool "${name}" do not match its inputSchema:
+${detail}`);
+        }
+      }
+    }
+    const result = await this.raw.callTool(
+      { name, arguments: args },
+      void 0,
+      { timeout: options.timeoutMs ?? this.defaultTimeoutMs }
+    );
+    return result;
+  }
+  // ── resources ─────────────────────────────────────────────────────────────
+  async resources() {
+    if (!this._resources) {
+      try {
+        const res = await this.raw.listResources();
+        this._resources = res.resources ?? [];
+      } catch {
+        this._resources = [];
+      }
+    }
+    return this._resources;
+  }
+  async readResource(uri) {
+    return await this.raw.readResource({ uri });
+  }
+  // ── prompts ───────────────────────────────────────────────────────────────
+  async prompts() {
+    if (!this._prompts) {
+      try {
+        const res = await this.raw.listPrompts();
+        this._prompts = res.prompts ?? [];
+      } catch {
+        this._prompts = [];
+      }
+    }
+    return this._prompts;
+  }
+  async getPrompt(name, args = {}) {
+    return this.raw.getPrompt({ name, arguments: args });
+  }
+  // ── lifecycle ───────────────────────────────────────────────────────────────
+  /** Drop cached listings so the next `tools()`/`resources()`/`prompts()` re-fetches. */
+  refresh() {
+    this._tools = void 0;
+    this._resources = void 0;
+    this._prompts = void 0;
+  }
+  /** Liveness check — resolves if the server answers a ping. */
+  async ping() {
+    await this.raw.ping();
+  }
+  /** Tear down the connection (and any spawned child process). Idempotent. */
+  async close() {
+    await this._close();
+  }
+};
+async function createTestClient(target, options = {}) {
+  const { client, close } = await openConnection(target, options);
+  return new TestClient(client, close, options.timeoutMs ?? 1e4);
+}
+async function withTestClient(target, fn, options = {}) {
+  const client = await createTestClient(target, options);
+  try {
+    return await fn(client);
+  } finally {
+    await client.close();
+  }
+}
+
+// src/conformance.ts
+var TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,128}$/;
+var CHECKS = [
+  {
+    id: "server-identity",
+    title: "Server reports a name and version",
+    severity: "warning",
+    run: async ({ client }) => {
+      const info = client.serverInfo();
+      if (info?.name && info?.version) return { status: "pass" };
+      return { status: "fail", detail: `server info is ${JSON.stringify(info)}` };
+    }
+  },
+  {
+    id: "tools-listable",
+    title: "tools/list responds",
+    severity: "error",
+    run: async ({ tools }) => {
+      return { status: "pass", detail: `${tools.length} tool(s)` };
+    }
+  },
+  {
+    id: "unique-tool-names",
+    title: "Tool names are unique",
+    severity: "error",
+    run: async ({ tools }) => {
+      const seen = /* @__PURE__ */ new Set();
+      const dupes = /* @__PURE__ */ new Set();
+      for (const t of tools) {
+        if (seen.has(t.name)) dupes.add(t.name);
+        seen.add(t.name);
+      }
+      return dupes.size === 0 ? { status: "pass" } : { status: "fail", detail: "duplicate tool names", findings: [...dupes] };
+    }
+  },
+  {
+    id: "valid-tool-names",
+    title: "Tool names use a safe charset and length",
+    severity: "error",
+    run: async ({ tools }) => {
+      const bad = tools.filter((t) => !TOOL_NAME_RE.test(t.name)).map((t) => t.name);
+      return bad.length === 0 ? { status: "pass" } : { status: "fail", detail: "names must match /^[a-zA-Z0-9_-]{1,128}$/", findings: bad };
+    }
+  },
+  {
+    id: "tool-descriptions",
+    title: "Every tool has a description",
+    severity: "warning",
+    run: async ({ tools }) => {
+      const missing = tools.filter((t) => !t.description || !t.description.trim()).map((t) => t.name);
+      return missing.length === 0 ? { status: "pass" } : { status: "fail", detail: "an LLM picks tools by their description", findings: missing };
+    }
+  },
+  {
+    id: "description-quality",
+    title: "Descriptions are substantive (\u2265 12 chars)",
+    severity: "info",
+    run: async ({ tools }) => {
+      const thin = tools.filter((t) => t.description && t.description.trim().length > 0 && t.description.trim().length < 12).map((t) => `${t.name} ("${t.description.trim()}")`);
+      return thin.length === 0 ? { status: "pass" } : { status: "fail", detail: "very short descriptions hurt tool selection", findings: thin };
+    }
+  },
+  {
+    id: "tool-input-schema",
+    title: "Every tool declares an object inputSchema",
+    severity: "warning",
+    run: async ({ tools }) => {
+      const bad = tools.filter((t) => {
+        const s = t.inputSchema;
+        return !s || typeof s !== "object" || s.type !== "object";
+      }).map((t) => t.name);
+      return bad.length === 0 ? { status: "pass" } : { status: "fail", detail: 'inputSchema should be a JSON Schema with type:"object"', findings: bad };
+    }
+  },
+  {
+    id: "required-props-exist",
+    title: "Every `required` entry names a declared property",
+    severity: "error",
+    run: async ({ tools }) => {
+      const findings = [];
+      for (const t of tools) {
+        const s = t.inputSchema;
+        if (!s?.required || !s.properties) continue;
+        const props = new Set(Object.keys(s.properties));
+        for (const r of s.required) {
+          if (!props.has(r)) findings.push(`${t.name}: required "${r}" has no matching property`);
+        }
+      }
+      return findings.length === 0 ? { status: "pass" } : { status: "fail", findings };
+    }
+  },
+  {
+    id: "unknown-tool-handled",
+    title: "Calling an unknown tool fails gracefully (no crash/hang)",
+    severity: "error",
+    run: async ({ client, options }) => {
+      if (options.probeUnknownTool === false) {
+        return { status: "skip", detail: "probeUnknownTool disabled" };
+      }
+      const phantom = "__mcp_devkit_nonexistent_tool__";
+      try {
+        const res = await client.call(phantom, {}, { validate: false, timeoutMs: 5e3 });
+        return res.isError === true ? { status: "pass", detail: "returned isError result" } : { status: "fail", detail: "server returned a success result for a non-existent tool" };
+      } catch {
+        return { status: "pass", detail: "rejected with a protocol error" };
+      }
+    }
+  }
+];
+async function conformanceCheck(client, options = {}) {
+  const skip = new Set(options.skip ?? []);
+  const tools = await client.tools();
+  const checks = [];
+  for (const check of CHECKS) {
+    if (skip.has(check.id)) {
+      checks.push({ id: check.id, title: check.title, severity: check.severity, status: "skip", detail: "skipped by caller" });
+      continue;
+    }
+    try {
+      const outcome = await check.run({ client, tools, options });
+      checks.push({ id: check.id, title: check.title, severity: check.severity, ...outcome });
+    } catch (e) {
+      checks.push({
+        id: check.id,
+        title: check.title,
+        severity: check.severity,
+        status: "fail",
+        detail: `check threw: ${e.message}`
+      });
+    }
+  }
+  const summary = {
+    passed: checks.filter((c) => c.status === "pass").length,
+    failed: checks.filter((c) => c.status === "fail").length,
+    warnings: checks.filter((c) => c.status === "fail" && c.severity === "warning").length,
+    skipped: checks.filter((c) => c.status === "skip").length
+  };
+  const ok = !checks.some((c) => c.status === "fail" && c.severity === "error");
+  return { ok, checks, summary };
+}
+function listChecks() {
+  return CHECKS.map((c) => ({ id: c.id, title: c.title, severity: c.severity }));
+}
+
+export { TestClient, conformanceCheck, createTestClient, listChecks, openConnection, validateAgainstSchema, withTestClient };
+//# sourceMappingURL=chunk-EANYYOGZ.js.map
+//# sourceMappingURL=chunk-EANYYOGZ.js.map