@sriramadari/mcp-devkit 0.1.0

package/dist/cli.cjs

@@ -0,0 +1,619 @@
+#!/usr/bin/env node
+'use strict';
+
+var util = require('util');
+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');
+
+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);
+}
+
+// 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((c2) => c2.status === "pass").length,
+    failed: checks.filter((c2) => c2.status === "fail").length,
+    warnings: checks.filter((c2) => c2.status === "fail" && c2.severity === "warning").length,
+    skipped: checks.filter((c2) => c2.status === "skip").length
+  };
+  const ok = !checks.some((c2) => c2.status === "fail" && c2.severity === "error");
+  return { ok, checks, summary };
+}
+
+// src/cli.ts
+var useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+var c = {
+  dim: (s) => useColor ? `\x1B[2m${s}\x1B[0m` : s,
+  bold: (s) => useColor ? `\x1B[1m${s}\x1B[0m` : s,
+  green: (s) => useColor ? `\x1B[32m${s}\x1B[0m` : s,
+  yellow: (s) => useColor ? `\x1B[33m${s}\x1B[0m` : s,
+  red: (s) => useColor ? `\x1B[31m${s}\x1B[0m` : s,
+  cyan: (s) => useColor ? `\x1B[36m${s}\x1B[0m` : s
+};
+var USAGE = `${c.bold("mcp-devkit")} \u2014 testing & inspection toolkit for MCP servers
+
+${c.bold("Usage:")}
+  mcp-devkit inspect -- <command...>
+  mcp-devkit check   -- <command...>
+  mcp-devkit call --tool <name> [--args <json>] [--no-validate] -- <command...>
+
+${c.bold("Examples:")}
+  mcp-devkit inspect -- node dist/server.js
+  mcp-devkit check   -- npx -y @modelcontextprotocol/server-everything
+  mcp-devkit call --tool search --args '{"q":"mcp"}' -- node dist/server.js
+
+${c.bold("Options:")}
+  --tool <name>      tool to call (call command)
+  --args <json>      JSON arguments object for the tool (default {})
+  --no-validate      skip client-side inputSchema validation on call
+  --json             machine-readable JSON output (inspect / check)
+  --timeout <ms>     per-request timeout (default 15000)
+  -h, --help         show this help
+
+Everything after ${c.bold("--")} is the MCP server command to launch over stdio.
+`;
+function splitOnDoubleDash(argv) {
+  const i = argv.indexOf("--");
+  if (i === -1) return { flags: argv, command: [] };
+  return { flags: argv.slice(0, i), command: argv.slice(i + 1) };
+}
+async function main() {
+  const rawArgv = process.argv.slice(2);
+  const sub = rawArgv[0];
+  if (!sub || sub === "-h" || sub === "--help" || sub === "help") {
+    process.stdout.write(USAGE);
+    return sub ? 0 : 1;
+  }
+  const { flags, command } = splitOnDoubleDash(rawArgv.slice(1));
+  const { values } = util.parseArgs({
+    args: flags,
+    options: {
+      tool: { type: "string" },
+      args: { type: "string" },
+      "no-validate": { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      timeout: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    },
+    allowPositionals: true
+  });
+  if (values.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (command.length === 0) {
+    process.stderr.write(c.red("error: no server command given. Put it after `--`, e.g. `-- node dist/server.js`\n"));
+    return 2;
+  }
+  const timeoutMs = values.timeout ? Number(values.timeout) : 15e3;
+  const [cmd, ...cmdArgs] = command;
+  const client = await createTestClient(
+    { command: cmd, args: cmdArgs },
+    { timeoutMs }
+  );
+  try {
+    switch (sub) {
+      case "inspect":
+        return await runInspect(client, !!values.json);
+      case "check":
+        return await runCheck(client, !!values.json);
+      case "call":
+        return await runCall(client, {
+          tool: values.tool,
+          args: values.args,
+          validate: !values["no-validate"]
+        });
+      default:
+        process.stderr.write(c.red(`error: unknown command "${sub}"
+
+`));
+        process.stdout.write(USAGE);
+        return 2;
+    }
+  } finally {
+    await client.close().catch(() => {
+    });
+  }
+}
+async function runInspect(client, json) {
+  const [tools, resources, prompts] = await Promise.all([
+    client.tools(),
+    client.resources(),
+    client.prompts()
+  ]);
+  const info = client.serverInfo();
+  if (json) {
+    process.stdout.write(JSON.stringify({ server: info, tools, resources, prompts }, null, 2) + "\n");
+    return 0;
+  }
+  process.stdout.write(
+    `${c.bold(info?.name ?? "(unnamed server)")} ${c.dim("v" + (info?.version ?? "?"))}
+
+`
+  );
+  process.stdout.write(c.bold(`Tools (${tools.length})
+`));
+  for (const t of tools) {
+    process.stdout.write(`  ${c.cyan(t.name)}${t.description ? "  " + c.dim(t.description) : ""}
+`);
+    const props = t.inputSchema?.properties;
+    if (props && Object.keys(props).length > 0) {
+      const req = new Set(t.inputSchema?.required ?? []);
+      for (const [name, sub] of Object.entries(props)) {
+        const type = Array.isArray(sub.type) ? sub.type.join("|") : sub.type ?? "any";
+        process.stdout.write(`      ${name}${req.has(name) ? "*" : ""}: ${c.dim(String(type))}
+`);
+      }
+    }
+  }
+  if (resources.length > 0) {
+    process.stdout.write("\n" + c.bold(`Resources (${resources.length})
+`));
+    for (const r of resources) {
+      process.stdout.write(`  ${c.cyan(r.uri)}${r.name ? "  " + c.dim(r.name) : ""}
+`);
+    }
+  }
+  if (prompts.length > 0) {
+    process.stdout.write("\n" + c.bold(`Prompts (${prompts.length})
+`));
+    for (const p of prompts) {
+      process.stdout.write(`  ${c.cyan(p.name)}${p.description ? "  " + c.dim(p.description) : ""}
+`);
+    }
+  }
+  return 0;
+}
+async function runCheck(client, json) {
+  const report = await conformanceCheck(client);
+  if (json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    return report.ok ? 0 : 1;
+  }
+  const mark = (r) => r.status === "pass" ? c.green("\u2713") : r.status === "skip" ? c.dim("\u2013") : r.severity === "error" ? c.red("\u2717") : c.yellow("!");
+  for (const r of report.checks) {
+    process.stdout.write(`${mark(r)} ${r.title}${r.detail ? c.dim("  \u2014 " + r.detail) : ""}
+`);
+    for (const f of r.findings ?? []) {
+      process.stdout.write(`    ${c.dim("\u2022")} ${f}
+`);
+    }
+  }
+  const { passed, failed, skipped } = report.summary;
+  process.stdout.write(
+    `
+${report.ok ? c.green("PASS") : c.red("FAIL")}  ${passed} passed, ${failed} failed, ${skipped} skipped
+`
+  );
+  return report.ok ? 0 : 1;
+}
+async function runCall(client, opts) {
+  if (!opts.tool) {
+    process.stderr.write(c.red("error: --tool <name> is required for `call`\n"));
+    return 2;
+  }
+  let args = {};
+  if (opts.args) {
+    try {
+      args = JSON.parse(opts.args);
+    } catch (e) {
+      process.stderr.write(c.red(`error: --args is not valid JSON: ${e.message}
+`));
+      return 2;
+    }
+  }
+  const res = await client.call(opts.tool, args, { validate: opts.validate });
+  process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+  return res.isError ? 1 : 0;
+}
+main().then((code) => process.exit(code)).catch((err) => {
+  process.stderr.write(`${c.red("error:")} ${err?.message ?? err}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.cjs.map
+//# sourceMappingURL=cli.cjs.map