@sriramadari/mcp-devkit 0.1.0

package/dist/index.cjs

@@ -0,0 +1,623 @@
+'use strict';
+
+var index_js = require('@modelcontextprotocol/sdk/client/index.js');
+var inMemory_js = require('@modelcontextprotocol/sdk/inMemory.js');
+var stdio_js = require('@modelcontextprotocol/sdk/client/stdio.js');
+var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
+
+// src/connect.ts
+async function openConnection(target, options = {}) {
+  const client = new index_js.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] = inMemory_js.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 stdio_js.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/expect.ts
+var ToolResultAssertion = class {
+  constructor(result) {
+    this.result = result;
+    if (!result || !Array.isArray(result.content)) {
+      throw new Error(
+        "expectToolResult: value is not an MCP tool result (missing `content` array)"
+      );
+    }
+  }
+  result;
+  /** The text of all `type: "text"` content blocks, joined by newlines. */
+  text() {
+    return this.result.content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n");
+  }
+  /** Parse the joined text content as JSON. Throws if it isn't valid JSON. */
+  json() {
+    const text = this.text();
+    try {
+      return JSON.parse(text);
+    } catch (e) {
+      throw new Error(`expected tool result text to be JSON, but parsing failed: ${e.message}
+--- text ---
+${text}`);
+    }
+  }
+  /** The raw result, for assertions the matchers don't cover. */
+  raw() {
+    return this.result;
+  }
+  // ── success / failure ───────────────────────────────────────────────────────
+  /** Asserts the tool did NOT report an error (`isError` is not true). */
+  toSucceed() {
+    if (this.result.isError === true) {
+      throw new Error(`expected tool result to succeed, but isError=true
+--- content ---
+${this.text()}`);
+    }
+    return this;
+  }
+  /** Asserts the tool reported an error (`isError === true`). */
+  toError() {
+    if (this.result.isError !== true) {
+      throw new Error(`expected tool result to be an error (isError=true), but it succeeded
+--- content ---
+${this.text()}`);
+    }
+    return this;
+  }
+  /** Alias for {@link toError}. */
+  toFail() {
+    return this.toError();
+  }
+  // ── content ─────────────────────────────────────────────────────────────────
+  /** Asserts the joined text content contains a substring, or matches a RegExp. */
+  toHaveText(expected) {
+    const text = this.text();
+    const ok = typeof expected === "string" ? text.includes(expected) : expected.test(text);
+    if (!ok) {
+      throw new Error(`expected tool text to ${typeof expected === "string" ? `contain "${expected}"` : `match ${expected}`}, got:
+${text}`);
+    }
+    return this;
+  }
+  /** Asserts there is at least one content block of the given type. */
+  toHaveContentType(type) {
+    if (!this.result.content.some((b) => b.type === type)) {
+      const seen = [...new Set(this.result.content.map((b) => b.type))].join(", ") || "(none)";
+      throw new Error(`expected a content block of type "${type}", but saw: ${seen}`);
+    }
+    return this;
+  }
+  /** Asserts the number of content blocks. */
+  toHaveContentCount(n) {
+    if (this.result.content.length !== n) {
+      throw new Error(`expected ${n} content block(s), got ${this.result.content.length}`);
+    }
+    return this;
+  }
+  /** Asserts at least one content block satisfies the predicate. */
+  toSatisfy(predicate, message = "predicate") {
+    if (!this.result.content.some(predicate)) {
+      throw new Error(`expected at least one content block to satisfy ${message}`);
+    }
+    return this;
+  }
+  // ── structured content ──────────────────────────────────────────────────────
+  /**
+   * Asserts `structuredContent` deep-contains the given partial object.
+   * (Recursive subset match — extra keys on the actual value are fine.)
+   */
+  toMatchStructured(expected) {
+    const actual = this.result.structuredContent;
+    const miss = subsetMismatch(actual, expected, "");
+    if (miss) {
+      throw new Error(`structuredContent mismatch at ${miss.path}: ${miss.message}
+--- actual ---
+${JSON.stringify(actual, null, 2)}`);
+    }
+    return this;
+  }
+  /** Asserts `structuredContent` validates against a JSON Schema. */
+  toMatchSchema(schema) {
+    const { valid, errors } = validateAgainstSchema(this.result.structuredContent, schema);
+    if (!valid) {
+      const detail = errors.map((e) => `  ${e.path} ${e.message}`).join("\n");
+      throw new Error(`structuredContent does not match schema:
+${detail}`);
+    }
+    return this;
+  }
+};
+function subsetMismatch(actual, expected, path) {
+  if (expected !== null && typeof expected === "object" && !Array.isArray(expected)) {
+    if (actual === null || typeof actual !== "object" || Array.isArray(actual)) {
+      return { path: path || "/", message: `expected an object, got ${actual === null ? "null" : Array.isArray(actual) ? "array" : typeof actual}` };
+    }
+    for (const [k, v] of Object.entries(expected)) {
+      const sub = subsetMismatch(actual[k], v, `${path}/${k}`);
+      if (sub) return sub;
+    }
+    return null;
+  }
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) return { path: path || "/", message: `expected an array, got ${typeof actual}` };
+    if (actual.length !== expected.length) return { path: path || "/", message: `expected length ${expected.length}, got ${actual.length}` };
+    for (let i = 0; i < expected.length; i++) {
+      const sub = subsetMismatch(actual[i], expected[i], `${path}/${i}`);
+      if (sub) return sub;
+    }
+    return null;
+  }
+  if (actual !== expected) {
+    return { path: path || "/", message: `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}` };
+  }
+  return null;
+}
+function expectToolResult(result) {
+  return new ToolResultAssertion(result);
+}
+
+// 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 }));
+}
+function normalize(ret) {
+  if (typeof ret === "string") {
+    return { content: [{ type: "text", text: ret }] };
+  }
+  return {
+    content: ret.content ?? [{ type: "text", text: "" }],
+    isError: ret.isError,
+    structuredContent: ret.structuredContent
+  };
+}
+function mockServer(spec = {}) {
+  const server = new mcp_js.McpServer(
+    { name: spec.name ?? "mock-server", version: spec.version ?? "0.0.0" },
+    { capabilities: { tools: {} } }
+  );
+  for (const tool of spec.tools ?? []) {
+    const config = {};
+    if (tool.description) config.description = tool.description;
+    if (tool.title) config.title = tool.title;
+    if (tool.inputSchema) config.inputSchema = tool.inputSchema;
+    if (tool.annotations) config.annotations = tool.annotations;
+    const cb = async (argsOrExtra) => {
+      const args = (tool.inputSchema ? argsOrExtra : {}) ?? {};
+      return normalize(await tool.handler(args));
+    };
+    server.registerTool(
+      tool.name,
+      config,
+      cb
+    );
+  }
+  return server;
+}
+
+exports.TestClient = TestClient;
+exports.ToolResultAssertion = ToolResultAssertion;
+exports.conformanceCheck = conformanceCheck;
+exports.createTestClient = createTestClient;
+exports.expectToolResult = expectToolResult;
+exports.listChecks = listChecks;
+exports.mockServer = mockServer;
+exports.openConnection = openConnection;
+exports.validateAgainstSchema = validateAgainstSchema;
+exports.withTestClient = withTestClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map