@wix/mcp 1.0.27 → 1.0.28

package/README.md

@@ -81,6 +81,150 @@ Set logging output:
 
 > Experimental tools are in early development and may have limited functionality or breaking changes. They must be explicitly enabled with `--experimental`.
 
+## Toolkit API (Programmatic Usage)
+
+The Toolkit API lets you use `@wix/mcp` tools **in-process** without running an MCP server. This is the recommended approach for AI agent integrations (Vercel AI SDK, LangChain, custom agent loops, etc.).
+
+### Quick Start
+
+```typescript
+import { createWixToolkit, extractText } from '@wix/mcp';
+
+const toolkit = createWixToolkit({
+  auth: {
+    siteToken: async (siteId) => ({ Authorization: `Bearer ${myToken}` }),
+    accountToken: async () => ({ Authorization: `Bearer ${myToken}` }),
+  },
+  docs: { tools: ['REST'], getToKnowWixEnabled: true },
+  api: { tools: ['CallWixSiteAPI'] },
+  defaults: { siteId: 'my-site-id' },
+  clientName: 'my-app',
+});
+
+// Get all tools as plain objects
+for (const tool of toolkit.getTools()) {
+  console.log(tool.name, tool.description);
+  console.log(tool.inputSchema);  // Zod schema
+}
+
+// Execute a tool
+const result = await toolkit.getTool('SearchWixRESTDocumentation')!
+  .execute({ searchTerm: 'query products', reason: 'find endpoint' });
+console.log(extractText(result));
+
+// Pre-load WixREADME content for system prompt injection
+const readme = await toolkit.preloadReadme();
+```
+
+### `createWixToolkit(options)`
+
+Returns a `WixToolkit` with the following methods:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getTools()` | `WixTool[]` | All registered tools |
+| `getTool(name)` | `WixTool \| undefined` | Look up a tool by name |
+| `getToolNames()` | `string[]` | List of tool names |
+| `preloadReadme()` | `Promise<string \| null>` | Pre-load WixREADME content |
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `auth` | `WixToolkitAuth` | **Required.** Auth headers for API calls. Either `{ siteToken, accountToken }` functions or a full `McpAuthenticationStrategy`. |
+| `docs` | `WixToolkitDocsConfig` | Docs tools config. `tools` selects sources (`'REST'`, `'SDK'`, etc.). `getToKnowWixEnabled: true` enables `WixREADME`. |
+| `api` | `WixToolkitApiConfig` | API tools config. `tools` selects which API tools to register (`'CallWixSiteAPI'`, `'ListWixSites'`, `'ManageWixSite'`). |
+| `defaults` | `Record<string, any>` | Values to hide from tool schemas and auto-inject at execute time. Commonly used for `siteId`. |
+| `exclude` | `string[]` | Tool names to filter out after registration. |
+| `clientName` | `string` | Consumer identifier for BI tracking. |
+| `hooks` | `WixToolkitHooks` | Lifecycle callbacks for observability (see below). |
+
+### `WixTool` Interface
+
+Each tool returned by `getTools()` has:
+
+```typescript
+interface WixTool {
+  name: string;                              // e.g. 'CallWixSiteAPI'
+  description: string;                       // LLM-facing description
+  inputSchema: z.ZodObject<any>;             // Zod schema for parameters
+  annotations?: ToolAnnotations;             // MCP annotations (readOnlyHint, etc.)
+  execute(args: Record<string, any>): Promise<CallToolResult>;
+}
+```
+
+### `defaults` — Hiding and Injecting Parameters
+
+Use `defaults` to remove fields from tool schemas and auto-inject values at execute time. This is how you handle parameters the LLM shouldn't control (e.g., `siteId`):
+
+```typescript
+const toolkit = createWixToolkit({
+  auth: { ... },
+  api: { tools: ['CallWixSiteAPI'] },
+  defaults: { siteId: 'my-site-id' },
+});
+
+// CallWixSiteAPI schema no longer has siteId — the LLM won't see it
+// When execute() is called, siteId is automatically merged into args
+const tool = toolkit.getTool('CallWixSiteAPI')!;
+await tool.execute({ url: 'https://...', method: 'GET', reason: '...' });
+// internally calls the API with { siteId: 'my-site-id', url: '...', method: 'GET', ... }
+```
+
+### Lifecycle Hooks
+
+```typescript
+const toolkit = createWixToolkit({
+  // ...
+  hooks: {
+    beforeExecute: (toolName, args) => {
+      console.log(`[${toolName}] starting`, args);
+    },
+    afterExecute: (toolName, result, durationMs) => {
+      console.log(`[${toolName}] done in ${durationMs}ms`, result.isError ? 'ERROR' : 'OK');
+    },
+    onError: (toolName, error, durationMs) => {
+      console.error(`[${toolName}] threw after ${durationMs}ms`, error);
+    },
+  },
+});
+```
+
+Hooks are separate from the library's internal Panorama/BI telemetry, which runs automatically.
+
+### `extractText(result)`
+
+Helper to extract text content from a `CallToolResult`:
+
+```typescript
+import { extractText } from '@wix/mcp';
+
+const result = await tool.execute({ searchTerm: 'products' });
+const text = extractText(result);  // concatenated text blocks, non-text filtered out
+```
+
+### Vercel AI SDK Integration Example
+
+```typescript
+import { createWixToolkit, extractText } from '@wix/mcp';
+import { tool } from 'ai';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+const toolkit = createWixToolkit({ auth: { ... }, docs: { tools: ['REST'] } });
+
+// Convert WixTools to Vercel AI SDK tools
+const aiTools = Object.fromEntries(
+  toolkit.getTools().map(t => [
+    t.name,
+    tool({
+      description: t.description,
+      parameters: t.inputSchema,
+      execute: async (args) => extractText(await t.execute(args)),
+    }),
+  ])
+);
+```
+
 ## Resources
 
 The resource feature provides access to Wix documentation via the MCP server:

package/build/cjs/index.cjs

@@ -39304,7 +39304,6 @@ function createWixToolkit(options) {
     docs,
     api,
     defaults = {},
-    curryFields = [],
     exclude = [],
     clientName,
     hooks
@@ -39344,7 +39343,7 @@ function createWixToolkit(options) {
   } else {
     addApiCallTool(server, authStrategy);
   }
-  const fieldsToRemove = [...Object.keys(defaults), ...curryFields];
+  const fieldsToRemove = Object.keys(defaults);
   const allTools = captured.filter((t) => !exclude.includes(t.name)).map((captured2) => {
     const inputSchema = fieldsToRemove.length > 0 ? buildSchemaWithout(captured2.paramsSchema, fieldsToRemove) : external_exports.object(captured2.paramsSchema);
     const execute = async (args) => {