mcp-playbook 0.1.0

package/dist/server/build.js

@@ -0,0 +1,168 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/build.ts
+var build_exports = {};
+__export(build_exports, {
+  buildStaticSite: () => buildStaticSite
+});
+module.exports = __toCommonJS(build_exports);
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+
+// src/server/connector.ts
+var import_client = require("@modelcontextprotocol/sdk/client/index.js");
+var import_stdio = require("@modelcontextprotocol/sdk/client/stdio.js");
+var import_sse = require("@modelcontextprotocol/sdk/client/sse.js");
+var import_streamableHttp = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+async function discoverAllServers(servers, extraExamples = {}, tags = {}) {
+  const toolTagMap = {};
+  for (const [tag, tools] of Object.entries(tags)) {
+    for (const tool of tools) {
+      if (!toolTagMap[tool]) toolTagMap[tool] = [];
+      toolTagMap[tool].push(tag);
+    }
+  }
+  const results = await Promise.allSettled(
+    servers.map(
+      (server, i) => connectToServer(server, i, extraExamples, toolTagMap)
+    )
+  );
+  return results.map((result, i) => {
+    if (result.status === "fulfilled") {
+      return result.value;
+    } else {
+      return {
+        id: `server-${i}`,
+        name: servers[i].name,
+        url: servers[i].url || `${servers[i].command} ${(servers[i].args || []).join(" ")}`,
+        status: "error",
+        version: "unknown",
+        tools: [],
+        error: result.reason?.message || "Connection failed"
+      };
+    }
+  });
+}
+async function connectToServer(config, index, extraExamples, toolTagMap) {
+  const client = new import_client.Client(
+    { name: "mcp-playbook", version: "0.1.0" },
+    { capabilities: {} }
+  );
+  let transport;
+  if (config.transport === "stdio") {
+    if (!config.command) throw new Error(`Server "${config.name}" needs a command for stdio transport`);
+    transport = new import_stdio.StdioClientTransport({
+      command: config.command,
+      args: config.args || [],
+      env: config.env || {},
+      cwd: config.cwd || process.cwd()
+    });
+  } else if (config.transport === "http") {
+    if (!config.url) throw new Error(`Server "${config.name}" needs a url for http transport`);
+    transport = new import_streamableHttp.StreamableHTTPClientTransport(new URL(config.url), {
+      requestInit: { headers: config.headers || {} }
+    });
+  } else if (config.transport === "sse") {
+    if (!config.url) throw new Error(`Server "${config.name}" needs a url for sse transport`);
+    transport = new import_sse.SSEClientTransport(new URL(config.url), {
+      requestInit: { headers: config.headers || {} }
+    });
+  } else {
+    throw new Error(`Unknown transport: ${config.transport}`);
+  }
+  await client.connect(transport);
+  const { tools } = await client.listTools();
+  const serverInfo = client.getServerVersion();
+  const discoveredTools = tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description || "",
+    inputSchema: tool.inputSchema,
+    examples: extraExamples[tool.name] || [],
+    tags: toolTagMap[tool.name] || []
+  }));
+  return {
+    id: `server-${index}`,
+    name: config.name,
+    url: config.url || `${config.command} ${(config.args || []).join(" ")}`,
+    status: "connected",
+    version: serverInfo?.version || "1.0.0",
+    tools: discoveredTools
+  };
+}
+
+// src/server/build.ts
+var import_meta = {};
+async function buildStaticSite(options) {
+  const configModule = await import(options.configPath);
+  const config = configModule.default;
+  const servers = await discoverAllServers(
+    config.servers,
+    config.examples || {},
+    config.tags || {}
+  );
+  import_fs.default.mkdirSync(options.outputDir, { recursive: true });
+  const data = {
+    title: config.title || "MCP Playbook",
+    description: config.description || "",
+    theme: config.theme || {},
+    builtAt: (/* @__PURE__ */ new Date()).toISOString(),
+    servers
+  };
+  import_fs.default.writeFileSync(
+    import_path.default.join(options.outputDir, "data.json"),
+    JSON.stringify(data, null, 2)
+  );
+  const clientDist = import_path.default.join(
+    import_path.default.dirname(new URL(import_meta.url).pathname),
+    "../../dist/client"
+  );
+  if (import_fs.default.existsSync(clientDist)) {
+    copyDir(clientDist, options.outputDir);
+  }
+  const toolCount = servers.reduce((acc, s) => acc + s.tools.length, 0);
+  console.log(`  ${servers.length} servers, ${toolCount} tools documented`);
+}
+function copyDir(src, dest) {
+  import_fs.default.mkdirSync(dest, { recursive: true });
+  for (const entry of import_fs.default.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = import_path.default.join(src, entry.name);
+    const destPath = import_path.default.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      import_fs.default.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildStaticSite
+});
+//# sourceMappingURL=build.js.map

package/dist/server/build.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/build.ts","../../src/server/connector.ts"],"sourcesContent":["/**\n * src/server/build.ts\n *\n * Builds a static documentation site from the MCP servers.\n *\n * Output:\n *   playbook-dist/\n *     index.html\n *     assets/\n *     data.json    ← all server/tool data baked in at build time\n *\n * This lets teams deploy their MCP docs to:\n *   - GitHub Pages\n *   - Vercel\n *   - Netlify\n *   - Any static host\n *\n * Users run: mcp-playbook build\n */\n\nimport fs from 'fs'\nimport path from 'path'\nimport { discoverAllServers } from './connector.js'\nimport type { PlaybookConfig } from '../config.js'\n\ninterface BuildOptions {\n  outputDir:  string\n  configPath: string\n}\n\nexport async function buildStaticSite(options: BuildOptions) {\n  // Load config\n  const configModule = await import(options.configPath)\n  const config: PlaybookConfig = configModule.default\n\n  // Connect to all servers and discover tools\n  const servers = await discoverAllServers(\n    config.servers,\n    config.examples || {},\n    config.tags     || {}\n  )\n\n  // Create output directory\n  fs.mkdirSync(options.outputDir, { recursive: true })\n\n  // Write the data file — the static site reads this instead of hitting the API\n  const data = {\n    title:       config.title       || 'MCP Playbook',\n    description: config.description || '',\n    theme:       config.theme       || {},\n    builtAt:     new Date().toISOString(),\n    servers\n  }\n\n  fs.writeFileSync(\n    path.join(options.outputDir, 'data.json'),\n    JSON.stringify(data, null, 2)\n  )\n\n  // Copy the static UI bundle\n  const clientDist = path.join(\n    path.dirname(new URL(import.meta.url).pathname),\n    '../../dist/client'\n  )\n\n  if (fs.existsSync(clientDist)) {\n    copyDir(clientDist, options.outputDir)\n  }\n\n  const toolCount = servers.reduce((acc, s) => acc + s.tools.length, 0)\n  console.log(`  ${servers.length} servers, ${toolCount} tools documented`)\n}\n\nfunction copyDir(src: string, dest: string) {\n  fs.mkdirSync(dest, { recursive: true })\n  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {\n    const srcPath  = path.join(src,  entry.name)\n    const destPath = path.join(dest, entry.name)\n    if (entry.isDirectory()) {\n      copyDir(srcPath, destPath)\n    } else {\n      fs.copyFileSync(srcPath, destPath)\n    }\n  }\n}\n","/**\n * src/server/connector.ts\n *\n * Connects to MCP servers and discovers their tools.\n * This is the bridge between the user's MCP servers and\n * the Playbook UI.\n *\n * Supports:\n *   - stdio transport (spawn a process, talk over stdin/stdout)\n *   - HTTP / SSE transport (connect to a running server)\n *\n * Returns a unified DiscoveredServer[] with all tool schemas.\n */\n\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js'\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'\nimport { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'\nimport type { ServerConfig, ToolExample } from '../config.js'\n\nexport interface DiscoveredTool {\n  name:        string\n  description: string\n  inputSchema: Record<string, unknown>\n  examples:    ToolExample[]\n  tags:        string[]\n}\n\nexport interface DiscoveredServer {\n  id:       string\n  name:     string\n  url:      string\n  status:   'connected' | 'disconnected' | 'error'\n  version:  string\n  tools:    DiscoveredTool[]\n  error?:   string\n}\n\n/**\n * Connect to all configured servers and discover their tools.\n * Runs all connections in parallel — slow servers don't block fast ones.\n */\nexport async function discoverAllServers(\n  servers: ServerConfig[],\n  extraExamples: Record<string, ToolExample[]> = {},\n  tags: Record<string, string[]> = {}\n): Promise<DiscoveredServer[]> {\n\n  // Build a reverse lookup: tool name → tag names\n  const toolTagMap: Record<string, string[]> = {}\n  for (const [tag, tools] of Object.entries(tags)) {\n    for (const tool of tools) {\n      if (!toolTagMap[tool]) toolTagMap[tool] = []\n      toolTagMap[tool].push(tag)\n    }\n  }\n\n  // Connect to all servers in parallel\n  const results = await Promise.allSettled(\n    servers.map((server, i) =>\n      connectToServer(server, i, extraExamples, toolTagMap)\n    )\n  )\n\n  return results.map((result, i) => {\n    if (result.status === 'fulfilled') {\n      return result.value\n    } else {\n      return {\n        id:      `server-${i}`,\n        name:    servers[i].name,\n        url:     servers[i].url || `${servers[i].command} ${(servers[i].args || []).join(' ')}`,\n        status:  'error' as const,\n        version: 'unknown',\n        tools:   [],\n        error:   result.reason?.message || 'Connection failed'\n      }\n    }\n  })\n}\n\nasync function connectToServer(\n  config: ServerConfig,\n  index: number,\n  extraExamples: Record<string, ToolExample[]>,\n  toolTagMap: Record<string, string[]>\n): Promise<DiscoveredServer> {\n\n  const client = new Client(\n    { name: 'mcp-playbook', version: '0.1.0' },\n    { capabilities: {} }\n  )\n\n  // Create the right transport based on config\n  let transport\n\n  if (config.transport === 'stdio') {\n    if (!config.command) throw new Error(`Server \"${config.name}\" needs a command for stdio transport`)\n    transport = new StdioClientTransport({\n      command: config.command,\n      args:    config.args    || [],\n      env:     config.env     || {},\n      cwd:     config.cwd     || process.cwd()\n    })\n  } else if (config.transport === 'http') {\n    if (!config.url) throw new Error(`Server \"${config.name}\" needs a url for http transport`)\n    transport = new StreamableHTTPClientTransport(new URL(config.url), {\n      requestInit: { headers: config.headers || {} }\n    })\n  } else if (config.transport === 'sse') {\n    if (!config.url) throw new Error(`Server \"${config.name}\" needs a url for sse transport`)\n    transport = new SSEClientTransport(new URL(config.url), {\n      requestInit: { headers: config.headers || {} }\n    })\n  } else {\n    throw new Error(`Unknown transport: ${(config as any).transport}`)\n  }\n\n  await client.connect(transport)\n\n  // Fetch tools from the server\n  const { tools } = await client.listTools()\n\n  // Fetch server info if available\n  const serverInfo = client.getServerVersion()\n\n  // Map tools to our format\n  const discoveredTools: DiscoveredTool[] = tools.map(tool => ({\n    name:        tool.name,\n    description: tool.description || '',\n    inputSchema: tool.inputSchema as Record<string, unknown>,\n    examples:    extraExamples[tool.name] || [],\n    tags:        toolTagMap[tool.name]    || []\n  }))\n\n  return {\n    id:      `server-${index}`,\n    name:    config.name,\n    url:     config.url || `${config.command} ${(config.args || []).join(' ')}`,\n    status:  'connected',\n    version: serverInfo?.version || '1.0.0',\n    tools:   discoveredTools\n  }\n}\n\n/**\n * Execute a tool call against a specific server.\n * Used by the Try tab in the UI.\n */\nexport async function executeTool(\n  serverConfig: ServerConfig,\n  toolName: string,\n  input: Record<string, unknown>\n): Promise<{ result: unknown; duration_ms: number; error?: string }> {\n\n  const start = Date.now()\n\n  try {\n    const client = new Client(\n      { name: 'mcp-playbook', version: '0.1.0' },\n      { capabilities: {} }\n    )\n\n    let transport\n    if (serverConfig.transport === 'stdio') {\n      transport = new StdioClientTransport({\n        command: serverConfig.command!,\n        args:    serverConfig.args || [],\n      })\n    } else {\n      transport = new StreamableHTTPClientTransport(new URL(serverConfig.url!))\n    }\n\n    await client.connect(transport)\n\n    const result = await client.callTool({ name: toolName, arguments: input })\n    await client.close()\n\n    return {\n      result,\n      duration_ms: Date.now() - start\n    }\n  } catch (err: any) {\n    return {\n      result:      null,\n      duration_ms: Date.now() - start,\n      error:       err.message\n    }\n  }\n}\n"],"mappings":"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","names":["fs","path"]}

package/dist/server/build.mjs

@@ -0,0 +1,132 @@
+// src/server/build.ts
+import fs from "fs";
+import path from "path";
+
+// src/server/connector.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+async function discoverAllServers(servers, extraExamples = {}, tags = {}) {
+  const toolTagMap = {};
+  for (const [tag, tools] of Object.entries(tags)) {
+    for (const tool of tools) {
+      if (!toolTagMap[tool]) toolTagMap[tool] = [];
+      toolTagMap[tool].push(tag);
+    }
+  }
+  const results = await Promise.allSettled(
+    servers.map(
+      (server, i) => connectToServer(server, i, extraExamples, toolTagMap)
+    )
+  );
+  return results.map((result, i) => {
+    if (result.status === "fulfilled") {
+      return result.value;
+    } else {
+      return {
+        id: `server-${i}`,
+        name: servers[i].name,
+        url: servers[i].url || `${servers[i].command} ${(servers[i].args || []).join(" ")}`,
+        status: "error",
+        version: "unknown",
+        tools: [],
+        error: result.reason?.message || "Connection failed"
+      };
+    }
+  });
+}
+async function connectToServer(config, index, extraExamples, toolTagMap) {
+  const client = new Client(
+    { name: "mcp-playbook", version: "0.1.0" },
+    { capabilities: {} }
+  );
+  let transport;
+  if (config.transport === "stdio") {
+    if (!config.command) throw new Error(`Server "${config.name}" needs a command for stdio transport`);
+    transport = new StdioClientTransport({
+      command: config.command,
+      args: config.args || [],
+      env: config.env || {},
+      cwd: config.cwd || process.cwd()
+    });
+  } else if (config.transport === "http") {
+    if (!config.url) throw new Error(`Server "${config.name}" needs a url for http transport`);
+    transport = new StreamableHTTPClientTransport(new URL(config.url), {
+      requestInit: { headers: config.headers || {} }
+    });
+  } else if (config.transport === "sse") {
+    if (!config.url) throw new Error(`Server "${config.name}" needs a url for sse transport`);
+    transport = new SSEClientTransport(new URL(config.url), {
+      requestInit: { headers: config.headers || {} }
+    });
+  } else {
+    throw new Error(`Unknown transport: ${config.transport}`);
+  }
+  await client.connect(transport);
+  const { tools } = await client.listTools();
+  const serverInfo = client.getServerVersion();
+  const discoveredTools = tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description || "",
+    inputSchema: tool.inputSchema,
+    examples: extraExamples[tool.name] || [],
+    tags: toolTagMap[tool.name] || []
+  }));
+  return {
+    id: `server-${index}`,
+    name: config.name,
+    url: config.url || `${config.command} ${(config.args || []).join(" ")}`,
+    status: "connected",
+    version: serverInfo?.version || "1.0.0",
+    tools: discoveredTools
+  };
+}
+
+// src/server/build.ts
+async function buildStaticSite(options) {
+  const configModule = await import(options.configPath);
+  const config = configModule.default;
+  const servers = await discoverAllServers(
+    config.servers,
+    config.examples || {},
+    config.tags || {}
+  );
+  fs.mkdirSync(options.outputDir, { recursive: true });
+  const data = {
+    title: config.title || "MCP Playbook",
+    description: config.description || "",
+    theme: config.theme || {},
+    builtAt: (/* @__PURE__ */ new Date()).toISOString(),
+    servers
+  };
+  fs.writeFileSync(
+    path.join(options.outputDir, "data.json"),
+    JSON.stringify(data, null, 2)
+  );
+  const clientDist = path.join(
+    path.dirname(new URL(import.meta.url).pathname),
+    "../../dist/client"
+  );
+  if (fs.existsSync(clientDist)) {
+    copyDir(clientDist, options.outputDir);
+  }
+  const toolCount = servers.reduce((acc, s) => acc + s.tools.length, 0);
+  console.log(`  ${servers.length} servers, ${toolCount} tools documented`);
+}
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+export {
+  buildStaticSite
+};
+//# sourceMappingURL=build.mjs.map

package/dist/server/build.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/build.ts","../../src/server/connector.ts"],"sourcesContent":["/**\n * src/server/build.ts\n *\n * Builds a static documentation site from the MCP servers.\n *\n * Output:\n *   playbook-dist/\n *     index.html\n *     assets/\n *     data.json    ← all server/tool data baked in at build time\n *\n * This lets teams deploy their MCP docs to:\n *   - GitHub Pages\n *   - Vercel\n *   - Netlify\n *   - Any static host\n *\n * Users run: mcp-playbook build\n */\n\nimport fs from 'fs'\nimport path from 'path'\nimport { discoverAllServers } from './connector.js'\nimport type { PlaybookConfig } from '../config.js'\n\ninterface BuildOptions {\n  outputDir:  string\n  configPath: string\n}\n\nexport async function buildStaticSite(options: BuildOptions) {\n  // Load config\n  const configModule = await import(options.configPath)\n  const config: PlaybookConfig = configModule.default\n\n  // Connect to all servers and discover tools\n  const servers = await discoverAllServers(\n    config.servers,\n    config.examples || {},\n    config.tags     || {}\n  )\n\n  // Create output directory\n  fs.mkdirSync(options.outputDir, { recursive: true })\n\n  // Write the data file — the static site reads this instead of hitting the API\n  const data = {\n    title:       config.title       || 'MCP Playbook',\n    description: config.description || '',\n    theme:       config.theme       || {},\n    builtAt:     new Date().toISOString(),\n    servers\n  }\n\n  fs.writeFileSync(\n    path.join(options.outputDir, 'data.json'),\n    JSON.stringify(data, null, 2)\n  )\n\n  // Copy the static UI bundle\n  const clientDist = path.join(\n    path.dirname(new URL(import.meta.url).pathname),\n    '../../dist/client'\n  )\n\n  if (fs.existsSync(clientDist)) {\n    copyDir(clientDist, options.outputDir)\n  }\n\n  const toolCount = servers.reduce((acc, s) => acc + s.tools.length, 0)\n  console.log(`  ${servers.length} servers, ${toolCount} tools documented`)\n}\n\nfunction copyDir(src: string, dest: string) {\n  fs.mkdirSync(dest, { recursive: true })\n  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {\n    const srcPath  = path.join(src,  entry.name)\n    const destPath = path.join(dest, entry.name)\n    if (entry.isDirectory()) {\n      copyDir(srcPath, destPath)\n    } else {\n      fs.copyFileSync(srcPath, destPath)\n    }\n  }\n}\n","/**\n * src/server/connector.ts\n *\n * Connects to MCP servers and discovers their tools.\n * This is the bridge between the user's MCP servers and\n * the Playbook UI.\n *\n * Supports:\n *   - stdio transport (spawn a process, talk over stdin/stdout)\n *   - HTTP / SSE transport (connect to a running server)\n *\n * Returns a unified DiscoveredServer[] with all tool schemas.\n */\n\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js'\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'\nimport { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'\nimport type { ServerConfig, ToolExample } from '../config.js'\n\nexport interface DiscoveredTool {\n  name:        string\n  description: string\n  inputSchema: Record<string, unknown>\n  examples:    ToolExample[]\n  tags:        string[]\n}\n\nexport interface DiscoveredServer {\n  id:       string\n  name:     string\n  url:      string\n  status:   'connected' | 'disconnected' | 'error'\n  version:  string\n  tools:    DiscoveredTool[]\n  error?:   string\n}\n\n/**\n * Connect to all configured servers and discover their tools.\n * Runs all connections in parallel — slow servers don't block fast ones.\n */\nexport async function discoverAllServers(\n  servers: ServerConfig[],\n  extraExamples: Record<string, ToolExample[]> = {},\n  tags: Record<string, string[]> = {}\n): Promise<DiscoveredServer[]> {\n\n  // Build a reverse lookup: tool name → tag names\n  const toolTagMap: Record<string, string[]> = {}\n  for (const [tag, tools] of Object.entries(tags)) {\n    for (const tool of tools) {\n      if (!toolTagMap[tool]) toolTagMap[tool] = []\n      toolTagMap[tool].push(tag)\n    }\n  }\n\n  // Connect to all servers in parallel\n  const results = await Promise.allSettled(\n    servers.map((server, i) =>\n      connectToServer(server, i, extraExamples, toolTagMap)\n    )\n  )\n\n  return results.map((result, i) => {\n    if (result.status === 'fulfilled') {\n      return result.value\n    } else {\n      return {\n        id:      `server-${i}`,\n        name:    servers[i].name,\n        url:     servers[i].url || `${servers[i].command} ${(servers[i].args || []).join(' ')}`,\n        status:  'error' as const,\n        version: 'unknown',\n        tools:   [],\n        error:   result.reason?.message || 'Connection failed'\n      }\n    }\n  })\n}\n\nasync function connectToServer(\n  config: ServerConfig,\n  index: number,\n  extraExamples: Record<string, ToolExample[]>,\n  toolTagMap: Record<string, string[]>\n): Promise<DiscoveredServer> {\n\n  const client = new Client(\n    { name: 'mcp-playbook', version: '0.1.0' },\n    { capabilities: {} }\n  )\n\n  // Create the right transport based on config\n  let transport\n\n  if (config.transport === 'stdio') {\n    if (!config.command) throw new Error(`Server \"${config.name}\" needs a command for stdio transport`)\n    transport = new StdioClientTransport({\n      command: config.command,\n      args:    config.args    || [],\n      env:     config.env     || {},\n      cwd:     config.cwd     || process.cwd()\n    })\n  } else if (config.transport === 'http') {\n    if (!config.url) throw new Error(`Server \"${config.name}\" needs a url for http transport`)\n    transport = new StreamableHTTPClientTransport(new URL(config.url), {\n      requestInit: { headers: config.headers || {} }\n    })\n  } else if (config.transport === 'sse') {\n    if (!config.url) throw new Error(`Server \"${config.name}\" needs a url for sse transport`)\n    transport = new SSEClientTransport(new URL(config.url), {\n      requestInit: { headers: config.headers || {} }\n    })\n  } else {\n    throw new Error(`Unknown transport: ${(config as any).transport}`)\n  }\n\n  await client.connect(transport)\n\n  // Fetch tools from the server\n  const { tools } = await client.listTools()\n\n  // Fetch server info if available\n  const serverInfo = client.getServerVersion()\n\n  // Map tools to our format\n  const discoveredTools: DiscoveredTool[] = tools.map(tool => ({\n    name:        tool.name,\n    description: tool.description || '',\n    inputSchema: tool.inputSchema as Record<string, unknown>,\n    examples:    extraExamples[tool.name] || [],\n    tags:        toolTagMap[tool.name]    || []\n  }))\n\n  return {\n    id:      `server-${index}`,\n    name:    config.name,\n    url:     config.url || `${config.command} ${(config.args || []).join(' ')}`,\n    status:  'connected',\n    version: serverInfo?.version || '1.0.0',\n    tools:   discoveredTools\n  }\n}\n\n/**\n * Execute a tool call against a specific server.\n * Used by the Try tab in the UI.\n */\nexport async function executeTool(\n  serverConfig: ServerConfig,\n  toolName: string,\n  input: Record<string, unknown>\n): Promise<{ result: unknown; duration_ms: number; error?: string }> {\n\n  const start = Date.now()\n\n  try {\n    const client = new Client(\n      { name: 'mcp-playbook', version: '0.1.0' },\n      { capabilities: {} }\n    )\n\n    let transport\n    if (serverConfig.transport === 'stdio') {\n      transport = new StdioClientTransport({\n        command: serverConfig.command!,\n        args:    serverConfig.args || [],\n      })\n    } else {\n      transport = new StreamableHTTPClientTransport(new URL(serverConfig.url!))\n    }\n\n    await client.connect(transport)\n\n    const result = await client.callTool({ name: toolName, arguments: input })\n    await client.close()\n\n    return {\n      result,\n      duration_ms: Date.now() - start\n    }\n  } catch (err: any) {\n    return {\n      result:      null,\n      duration_ms: Date.now() - start,\n      error:       err.message\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/server/connector.d.mts

@@ -0,0 +1,119 @@
+/**
+ * src/config.ts
+ *
+ * Type definitions and the defineConfig() helper.
+ *
+ * Users write:
+ *   import { defineConfig } from 'mcp-playbook'
+ *   export default defineConfig({ ... })
+ *
+ * Same pattern as Vite, Vitest, etc.
+ */
+interface ServerConfig {
+    /** Display name shown in the UI */
+    name: string;
+    /** How to connect to this MCP server */
+    transport: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+}
+interface ToolExample {
+    /** Short label shown in the Examples tab */
+    label: string;
+    /** Optional longer description */
+    description?: string;
+    /** Input values to pre-fill */
+    input: Record<string, unknown>;
+    /** Optional expected output to show alongside */
+    expectedOutput?: unknown;
+}
+interface PlaybookConfig {
+    /** Title shown in the UI header */
+    title?: string;
+    /** Subtitle / description */
+    description?: string;
+    /** MCP servers to connect to */
+    servers: ServerConfig[];
+    /**
+     * Hand-written examples per tool name.
+     * These are merged with any examples found in the server's tool definitions.
+     *
+     * examples: {
+     *   get_user: [{ label: 'Basic', input: { userId: 'usr_123' } }]
+     * }
+     */
+    examples?: Record<string, ToolExample[]>;
+    /**
+     * Group tools under named sections.
+     * tags: { 'User management': ['get_user', 'create_user'] }
+     */
+    tags?: Record<string, string[]>;
+    /** UI theming */
+    theme?: {
+        primary?: string;
+        background?: string;
+        font?: string;
+    };
+    /** Port for dev server. Default: 4242 */
+    port?: number;
+}
+/**
+ * defineConfig — gives you TypeScript autocomplete in your config file.
+ * This is the primary API users interact with.
+ *
+ * Usage:
+ *   import { defineConfig } from 'mcp-playbook'
+ *   export default defineConfig({ servers: [...] })
+ */
+declare function defineConfig(config: PlaybookConfig): PlaybookConfig;
+
+/**
+ * src/server/connector.ts
+ *
+ * Connects to MCP servers and discovers their tools.
+ * This is the bridge between the user's MCP servers and
+ * the Playbook UI.
+ *
+ * Supports:
+ *   - stdio transport (spawn a process, talk over stdin/stdout)
+ *   - HTTP / SSE transport (connect to a running server)
+ *
+ * Returns a unified DiscoveredServer[] with all tool schemas.
+ */
+
+interface DiscoveredTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    examples: ToolExample[];
+    tags: string[];
+}
+interface DiscoveredServer {
+    id: string;
+    name: string;
+    url: string;
+    status: 'connected' | 'disconnected' | 'error';
+    version: string;
+    tools: DiscoveredTool[];
+    error?: string;
+}
+/**
+ * Connect to all configured servers and discover their tools.
+ * Runs all connections in parallel — slow servers don't block fast ones.
+ */
+declare function discoverAllServers(servers: ServerConfig[], extraExamples?: Record<string, ToolExample[]>, tags?: Record<string, string[]>): Promise<DiscoveredServer[]>;
+/**
+ * Execute a tool call against a specific server.
+ * Used by the Try tab in the UI.
+ */
+declare function executeTool(serverConfig: ServerConfig, toolName: string, input: Record<string, unknown>): Promise<{
+    result: unknown;
+    duration_ms: number;
+    error?: string;
+}>;
+
+export { type DiscoveredServer, type DiscoveredTool, type PlaybookConfig as P, type ServerConfig as S, type ToolExample as T, defineConfig as d, discoverAllServers, executeTool };

package/dist/server/connector.d.ts

@@ -0,0 +1,119 @@
+/**
+ * src/config.ts
+ *
+ * Type definitions and the defineConfig() helper.
+ *
+ * Users write:
+ *   import { defineConfig } from 'mcp-playbook'
+ *   export default defineConfig({ ... })
+ *
+ * Same pattern as Vite, Vitest, etc.
+ */
+interface ServerConfig {
+    /** Display name shown in the UI */
+    name: string;
+    /** How to connect to this MCP server */
+    transport: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+}
+interface ToolExample {
+    /** Short label shown in the Examples tab */
+    label: string;
+    /** Optional longer description */
+    description?: string;
+    /** Input values to pre-fill */
+    input: Record<string, unknown>;
+    /** Optional expected output to show alongside */
+    expectedOutput?: unknown;
+}
+interface PlaybookConfig {
+    /** Title shown in the UI header */
+    title?: string;
+    /** Subtitle / description */
+    description?: string;
+    /** MCP servers to connect to */
+    servers: ServerConfig[];
+    /**
+     * Hand-written examples per tool name.
+     * These are merged with any examples found in the server's tool definitions.
+     *
+     * examples: {
+     *   get_user: [{ label: 'Basic', input: { userId: 'usr_123' } }]
+     * }
+     */
+    examples?: Record<string, ToolExample[]>;
+    /**
+     * Group tools under named sections.
+     * tags: { 'User management': ['get_user', 'create_user'] }
+     */
+    tags?: Record<string, string[]>;
+    /** UI theming */
+    theme?: {
+        primary?: string;
+        background?: string;
+        font?: string;
+    };
+    /** Port for dev server. Default: 4242 */
+    port?: number;
+}
+/**
+ * defineConfig — gives you TypeScript autocomplete in your config file.
+ * This is the primary API users interact with.
+ *
+ * Usage:
+ *   import { defineConfig } from 'mcp-playbook'
+ *   export default defineConfig({ servers: [...] })
+ */
+declare function defineConfig(config: PlaybookConfig): PlaybookConfig;
+
+/**
+ * src/server/connector.ts
+ *
+ * Connects to MCP servers and discovers their tools.
+ * This is the bridge between the user's MCP servers and
+ * the Playbook UI.
+ *
+ * Supports:
+ *   - stdio transport (spawn a process, talk over stdin/stdout)
+ *   - HTTP / SSE transport (connect to a running server)
+ *
+ * Returns a unified DiscoveredServer[] with all tool schemas.
+ */
+
+interface DiscoveredTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    examples: ToolExample[];
+    tags: string[];
+}
+interface DiscoveredServer {
+    id: string;
+    name: string;
+    url: string;
+    status: 'connected' | 'disconnected' | 'error';
+    version: string;
+    tools: DiscoveredTool[];
+    error?: string;
+}
+/**
+ * Connect to all configured servers and discover their tools.
+ * Runs all connections in parallel — slow servers don't block fast ones.
+ */
+declare function discoverAllServers(servers: ServerConfig[], extraExamples?: Record<string, ToolExample[]>, tags?: Record<string, string[]>): Promise<DiscoveredServer[]>;
+/**
+ * Execute a tool call against a specific server.
+ * Used by the Try tab in the UI.
+ */
+declare function executeTool(serverConfig: ServerConfig, toolName: string, input: Record<string, unknown>): Promise<{
+    result: unknown;
+    duration_ms: number;
+    error?: string;
+}>;
+
+export { type DiscoveredServer, type DiscoveredTool, type PlaybookConfig as P, type ServerConfig as S, type ToolExample as T, defineConfig as d, discoverAllServers, executeTool };