strapi-plugin-ai-sdk 0.6.10 → 0.7.0

package/README.md

@@ -286,9 +286,12 @@ The AI assistant has access to these tools. Tools marked as **public** are also
 |------|----------|-------------|
 | `listContentTypes` | `list_content_types` | List all Strapi content types and components with their fields and relations |
 | `searchContent` | `search_content` | Search and query any content type with filters, sorting, and pagination |
+| `aggregateContent` | `aggregate_content` | Count, group, and analyze content (faster than searchContent for analytics) |
 | `writeContent` | `write_content` | Create or update documents in any content type |
 | `sendEmail` | `send_email` | Send emails via the configured email provider (e.g. Resend) |
 
+Additionally, the AI SDK automatically discovers tools from other installed plugins (see [Extending the Plugin](#adding-tools-from-other-plugins-convention-based-discovery)). For example, with the mentions and embeddings plugins installed, the AI also has access to `searchMentions`, `semanticSearch`, `ragQuery`, and more.
+
 ### Tool Details
 
 **searchContent** parameters: `contentType` (required), `query`, `filters`, `fields`, `sort`, `page`, `pageSize` (max 50)
@@ -465,7 +468,151 @@ curl -N -X POST http://localhost:1337/api/ai-sdk/ask-stream \
 
 ## Extending the Plugin
 
-### Adding a Custom Tool
+### Adding Tools from Other Plugins (Convention-Based Discovery)
+
+Any Strapi plugin can contribute tools to the AI SDK by exposing an `ai-tools` service with a `getTools()` method. The AI SDK discovers these automatically at boot time -- no configuration required.
+
+```mermaid
+flowchart LR
+  subgraph "AI SDK Bootstrap"
+    B[Scan all plugins]
+  end
+
+  subgraph "Plugin A"
+    A1[ai-tools service] --> A2["getTools()"]
+  end
+
+  subgraph "Plugin B"
+    B1[ai-tools service] --> B2["getTools()"]
+  end
+
+  B --> A1
+  B --> B1
+  A2 --> R[ToolRegistry]
+  B2 --> R
+  R --> Chat[Admin Chat]
+  R --> MCP[MCP Server]
+  R --> Public[Public Chat]
+```
+
+#### How It Works
+
+1. On startup, the AI SDK scans every loaded plugin for an `ai-tools` service
+2. If found, it calls `getTools()` which returns an array of `ToolDefinition` objects
+3. Each tool is namespaced as `pluginName__toolName` (e.g., `octalens_mentions__searchMentions`) to prevent collisions
+4. Discovered tools are registered in the shared `ToolRegistry` alongside built-in tools
+5. All registered tools are available in admin chat, public chat (if `publicSafe: true`), and MCP
+
+#### Creating an `ai-tools` Service in Your Plugin
+
+**1. Define canonical tools** in `server/src/tools/`:
+
+```typescript
+// server/src/tools/my-tool.ts
+import { z } from 'zod';
+import type { Core } from '@strapi/strapi';
+
+const schema = z.object({
+  query: z.string().describe('Search query'),
+  limit: z.number().min(1).max(50).optional().default(10).describe('Max results'),
+});
+
+export const mySearchTool = {
+  name: 'mySearch',
+  description: 'Search my plugin data with relevance ranking.',
+  schema,
+  execute: async (args: z.infer<typeof schema>, strapi: Core.Strapi) => {
+    const validated = schema.parse(args);
+    const results = await strapi.documents('plugin::my-plugin.item' as any).findMany({
+      filters: { title: { $containsi: validated.query } },
+      limit: validated.limit,
+    });
+    return { results, total: results.length };
+  },
+  publicSafe: true, // available in public chat (read-only operations)
+};
+```
+
+**2. Create the `ai-tools` service:**
+
+```typescript
+// server/src/services/ai-tools.ts
+import type { Core } from '@strapi/strapi';
+import { tools } from '../tools';
+
+export default ({ strapi }: { strapi: Core.Strapi }) => ({
+  getTools() {
+    return tools;
+  },
+});
+```
+
+**3. Register the service:**
+
+```typescript
+// server/src/services/index.ts
+import myService from './my-service';
+import aiTools from './ai-tools';
+
+export default {
+  'my-service': myService,
+  'ai-tools': aiTools,
+};
+```
+
+That's it. The AI SDK will discover and register your tools on the next Strapi restart.
+
+#### ToolDefinition Interface
+
+```typescript
+interface ToolDefinition {
+  name: string;                    // camelCase, unique within your plugin
+  description: string;             // Clear description for the AI model
+  schema: z.ZodObject<any>;        // Zod schema for parameter validation
+  execute: (args: any, strapi: Core.Strapi, context?: ToolContext) => Promise<unknown>;
+  internal?: boolean;              // If true, hidden from MCP (AI chat only)
+  publicSafe?: boolean;            // If true, available in public/widget chat
+}
+```
+
+#### 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:
+
+```mermaid
+flowchart TB
+  subgraph "Your Plugin"
+    T["server/src/tools/<br/>Canonical tool definitions<br/>(Zod schema + business logic)"]
+
+    subgraph "AI SDK Path"
+      S["services/ai-tools.ts<br/>getTools() → tools array"]
+    end
+
+    subgraph "MCP Path"
+      M["mcp/tools/*.ts<br/>Thin wrappers → MCP envelope"]
+      MS["mcp/server.ts"]
+    end
+
+    T --> S
+    T --> M
+    M --> MS
+  end
+
+  S -->|"Discovery"| SDK["AI SDK ToolRegistry"]
+  MS -->|"JSON-RPC"| Clients["Claude Desktop / Cursor"]
+```
+
+This eliminates duplication -- business logic lives in one place, and each consumer (AI SDK, MCP) uses a thin adapter.
+
+#### Real-World Examples
+
+Two plugins already use this pattern:
+
+**[strapi-octolens-mentions-plugin](../strapi-octolens-mentions-plugin/)** -- Contributes 4 tools: `searchMentions` (BM25 relevance search), `listMentions`, `getMention`, `updateMention`
+
+**[strapi-content-embeddings](../strapi-content-embeddings/)** -- Contributes 5 tools: `semanticSearch` (vector similarity), `ragQuery` (RAG), `listEmbeddings`, `getEmbedding`, `createEmbedding`
+
+### Adding a Custom Tool (Without a Plugin)
 
 **Option A: Inside the plugin** -- create files in `tools/definitions/` and `tool-logic/`, add to the `builtInTools` array.
 
@@ -578,7 +725,7 @@ Error response format:
 server/src/
   index.ts                    # Server entry point
   register.ts                 # Plugin register lifecycle
-  bootstrap.ts                # Initialize providers, tools, MCP
+  bootstrap.ts                # Initialize providers, tools, MCP, plugin tool discovery
   destroy.ts                  # Graceful shutdown
   config/index.ts             # Plugin config defaults
   guardrails/                 # Input safety middleware
@@ -650,6 +797,8 @@ STRAPI_TOKEN=your-api-token npm run test:guardrails
 ## Documentation
 
 - [Architecture](./docs/architecture.md) -- full system architecture, data flows, extension guides
+- [Plugin Tool Discovery](./docs/plugin-tool-discovery.md) -- cross-plugin tool discovery architecture and implementation
+- [Tool Standardization Spec](./docs/tool-standardization-spec.md) -- canonical tool format, Zod-first vs MCP-native comparison, portability
 - [Guardrails](./docs/guardrails.md) -- guardrail system, pattern lists, `beforeProcess` hook API
 - [Sending Emails with Resend](./docs/sending-emails-with-resend.md) -- Resend setup, email tool, domain verification
 

package/dist/server/index.js

@@ -31,7 +31,7 @@ function _interopNamespace(e) {
 const fs__namespace = /* @__PURE__ */ _interopNamespace(fs$1);
 const path__namespace = /* @__PURE__ */ _interopNamespace(path$1);
 function toSnakeCase(str) {
-  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+  return str.replace(/:/g, "__").replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
 function createMcpServer(strapi) {
   const plugin = strapi.plugin("ai-sdk");
@@ -1225,6 +1225,51 @@ const bootstrap = ({ strapi }) => {
     toolRegistry.register(tool);
   }
   plugin.toolRegistry = toolRegistry;
+  const pluginNames = Object.keys(strapi.plugins).filter((n) => n !== PLUGIN_ID$2);
+  strapi.log.info(`[${PLUGIN_ID$2}] Scanning ${pluginNames.length} plugins for ai-tools: [${pluginNames.join(", ")}]`);
+  for (const [pluginName, pluginInstance] of Object.entries(strapi.plugins)) {
+    if (pluginName === PLUGIN_ID$2) continue;
+    try {
+      let aiToolsService = null;
+      try {
+        aiToolsService = strapi.plugin(pluginName)?.service?.("ai-tools");
+      } catch {
+      }
+      if (!aiToolsService) {
+        try {
+          aiToolsService = pluginInstance.service?.("ai-tools");
+        } catch {
+        }
+      }
+      if (!aiToolsService?.getTools) {
+        strapi.log.debug(`[${PLUGIN_ID$2}] No ai-tools service on plugin: ${pluginName}`);
+        continue;
+      }
+      strapi.log.info(`[${PLUGIN_ID$2}] Found ai-tools service on plugin: ${pluginName}`);
+      const contributed = aiToolsService.getTools();
+      if (!Array.isArray(contributed)) continue;
+      let count = 0;
+      for (const tool of contributed) {
+        if (!tool.name || !tool.execute || !tool.schema) {
+          strapi.log.warn(`[${PLUGIN_ID$2}] Invalid tool from ${pluginName}: ${tool.name || "unnamed"}`);
+          continue;
+        }
+        const safeName = pluginName.replace(/[^a-zA-Z0-9_-]/g, "_");
+        const namespacedName = `${safeName}__${tool.name}`;
+        if (toolRegistry.has(namespacedName)) {
+          strapi.log.warn(`[${PLUGIN_ID$2}] Duplicate tool: ${namespacedName}`);
+          continue;
+        }
+        toolRegistry.register({ ...tool, name: namespacedName });
+        count++;
+      }
+      if (count > 0) {
+        strapi.log.info(`[${PLUGIN_ID$2}] Registered ${count} tools from plugin: ${pluginName}`);
+      }
+    } catch (err) {
+      strapi.log.warn(`[${PLUGIN_ID$2}] Tool discovery failed for ${pluginName}: ${err}`);
+    }
+  }
   plugin.createMcpServer = () => createMcpServer(strapi);
   plugin.mcpSessions = /* @__PURE__ */ new Map();
   strapi.log.info(`[${PLUGIN_ID$2}] MCP endpoint available at: /api/${PLUGIN_ID$2}/mcp`);
@@ -2598,6 +2643,8 @@ const DEFAULT_PREAMBLE = `You are a Strapi CMS assistant. Use your tools to fulf
 
 For analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.
 
+Plugin tools: When specialized tools from plugins are available (listed below), ALWAYS prefer them over the generic searchContent tool. For example, use searchMentions for social mentions (it has BM25 relevance scoring), semanticSearch for vector similarity search across embeddings, and ragQuery for question-answering grounded in embedded content. Only fall back to searchContent when no specialized tool covers the query.
+
 Strapi filter syntax for searchContent and aggregateContent:
 - Scalar fields: { title: { $containsi: "hello" } }
 - Relation (manyToOne): { author: { name: { $eq: "John" } } }

package/dist/server/index.mjs

@@ -11,7 +11,7 @@ import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 function toSnakeCase(str) {
-  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+  return str.replace(/:/g, "__").replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
 function createMcpServer(strapi) {
   const plugin = strapi.plugin("ai-sdk");
@@ -1205,6 +1205,51 @@ const bootstrap = ({ strapi }) => {
     toolRegistry.register(tool2);
   }
   plugin.toolRegistry = toolRegistry;
+  const pluginNames = Object.keys(strapi.plugins).filter((n) => n !== PLUGIN_ID$2);
+  strapi.log.info(`[${PLUGIN_ID$2}] Scanning ${pluginNames.length} plugins for ai-tools: [${pluginNames.join(", ")}]`);
+  for (const [pluginName, pluginInstance] of Object.entries(strapi.plugins)) {
+    if (pluginName === PLUGIN_ID$2) continue;
+    try {
+      let aiToolsService = null;
+      try {
+        aiToolsService = strapi.plugin(pluginName)?.service?.("ai-tools");
+      } catch {
+      }
+      if (!aiToolsService) {
+        try {
+          aiToolsService = pluginInstance.service?.("ai-tools");
+        } catch {
+        }
+      }
+      if (!aiToolsService?.getTools) {
+        strapi.log.debug(`[${PLUGIN_ID$2}] No ai-tools service on plugin: ${pluginName}`);
+        continue;
+      }
+      strapi.log.info(`[${PLUGIN_ID$2}] Found ai-tools service on plugin: ${pluginName}`);
+      const contributed = aiToolsService.getTools();
+      if (!Array.isArray(contributed)) continue;
+      let count = 0;
+      for (const tool2 of contributed) {
+        if (!tool2.name || !tool2.execute || !tool2.schema) {
+          strapi.log.warn(`[${PLUGIN_ID$2}] Invalid tool from ${pluginName}: ${tool2.name || "unnamed"}`);
+          continue;
+        }
+        const safeName = pluginName.replace(/[^a-zA-Z0-9_-]/g, "_");
+        const namespacedName = `${safeName}__${tool2.name}`;
+        if (toolRegistry.has(namespacedName)) {
+          strapi.log.warn(`[${PLUGIN_ID$2}] Duplicate tool: ${namespacedName}`);
+          continue;
+        }
+        toolRegistry.register({ ...tool2, name: namespacedName });
+        count++;
+      }
+      if (count > 0) {
+        strapi.log.info(`[${PLUGIN_ID$2}] Registered ${count} tools from plugin: ${pluginName}`);
+      }
+    } catch (err) {
+      strapi.log.warn(`[${PLUGIN_ID$2}] Tool discovery failed for ${pluginName}: ${err}`);
+    }
+  }
   plugin.createMcpServer = () => createMcpServer(strapi);
   plugin.mcpSessions = /* @__PURE__ */ new Map();
   strapi.log.info(`[${PLUGIN_ID$2}] MCP endpoint available at: /api/${PLUGIN_ID$2}/mcp`);
@@ -2578,6 +2623,8 @@ const DEFAULT_PREAMBLE = `You are a Strapi CMS assistant. Use your tools to fulf
 
 For analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.
 
+Plugin tools: When specialized tools from plugins are available (listed below), ALWAYS prefer them over the generic searchContent tool. For example, use searchMentions for social mentions (it has BM25 relevance scoring), semanticSearch for vector similarity search across embeddings, and ragQuery for question-answering grounded in embedded content. Only fall back to searchContent when no specialized tool covers the query.
+
 Strapi filter syntax for searchContent and aggregateContent:
 - Scalar fields: { title: { $containsi: "hello" } }
 - Relation (manyToOne): { author: { name: { $eq: "John" } } }

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

@@ -13,6 +13,8 @@ export interface ToolDefinition {
     /** If true, tool is safe for unauthenticated public chat (read-only) */
     publicSafe?: boolean;
 }
+/** Type alias for external plugin authors to import when contributing tools */
+export type AiToolContribution = ToolDefinition;
 export declare class ToolRegistry {
     private readonly tools;
     register(def: ToolDefinition): void;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.10",
+  "version": "0.7.0",
   "keywords": [
     "strapi",
     "strapi-plugin",