@wix/mcp 1.0.27 → 1.0.29

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/bin-standalone.js

@@ -10772,7 +10772,8 @@ var defaultToolDescriptions = {
     ${SYSTEM_REMINDER}
   `,
   CallWixSiteAPI: dedent_default`
-    Call Wix apis on a business or site. Use this to create, read, update, and delete data and other Wix entities in your Wix site,
+    Call Wix apis on a business or site. Use this to create, read, update, and delete data and other Wix entities in your Wix site.
+    For POST/PATCH/PUT requests, pass the request body as a JSON object in the "body" parameter with all the required fields and values as described in the API schema, code examples, or docs you retrieved (e.g. body: {"name": "value", "nested": {"key": "value"}}).
     The API endpoint url param MUST ALWAYS be taken from the conversation context.
     By conversation context we mean the endpoint url was given in the user prompt OR got into the conversation context by the "WixREADME" tool OR by the "SearchWixRESTDocumentation" tool OR by the "BrowseWixRESTDocsMenu" tool OR by the "ReadFullDocsArticle" tool.
     Error Handling:
@@ -10789,6 +10790,7 @@ var defaultToolDescriptions = {
   `,
   ManageWixSite: dedent_default`
     Use account level API in order to create a site, update a site and publish site.
+    For POST/PATCH/PUT requests, pass the request body as a JSON object in the "body" parameter with all the required fields and values as described in the API schema, code examples, or docs you retrieved (e.g. body: {"name": "value", "nested": {"key": "value"}}).
     The API endpoint url param MUST ALWAYS be taken from the conversation context.
     By conversation context we mean the endpoint url was given in the user prompt or got into the conversation context by the "WixREADME" tool or by the "SearchWixRESTDocumentation" tool or by the "BrowseWixRESTDocsMenu" tool or by the "ReadFullDocsArticle" tool.
     ${SYSTEM_REMINDER}
@@ -11159,7 +11161,7 @@ var paramDescriptions = {
       `Docs urls like https://dev.wix.com/docs/... are not API urls, if you want to read the docs, use the "ReadFullDocsArticle" tool`
     ].join("\n"),
     method: "The HTTP method to use for the API call (e.g. GET, POST, PUT, DELETE)",
-    body: 'The request body object. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
+    body: 'The request body as a JSON object with all the required fields and values, including nested objects. Pass the actual object, NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
     reason: "One sentence explaining the original user request and why you are calling this API to complete it.",
     sourceDocUrl: [
       "The URL of the documentation or recipe where you found this API endpoint.",
@@ -11177,7 +11179,7 @@ var paramDescriptions = {
   ManageWixSite: {
     url: "The url of the api to call - ALWAYS get the information from the Wix REST docs DONT GUESS IT, the URL MUST BE ABSOLUTE URL",
     method: "The HTTP method to use for the API call (e.g. GET, POST, PUT, DELETE)",
-    body: 'The request body object. YOU MUST NEVER MAKE UP A BODY - this should be based on the conversation context, i.e from the user prompt or from the "WixREADME" tool or from the "SearchWixRESTDocumentation" tool or from the "BrowseWixRESTDocsMenu" tool or from the "ReadFullDocsArticle" tool or from the "ReadFullDocsMethodSchema" tool - i.e based on the API docs. YOU MUST NEVER ASSUME YOU KNOW WHAT THE SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT.'
+    body: 'The request body as a JSON object with all the required fields and values, including nested objects. Pass the actual object, NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - this should be based on the conversation context, i.e from the user prompt or from the "WixREADME" tool or from the "SearchWixRESTDocumentation" tool or from the "BrowseWixRESTDocsMenu" tool or from the "ReadFullDocsArticle" tool or from the "ReadFullDocsMethodSchema" tool - i.e based on the API docs. YOU MUST NEVER ASSUME YOU KNOW WHAT THE SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT.'
   },
   SearchWixWDSDocumentation: {
     searchTerm: "The search term to search for in the Wix Design System Documentation",