strapi-plugin-ai-sdk 0.8.0 → 0.10.0

package/README.md

@@ -302,18 +302,54 @@ Additionally, the AI SDK automatically discovers tools from other installed plug
 
 ## MCP Server
 
-The plugin exposes an [MCP](https://modelcontextprotocol.io/) server at `/api/ai-sdk/mcp` that lets external AI clients call the public tools directly.
+The plugin exposes an [MCP](https://modelcontextprotocol.io/) server at `/api/ai-sdk/mcp` that lets external AI clients (Claude Desktop, Claude Code, Cursor, Windsurf, etc.) call the public tools directly.
 
 ### How It Works
 
+- Uses the low-level MCP `Server` class for full control over JSON Schema output, ensuring compatibility with `mcp-remote` and all MCP clients regardless of Zod version
+- Uses the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) (MCP 2025-03-26 spec)
 - Sessions are created on first request and identified by the `mcp-session-id` header
 - Tool names are converted from camelCase to snake_case (`listContentTypes` -> `list_content_types`)
+- Each tool includes a `title` (e.g. "Strapi: Search Content") and `annotations` (`readOnlyHint`, `destructiveHint`) for better client integration
+- All tool schemas include `additionalProperties: false` to ensure compatibility with `mcp-remote` and Claude Desktop
+- Custom Zod-to-JSON Schema converter that supports both Zod 3 and Zod 4, producing complete type information (types, descriptions, defaults, enums, constraints) for every parameter
+- MCP arguments are coerced through the Zod schema before execution — stringified JSON values (e.g. `fields: '["title"]'`) are automatically parsed to their expected types, and defaults are applied for omitted optional parameters
+- The server returns dynamic `instructions` during initialization so clients know when to load tools — plugins that provide `getMeta()` get keyword-driven entries (e.g. `/youtube`, `/octalens`), others get auto-generated summaries
 - Sessions expire after the configured timeout (default: 4 hours)
 - Maximum concurrent sessions can be configured (default: 100)
 
+### Setup
+
+#### 1. Enable permissions
+
+In the Strapi admin panel:
+
+1. Go to **Settings > API Tokens**
+2. Create a new API token (or use an existing one)
+3. Under **Permissions**, enable the **Ai-sdk** actions: `handle` (covers POST, GET, DELETE for MCP)
+4. Copy the token
+
+Alternatively, for public access without a token:
+
+1. Go to **Settings > Users & Permissions > Roles > Public**
+2. Under **Ai-sdk**, enable `handle`
+3. Save
+
+#### 2. Connect your AI client
+
+The MCP endpoint URL is:
+
+```
+http://localhost:1337/api/ai-sdk/mcp
+```
+
+For remote deployments, replace `localhost:1337` with your Strapi URL.
+
 ### Connecting from Claude Desktop
 
-Add to your Claude Desktop MCP config:
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+**Without authentication (public permissions enabled):**
 
 ```json
 {
@@ -325,9 +361,53 @@ Add to your Claude Desktop MCP config:
 }
 ```
 
+**With an API token:**
+
+```json
+{
+  "mcpServers": {
+    "strapi": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "http://localhost:1337/api/ai-sdk/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_STRAPI_API_TOKEN"
+      ]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving the config.
+
+### Connecting from Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "strapi": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "http://localhost:1337/api/ai-sdk/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_STRAPI_API_TOKEN"
+      ]
+    }
+  }
+}
+```
+
+Or run: `claude mcp add strapi -- npx mcp-remote http://localhost:1337/api/ai-sdk/mcp --header "Authorization: Bearer YOUR_STRAPI_API_TOKEN"`
+
 ### Connecting from Cursor
 
-Add to your Cursor MCP settings:
+Add to your Cursor MCP settings (`.cursor/mcp.json`):
+
+**Without authentication:**
 
 ```json
 {
@@ -339,6 +419,71 @@ Add to your Cursor MCP settings:
 }
 ```
 
+**With an API token:**
+
+```json
+{
+  "mcpServers": {
+    "strapi": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "http://localhost:1337/api/ai-sdk/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_STRAPI_API_TOKEN"
+      ]
+    }
+  }
+}
+```
+
+### Testing with cURL
+
+```bash
+# 1. Initialize a session
+curl -s -X POST http://localhost:1337/api/ai-sdk/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer YOUR_STRAPI_API_TOKEN" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
+
+# 2. Send initialized notification (use the mcp-session-id from step 1)
+curl -s -X POST http://localhost:1337/api/ai-sdk/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_STRAPI_API_TOKEN" \
+  -H "mcp-session-id: SESSION_ID_FROM_STEP_1" \
+  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+
+# 3. List available tools
+curl -s -X POST http://localhost:1337/api/ai-sdk/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer YOUR_STRAPI_API_TOKEN" \
+  -H "mcp-session-id: SESSION_ID_FROM_STEP_1" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
+
+# 4. Call a tool
+curl -s -X POST http://localhost:1337/api/ai-sdk/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer YOUR_STRAPI_API_TOKEN" \
+  -H "mcp-session-id: SESSION_ID_FROM_STEP_1" \
+  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_content_types","arguments":{}}}'
+```
+
+### MCP Configuration
+
+```typescript
+// config/plugins.ts
+config: {
+  mcp: {
+    sessionTimeoutMs: 4 * 60 * 60 * 1000,  // 4 hours (default)
+    maxSessions: 100,                        // default
+    cleanupInterval: 100,                    // cleanup expired sessions every N requests
+  },
+}
+```
+
 ## Guardrails
 
 The plugin includes a guardrail middleware that checks all user input before it reaches the AI. It runs on every AI endpoint (`/ask`, `/ask-stream`, `/chat`, `/mcp`).
@@ -533,7 +678,7 @@ export const mySearchTool = {
 };
 ```
 
-**2. Create the `ai-tools` service:**
+**2. Create the `ai-tools` service with optional `getMeta()`:**
 
 ```typescript
 // server/src/services/ai-tools.ts
@@ -544,6 +689,19 @@ export default ({ strapi }: { strapi: Core.Strapi }) => ({
   getTools() {
     return tools;
   },
+
+  /**
+   * Optional: provide metadata so the MCP server instructions
+   * include your plugin's capabilities and trigger keywords.
+   * Without this, a summary is auto-generated from tool descriptions.
+   */
+  getMeta() {
+    return {
+      label: 'My Plugin',
+      description: 'Search and manage my plugin data with relevance ranking',
+      keywords: ['/my-plugin', 'my data', 'search my stuff'],
+    };
+  },
 });
 ```
 
@@ -575,6 +733,22 @@ interface ToolDefinition {
 }
 ```
 
+#### ToolSourceMeta Interface (optional `getMeta()`)
+
+When your plugin provides `getMeta()` on its `ai-tools` service, the MCP server instructions include your plugin's capabilities with trigger keywords. This helps Claude Desktop's "Load tools when needed" mode activate the right server for your plugin's queries.
+
+Without `getMeta()`, the AI SDK auto-generates a summary from your tool descriptions — so this is optional but recommended for better discoverability.
+
+```typescript
+interface ToolSourceMeta {
+  label: string;          // Human-readable label, e.g. "YouTube Transcripts"
+  description: string;    // One-line capability summary for MCP instructions
+  keywords?: string[];    // Trigger keywords/prefixes, e.g. ["/youtube", "/yt", "transcript"]
+}
+```
+
+Keywords that start with `/` are rendered as slash-command hints in the instructions (e.g. `/youtube or /yt — Fetch and search YouTube transcripts`). Other keywords are included as natural-language triggers.
+
 #### Canonical Architecture Pattern
 
 The recommended pattern is to define tools once in `server/src/tools/` and consume them from both the AI SDK service and MCP handlers:

package/dist/server/index.js

@@ -1,6 +1,7 @@
 "use strict";
 const anthropic = require("@ai-sdk/anthropic");
-const mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
+const index_js = require("@modelcontextprotocol/sdk/server/index.js");
+const types_js = require("@modelcontextprotocol/sdk/types.js");
 const ai = require("ai");
 const zod = require("zod");
 const fs = require("fs");
@@ -34,7 +35,7 @@ function toSnakeCase$1(str) {
   return str.replace(/:/g, "__").replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
 function extractType(field) {
-  const def = field?._zod?.def;
+  const def = field?._zod?.def ?? field?.def;
   if (!def) return "unknown";
   switch (def.type) {
     case "string":
@@ -44,11 +45,11 @@ function extractType(field) {
     case "boolean":
       return "boolean";
     case "enum":
-      return Object.keys(def.entries).join(" | ");
+      return def.entries ? Object.keys(def.entries).join(" | ") : "enum";
     case "optional":
-      return extractType({ _zod: { def: def.innerType } });
+      return extractType(def.innerType);
     case "default":
-      return extractType({ _zod: { def: def.innerType } });
+      return extractType(def.innerType);
     case "record":
       return "object";
     case "array":
@@ -117,67 +118,319 @@ function generateToolGuide(registry) {
 function toSnakeCase(str) {
   return str.replace(/:/g, "__").replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
+function toTitle(mcpName, source) {
+  const prefix = source === "built-in" ? "Strapi" : source.replace(/_/g, "-");
+  const shortName = mcpName.replace(/^[a-z_]+__/, "").replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return `${prefix}: ${shortName}`;
+}
+function getToolSource(name) {
+  const sep = name.indexOf("__");
+  return sep === -1 ? "built-in" : name.substring(0, sep);
+}
+function summarizeTools(tools, registry) {
+  const summaries = [];
+  for (const name of tools) {
+    const def = registry.get(name);
+    if (!def) continue;
+    const first = def.description.split(/\.\s/)[0].replace(/\.$/, "");
+    summaries.push(first);
+  }
+  return summaries.join(". ") + ".";
+}
+function buildInstructions(registry) {
+  const sources = registry.getToolSources();
+  const lines = [];
+  lines.push(
+    "Strapi CMS MCP server. Use this server for ANY of the following:"
+  );
+  lines.push(
+    "- /strapi — Query, create, update, delete CMS content (articles, pages, authors, categories, media, any custom content types)"
+  );
+  for (const source of sources) {
+    if (source.id === "built-in") continue;
+    const meta = registry.getSourceMeta(source.id);
+    if (meta) {
+      const prefix = meta.keywords?.length ? meta.keywords.map((k) => k.startsWith("/") ? k : `/${k}`).join(" or ") : `/${source.id.replace(/_/g, "-")}`;
+      lines.push(`- ${prefix} — ${meta.description}`);
+    } else {
+      const label = source.id.replace(/_/g, "-");
+      const summary = summarizeTools(source.tools, registry);
+      lines.push(`- /${label} — ${summary}`);
+    }
+  }
+  lines.push(
+    "- /memory — Save and recall user facts and preferences",
+    "- /notes — Save and recall research notes, code snippets, ideas",
+    "- /tasks — Create, update, complete, and list tasks",
+    "- /email — Send emails",
+    "- /media — Upload media files to the CMS"
+  );
+  return lines.join("\n");
+}
+function getZodType(field) {
+  const def = field?._def;
+  if (!def) return void 0;
+  return def.typeName ?? def.type;
+}
+function getDescription(field) {
+  return field?.description ?? field?._def?.description;
+}
+function zodToInputSchema(schema2) {
+  const shape = schema2.shape;
+  const properties = {};
+  const required = [];
+  for (const [key, fieldDef] of Object.entries(shape)) {
+    const prop = zodFieldToJsonSchema(fieldDef);
+    properties[key] = prop;
+    if (!isOptionalOrDefaulted(fieldDef)) {
+      required.push(key);
+    }
+  }
+  const result = {
+    type: "object",
+    properties,
+    additionalProperties: false
+  };
+  if (required.length > 0) {
+    result.required = required;
+  }
+  return result;
+}
+function isOptionalOrDefaulted(field) {
+  if (!field) return true;
+  const t = getZodType(field);
+  if (!t) return false;
+  const normalized = normalizeType(t);
+  if (normalized === "optional" || normalized === "default") return true;
+  if (field._def?.innerType) return isOptionalOrDefaulted(field._def.innerType);
+  return false;
+}
+function normalizeType(t) {
+  if (t.startsWith("Zod")) return t.slice(3).toLowerCase();
+  return t.toLowerCase();
+}
+function zodFieldToJsonSchema(field) {
+  const rawType = getZodType(field);
+  if (!rawType) return {};
+  const t = normalizeType(rawType);
+  const def = field._def;
+  const prop = {};
+  const desc = getDescription(field);
+  if (desc) prop.description = desc;
+  switch (t) {
+    case "string":
+      prop.type = "string";
+      break;
+    case "number": {
+      prop.type = "number";
+      if (field.isInt) prop.type = "integer";
+      if (typeof field.minValue === "number" && field.minValue > -Number.MAX_SAFE_INTEGER) prop.minimum = field.minValue;
+      if (typeof field.maxValue === "number" && field.maxValue < Number.MAX_SAFE_INTEGER) prop.maximum = field.maxValue;
+      if (def.checks && Array.isArray(def.checks)) {
+        for (const check of def.checks) {
+          if (check.kind === "min") prop.minimum = check.value;
+          if (check.kind === "max") prop.maximum = check.value;
+          if (check.kind === "int") prop.type = "integer";
+        }
+      }
+      break;
+    }
+    case "boolean":
+      prop.type = "boolean";
+      break;
+    case "enum": {
+      prop.type = "string";
+      if (Array.isArray(def.values)) {
+        prop.enum = def.values;
+      } else if (def.entries) {
+        prop.enum = Object.keys(def.entries);
+      } else if (Array.isArray(field.options)) {
+        prop.enum = field.options;
+      }
+      break;
+    }
+    case "array": {
+      prop.type = "array";
+      const itemType = def.element ?? def.type;
+      if (itemType) {
+        const itemSchema = zodFieldToJsonSchema(itemType);
+        prop.items = Object.keys(itemSchema).length > 0 ? itemSchema : { type: "string" };
+      }
+      break;
+    }
+    case "object": {
+      prop.type = "object";
+      if (field.shape) {
+        const nested = {};
+        for (const [k, v] of Object.entries(field.shape)) {
+          nested[k] = zodFieldToJsonSchema(v);
+        }
+        prop.properties = nested;
+        prop.additionalProperties = false;
+      }
+      break;
+    }
+    case "optional": {
+      const inner = zodFieldToJsonSchema(def.innerType);
+      if (desc) inner.description = desc;
+      return inner;
+    }
+    case "default": {
+      const inner = zodFieldToJsonSchema(def.innerType);
+      const dv = typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+      if (dv !== void 0) inner.default = dv;
+      if (desc) inner.description = desc;
+      return inner;
+    }
+    case "effects":
+      return zodFieldToJsonSchema(def.schema ?? def.innerType);
+    case "nullable":
+      return zodFieldToJsonSchema(def.innerType);
+    case "union": {
+      const options2 = def.options;
+      if (Array.isArray(options2) && options2.length > 0) {
+        return zodFieldToJsonSchema(options2[0]);
+      }
+      break;
+    }
+    case "record":
+      prop.type = "object";
+      break;
+    case "literal":
+      if (def.value !== void 0) {
+        prop.type = typeof def.value;
+        prop.enum = [def.value];
+      }
+      break;
+  }
+  return prop;
+}
+function coerceArgs(args, schema2) {
+  const shape = schema2.shape;
+  const result = { ...args };
+  for (const [key, value] of Object.entries(result)) {
+    if (typeof value !== "string") continue;
+    const fieldDef = shape[key];
+    if (!fieldDef) continue;
+    const expectedType = resolveBaseType(fieldDef);
+    if (expectedType === "object" || expectedType === "array") {
+      try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed === "object" && parsed !== null) {
+          result[key] = parsed;
+        }
+      } catch {
+      }
+    }
+  }
+  return result;
+}
+function resolveBaseType(field) {
+  const rawType = getZodType(field);
+  if (!rawType) return void 0;
+  const t = normalizeType(rawType);
+  if ((t === "optional" || t === "default" || t === "nullable") && field._def?.innerType) {
+    return resolveBaseType(field._def.innerType);
+  }
+  if (t === "record") return "object";
+  return t;
+}
 function createMcpServer(strapi) {
   const plugin = strapi.plugin("ai-sdk");
   const registry = plugin.toolRegistry;
   if (!registry) {
     throw new Error("Tool registry not initialized");
   }
-  const server = new mcp_js.McpServer(
+  const instructions = buildInstructions(registry);
+  const server = new index_js.Server(
     {
-      name: "ai-sdk-mcp",
+      name: "strapi-ai-sdk",
       version: "1.0.0"
     },
     {
       capabilities: {
         tools: {},
         resources: {}
-      }
+      },
+      instructions
     }
   );
-  const toolNames = [];
+  const toolList = [];
+  const toolHandlers = /* @__PURE__ */ new Map();
   for (const [name, def] of registry.getPublic()) {
     const mcpName = toSnakeCase(name);
-    toolNames.push(mcpName);
-    server.registerTool(
-      mcpName,
-      {
-        description: def.description,
-        inputSchema: def.schema.shape
-      },
-      async (args) => {
-        strapi.log.debug(`[ai-sdk:mcp] Tool call: ${mcpName}`);
-        const result = await def.execute(args, strapi);
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2)
-            }
-          ]
-        };
+    const source = getToolSource(name);
+    toolList.push({
+      name: mcpName,
+      title: toTitle(mcpName, source),
+      description: def.description,
+      inputSchema: zodToInputSchema(def.schema),
+      annotations: {
+        readOnlyHint: def.publicSafe ?? false,
+        destructiveHint: false
       }
-    );
+    });
+    toolHandlers.set(mcpName, def);
   }
+  server.setRequestHandler(types_js.ListToolsRequestSchema, async () => {
+    strapi.log.debug("[ai-sdk:mcp] Listing tools");
+    return { tools: toolList };
+  });
+  server.setRequestHandler(types_js.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    strapi.log.debug(`[ai-sdk:mcp] Tool call: ${name}`);
+    const def = toolHandlers.get(name);
+    if (!def) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+        isError: true
+      };
+    }
+    try {
+      const coerced = coerceArgs(args ?? {}, def.schema);
+      const validated = def.schema.parse(coerced);
+      const result = await def.execute(validated, strapi);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (error) {
+      strapi.log.error(`[ai-sdk:mcp] Tool ${name} failed:`, {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: true, message: String(error) }) }],
+        isError: true
+      };
+    }
+  });
   const guideMarkdown = generateToolGuide(registry);
-  server.registerResource(
-    "Tool Guide",
-    "strapi://tools/guide",
-    {
-      description: "Complete guide to all available Strapi AI tools with parameters and usage examples",
-      mimeType: "text/markdown"
-    },
-    async () => ({
-      contents: [
-        {
-          uri: "strapi://tools/guide",
-          mimeType: "text/markdown",
-          text: guideMarkdown
-        }
-      ]
-    })
-  );
+  server.setRequestHandler(types_js.ListResourcesRequestSchema, async () => ({
+    resources: [
+      {
+        uri: "strapi://tools/guide",
+        name: "Tool Guide",
+        description: "Complete guide to all available Strapi AI tools with parameters and usage examples",
+        mimeType: "text/markdown"
+      }
+    ]
+  }));
+  server.setRequestHandler(types_js.ReadResourceRequestSchema, async (request) => {
+    if (request.params.uri === "strapi://tools/guide") {
+      return {
+        contents: [
+          {
+            uri: "strapi://tools/guide",
+            mimeType: "text/markdown",
+            text: guideMarkdown
+          }
+        ]
+      };
+    }
+    throw new Error(`Resource not found: ${request.params.uri}`);
+  });
+  const toolNames = toolList.map((t) => t.name);
   strapi.log.info("[ai-sdk:mcp] MCP server created with tools:", { tools: toolNames });
+  strapi.log.debug("[ai-sdk:mcp] Server instructions:", instructions);
   return server;
 }
 const DEFAULT_MODEL = "claude-sonnet-4-20250514";
@@ -280,6 +533,15 @@ class AIProvider {
 class ToolRegistry {
   constructor() {
     this.tools = /* @__PURE__ */ new Map();
+    this.sourceMeta = /* @__PURE__ */ new Map();
+  }
+  /** Register metadata for a tool source (plugin namespace) */
+  setSourceMeta(sourceId, meta) {
+    this.sourceMeta.set(sourceId, meta);
+  }
+  /** Get metadata for a tool source, if provided */
+  getSourceMeta(sourceId) {
+    return this.sourceMeta.get(sourceId);
   }
   register(def) {
     this.tools.set(def.name, def);
@@ -1492,6 +1754,13 @@ function discoverPluginTools(strapi, registry) {
       const count = registerContributedTools(strapi, registry, pluginName, contributed);
       if (count > 0) {
         strapi.log.info(`[${PLUGIN_ID$2}] Registered ${count} tools from plugin: ${pluginName}`);
+        const safeName = pluginName.replace(/[^a-zA-Z0-9_-]/g, "_");
+        if (typeof aiToolsService.getMeta === "function") {
+          const meta = aiToolsService.getMeta();
+          if (meta?.label && meta?.description) {
+            registry.setSourceMeta(safeName, meta);
+          }
+        }
       }
     } catch (err) {
       strapi.log.warn(`[${PLUGIN_ID$2}] Tool discovery failed for ${pluginName}: ${err}`);

package/dist/server/index.mjs

@@ -1,5 +1,6 @@
 import { createAnthropic } from "@ai-sdk/anthropic";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { generateText, streamText, tool, zodSchema, convertToModelMessages, stepCountIs } from "ai";
 import { z } from "zod";
 import { mkdtempSync, writeFileSync, unlinkSync, rmdirSync } from "fs";
@@ -14,7 +15,7 @@ function toSnakeCase$1(str) {
   return str.replace(/:/g, "__").replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
 function extractType(field) {
-  const def = field?._zod?.def;
+  const def = field?._zod?.def ?? field?.def;
   if (!def) return "unknown";
   switch (def.type) {
     case "string":
@@ -24,11 +25,11 @@ function extractType(field) {
     case "boolean":
       return "boolean";
     case "enum":
-      return Object.keys(def.entries).join(" | ");
+      return def.entries ? Object.keys(def.entries).join(" | ") : "enum";
     case "optional":
-      return extractType({ _zod: { def: def.innerType } });
+      return extractType(def.innerType);
     case "default":
-      return extractType({ _zod: { def: def.innerType } });
+      return extractType(def.innerType);
     case "record":
       return "object";
     case "array":
@@ -97,67 +98,319 @@ function generateToolGuide(registry) {
 function toSnakeCase(str) {
   return str.replace(/:/g, "__").replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
+function toTitle(mcpName, source) {
+  const prefix = source === "built-in" ? "Strapi" : source.replace(/_/g, "-");
+  const shortName = mcpName.replace(/^[a-z_]+__/, "").replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return `${prefix}: ${shortName}`;
+}
+function getToolSource(name) {
+  const sep = name.indexOf("__");
+  return sep === -1 ? "built-in" : name.substring(0, sep);
+}
+function summarizeTools(tools, registry) {
+  const summaries = [];
+  for (const name of tools) {
+    const def = registry.get(name);
+    if (!def) continue;
+    const first = def.description.split(/\.\s/)[0].replace(/\.$/, "");
+    summaries.push(first);
+  }
+  return summaries.join(". ") + ".";
+}
+function buildInstructions(registry) {
+  const sources = registry.getToolSources();
+  const lines = [];
+  lines.push(
+    "Strapi CMS MCP server. Use this server for ANY of the following:"
+  );
+  lines.push(
+    "- /strapi — Query, create, update, delete CMS content (articles, pages, authors, categories, media, any custom content types)"
+  );
+  for (const source of sources) {
+    if (source.id === "built-in") continue;
+    const meta = registry.getSourceMeta(source.id);
+    if (meta) {
+      const prefix = meta.keywords?.length ? meta.keywords.map((k) => k.startsWith("/") ? k : `/${k}`).join(" or ") : `/${source.id.replace(/_/g, "-")}`;
+      lines.push(`- ${prefix} — ${meta.description}`);
+    } else {
+      const label = source.id.replace(/_/g, "-");
+      const summary = summarizeTools(source.tools, registry);
+      lines.push(`- /${label} — ${summary}`);
+    }
+  }
+  lines.push(
+    "- /memory — Save and recall user facts and preferences",
+    "- /notes — Save and recall research notes, code snippets, ideas",
+    "- /tasks — Create, update, complete, and list tasks",
+    "- /email — Send emails",
+    "- /media — Upload media files to the CMS"
+  );
+  return lines.join("\n");
+}
+function getZodType(field) {
+  const def = field?._def;
+  if (!def) return void 0;
+  return def.typeName ?? def.type;
+}
+function getDescription(field) {
+  return field?.description ?? field?._def?.description;
+}
+function zodToInputSchema(schema2) {
+  const shape = schema2.shape;
+  const properties = {};
+  const required = [];
+  for (const [key, fieldDef] of Object.entries(shape)) {
+    const prop = zodFieldToJsonSchema(fieldDef);
+    properties[key] = prop;
+    if (!isOptionalOrDefaulted(fieldDef)) {
+      required.push(key);
+    }
+  }
+  const result = {
+    type: "object",
+    properties,
+    additionalProperties: false
+  };
+  if (required.length > 0) {
+    result.required = required;
+  }
+  return result;
+}
+function isOptionalOrDefaulted(field) {
+  if (!field) return true;
+  const t = getZodType(field);
+  if (!t) return false;
+  const normalized = normalizeType(t);
+  if (normalized === "optional" || normalized === "default") return true;
+  if (field._def?.innerType) return isOptionalOrDefaulted(field._def.innerType);
+  return false;
+}
+function normalizeType(t) {
+  if (t.startsWith("Zod")) return t.slice(3).toLowerCase();
+  return t.toLowerCase();
+}
+function zodFieldToJsonSchema(field) {
+  const rawType = getZodType(field);
+  if (!rawType) return {};
+  const t = normalizeType(rawType);
+  const def = field._def;
+  const prop = {};
+  const desc = getDescription(field);
+  if (desc) prop.description = desc;
+  switch (t) {
+    case "string":
+      prop.type = "string";
+      break;
+    case "number": {
+      prop.type = "number";
+      if (field.isInt) prop.type = "integer";
+      if (typeof field.minValue === "number" && field.minValue > -Number.MAX_SAFE_INTEGER) prop.minimum = field.minValue;
+      if (typeof field.maxValue === "number" && field.maxValue < Number.MAX_SAFE_INTEGER) prop.maximum = field.maxValue;
+      if (def.checks && Array.isArray(def.checks)) {
+        for (const check of def.checks) {
+          if (check.kind === "min") prop.minimum = check.value;
+          if (check.kind === "max") prop.maximum = check.value;
+          if (check.kind === "int") prop.type = "integer";
+        }
+      }
+      break;
+    }
+    case "boolean":
+      prop.type = "boolean";
+      break;
+    case "enum": {
+      prop.type = "string";
+      if (Array.isArray(def.values)) {
+        prop.enum = def.values;
+      } else if (def.entries) {
+        prop.enum = Object.keys(def.entries);
+      } else if (Array.isArray(field.options)) {
+        prop.enum = field.options;
+      }
+      break;
+    }
+    case "array": {
+      prop.type = "array";
+      const itemType = def.element ?? def.type;
+      if (itemType) {
+        const itemSchema = zodFieldToJsonSchema(itemType);
+        prop.items = Object.keys(itemSchema).length > 0 ? itemSchema : { type: "string" };
+      }
+      break;
+    }
+    case "object": {
+      prop.type = "object";
+      if (field.shape) {
+        const nested = {};
+        for (const [k, v] of Object.entries(field.shape)) {
+          nested[k] = zodFieldToJsonSchema(v);
+        }
+        prop.properties = nested;
+        prop.additionalProperties = false;
+      }
+      break;
+    }
+    case "optional": {
+      const inner = zodFieldToJsonSchema(def.innerType);
+      if (desc) inner.description = desc;
+      return inner;
+    }
+    case "default": {
+      const inner = zodFieldToJsonSchema(def.innerType);
+      const dv = typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+      if (dv !== void 0) inner.default = dv;
+      if (desc) inner.description = desc;
+      return inner;
+    }
+    case "effects":
+      return zodFieldToJsonSchema(def.schema ?? def.innerType);
+    case "nullable":
+      return zodFieldToJsonSchema(def.innerType);
+    case "union": {
+      const options2 = def.options;
+      if (Array.isArray(options2) && options2.length > 0) {
+        return zodFieldToJsonSchema(options2[0]);
+      }
+      break;
+    }
+    case "record":
+      prop.type = "object";
+      break;
+    case "literal":
+      if (def.value !== void 0) {
+        prop.type = typeof def.value;
+        prop.enum = [def.value];
+      }
+      break;
+  }
+  return prop;
+}
+function coerceArgs(args, schema2) {
+  const shape = schema2.shape;
+  const result = { ...args };
+  for (const [key, value] of Object.entries(result)) {
+    if (typeof value !== "string") continue;
+    const fieldDef = shape[key];
+    if (!fieldDef) continue;
+    const expectedType = resolveBaseType(fieldDef);
+    if (expectedType === "object" || expectedType === "array") {
+      try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed === "object" && parsed !== null) {
+          result[key] = parsed;
+        }
+      } catch {
+      }
+    }
+  }
+  return result;
+}
+function resolveBaseType(field) {
+  const rawType = getZodType(field);
+  if (!rawType) return void 0;
+  const t = normalizeType(rawType);
+  if ((t === "optional" || t === "default" || t === "nullable") && field._def?.innerType) {
+    return resolveBaseType(field._def.innerType);
+  }
+  if (t === "record") return "object";
+  return t;
+}
 function createMcpServer(strapi) {
   const plugin = strapi.plugin("ai-sdk");
   const registry = plugin.toolRegistry;
   if (!registry) {
     throw new Error("Tool registry not initialized");
   }
-  const server = new McpServer(
+  const instructions = buildInstructions(registry);
+  const server = new Server(
     {
-      name: "ai-sdk-mcp",
+      name: "strapi-ai-sdk",
       version: "1.0.0"
     },
     {
       capabilities: {
         tools: {},
         resources: {}
-      }
+      },
+      instructions
     }
   );
-  const toolNames = [];
+  const toolList = [];
+  const toolHandlers = /* @__PURE__ */ new Map();
   for (const [name, def] of registry.getPublic()) {
     const mcpName = toSnakeCase(name);
-    toolNames.push(mcpName);
-    server.registerTool(
-      mcpName,
-      {
-        description: def.description,
-        inputSchema: def.schema.shape
-      },
-      async (args) => {
-        strapi.log.debug(`[ai-sdk:mcp] Tool call: ${mcpName}`);
-        const result = await def.execute(args, strapi);
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2)
-            }
-          ]
-        };
+    const source = getToolSource(name);
+    toolList.push({
+      name: mcpName,
+      title: toTitle(mcpName, source),
+      description: def.description,
+      inputSchema: zodToInputSchema(def.schema),
+      annotations: {
+        readOnlyHint: def.publicSafe ?? false,
+        destructiveHint: false
       }
-    );
+    });
+    toolHandlers.set(mcpName, def);
   }
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    strapi.log.debug("[ai-sdk:mcp] Listing tools");
+    return { tools: toolList };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    strapi.log.debug(`[ai-sdk:mcp] Tool call: ${name}`);
+    const def = toolHandlers.get(name);
+    if (!def) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+        isError: true
+      };
+    }
+    try {
+      const coerced = coerceArgs(args ?? {}, def.schema);
+      const validated = def.schema.parse(coerced);
+      const result = await def.execute(validated, strapi);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (error) {
+      strapi.log.error(`[ai-sdk:mcp] Tool ${name} failed:`, {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: true, message: String(error) }) }],
+        isError: true
+      };
+    }
+  });
   const guideMarkdown = generateToolGuide(registry);
-  server.registerResource(
-    "Tool Guide",
-    "strapi://tools/guide",
-    {
-      description: "Complete guide to all available Strapi AI tools with parameters and usage examples",
-      mimeType: "text/markdown"
-    },
-    async () => ({
-      contents: [
-        {
-          uri: "strapi://tools/guide",
-          mimeType: "text/markdown",
-          text: guideMarkdown
-        }
-      ]
-    })
-  );
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+      {
+        uri: "strapi://tools/guide",
+        name: "Tool Guide",
+        description: "Complete guide to all available Strapi AI tools with parameters and usage examples",
+        mimeType: "text/markdown"
+      }
+    ]
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    if (request.params.uri === "strapi://tools/guide") {
+      return {
+        contents: [
+          {
+            uri: "strapi://tools/guide",
+            mimeType: "text/markdown",
+            text: guideMarkdown
+          }
+        ]
+      };
+    }
+    throw new Error(`Resource not found: ${request.params.uri}`);
+  });
+  const toolNames = toolList.map((t) => t.name);
   strapi.log.info("[ai-sdk:mcp] MCP server created with tools:", { tools: toolNames });
+  strapi.log.debug("[ai-sdk:mcp] Server instructions:", instructions);
   return server;
 }
 const DEFAULT_MODEL = "claude-sonnet-4-20250514";
@@ -260,6 +513,15 @@ class AIProvider {
 class ToolRegistry {
   constructor() {
     this.tools = /* @__PURE__ */ new Map();
+    this.sourceMeta = /* @__PURE__ */ new Map();
+  }
+  /** Register metadata for a tool source (plugin namespace) */
+  setSourceMeta(sourceId, meta) {
+    this.sourceMeta.set(sourceId, meta);
+  }
+  /** Get metadata for a tool source, if provided */
+  getSourceMeta(sourceId) {
+    return this.sourceMeta.get(sourceId);
   }
   register(def) {
     this.tools.set(def.name, def);
@@ -1472,6 +1734,13 @@ function discoverPluginTools(strapi, registry) {
       const count = registerContributedTools(strapi, registry, pluginName, contributed);
       if (count > 0) {
         strapi.log.info(`[${PLUGIN_ID$2}] Registered ${count} tools from plugin: ${pluginName}`);
+        const safeName = pluginName.replace(/[^a-zA-Z0-9_-]/g, "_");
+        if (typeof aiToolsService.getMeta === "function") {
+          const meta = aiToolsService.getMeta();
+          if (meta?.label && meta?.description) {
+            registry.setSourceMeta(safeName, meta);
+          }
+        }
       }
     } catch (err) {
       strapi.log.warn(`[${PLUGIN_ID$2}] Tool discovery failed for ${pluginName}: ${err}`);

package/dist/server/src/lib/tool-registry.d.ts

@@ -16,8 +16,22 @@ export interface ToolDefinition {
 }
 /** Type alias for external plugin authors to import when contributing tools */
 export type AiToolContribution = ToolDefinition;
+/** Metadata a plugin can optionally provide to describe its tool source */
+export interface ToolSourceMeta {
+    /** Short human-readable label, e.g. "YouTube Transcripts" */
+    label: string;
+    /** One-line capability summary for MCP instructions */
+    description: string;
+    /** Trigger keywords/prefixes users might type, e.g. ["/youtube", "/yt", "transcript"] */
+    keywords?: string[];
+}
 export declare class ToolRegistry {
     private readonly tools;
+    private readonly sourceMeta;
+    /** Register metadata for a tool source (plugin namespace) */
+    setSourceMeta(sourceId: string, meta: ToolSourceMeta): void;
+    /** Get metadata for a tool source, if provided */
+    getSourceMeta(sourceId: string): ToolSourceMeta | undefined;
     register(def: ToolDefinition): void;
     unregister(name: string): boolean;
     get(name: string): ToolDefinition | undefined;

package/dist/server/src/lib/types.d.ts

@@ -1,5 +1,5 @@
 import type { ModelMessage, ToolSet, StopCondition } from 'ai';
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import type { AIProvider } from './ai-provider';
 import type { ToolRegistry } from './tool-registry';
@@ -72,14 +72,14 @@ export interface StreamTextResult {
 }
 export declare function isPromptInput(input: GenerateInput): input is PromptInput;
 export interface MCPSession {
-    server: McpServer;
+    server: Server;
     transport: StreamableHTTPServerTransport;
     createdAt: number;
 }
 export interface PluginInstance {
     aiProvider?: AIProvider;
     toolRegistry?: ToolRegistry;
-    createMcpServer?: (() => McpServer) | null;
+    createMcpServer?: (() => Server) | null;
     mcpSessions?: Map<string, MCPSession> | null;
 }
 export {};

package/dist/server/src/mcp/server.d.ts

@@ -1,7 +1,11 @@
 import type { Core } from '@strapi/strapi';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 /**
  * Create an MCP server instance configured with public tools from the registry.
  * Internal tools are excluded.
+ *
+ * Uses the low-level Server class (not McpServer) for full control over
+ * the JSON Schema output, ensuring compatibility with mcp-remote and
+ * Claude Desktop regardless of Zod version.
  */
-export declare function createMcpServer(strapi: Core.Strapi): McpServer;
+export declare function createMcpServer(strapi: Core.Strapi): Server;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.8.0",
+  "version": "0.10.0",
   "keywords": [
     "strapi",
     "strapi-plugin",