strapi-plugin-ai-sdk 0.6.9 → 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/_chunks/{App-C_BH5Ir4.js → App-BGIUzHMh.js}

@@ -6,7 +6,7 @@ const reactRouterDom = require("react-router-dom");
 const designSystem = require("@strapi/design-system");
 const react = require("react");
 const styled = require("styled-components");
-const index = require("./index-DCEjJ0as.js");
+const index = require("./index-BNk29VRc.js");
 const icons = require("@strapi/icons");
 const Markdown = require("react-markdown");
 const remarkGfm = require("remark-gfm");
@@ -618,6 +618,267 @@ function MemoryPanel({ memories, open, onDelete }) {
     ] })
   ] });
 }
+const SCORE_LABELS = {
+  1: "Negligible",
+  2: "Minor",
+  3: "Moderate",
+  4: "Significant",
+  5: "Critical"
+};
+const Card = styled__default.default.div`
+  margin-top: 8px;
+  border: 1px solid #dcdce4;
+  border-radius: 8px;
+  padding: 14px 16px;
+  background: #fff;
+  font-size: 13px;
+`;
+const Title = styled__default.default.div`
+  font-weight: 700;
+  font-size: 14px;
+  color: #32324d;
+  margin-bottom: 2px;
+`;
+const Description = styled__default.default.div`
+  color: #8e8ea9;
+  font-size: 12px;
+  margin-bottom: 10px;
+`;
+const Row = styled__default.default.div`
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-bottom: 8px;
+  flex-wrap: wrap;
+`;
+const Label = styled__default.default.label`
+  font-size: 12px;
+  font-weight: 600;
+  color: #666687;
+  min-width: 80px;
+`;
+const Select = styled__default.default.select`
+  padding: 4px 8px;
+  border: 1px solid #dcdce4;
+  border-radius: 4px;
+  font-size: 12px;
+  background: #fff;
+  color: #32324d;
+`;
+const DateInput = styled__default.default.input`
+  padding: 4px 8px;
+  border: 1px solid #dcdce4;
+  border-radius: 4px;
+  font-size: 12px;
+  color: #32324d;
+`;
+const AsapButton = styled__default.default.button`
+  padding: 4px 10px;
+  border: none;
+  border-radius: 4px;
+  background: #4945ff;
+  color: #fff;
+  font-size: 11px;
+  font-weight: 600;
+  cursor: pointer;
+
+  &:hover {
+    background: #3b38e0;
+  }
+`;
+const ScorePreview = styled__default.default.div`
+  font-size: 12px;
+  color: #666687;
+  margin-bottom: 10px;
+  font-weight: 500;
+`;
+const CreateButton = styled__default.default.button`
+  padding: 8px 18px;
+  border: none;
+  border-radius: 4px;
+  background: #4945ff;
+  color: #fff;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+
+  &:disabled {
+    background: #a5a5ba;
+    cursor: not-allowed;
+  }
+
+  &:not(:disabled):hover {
+    background: #3b38e0;
+  }
+`;
+const SuccessBanner = styled__default.default.div`
+  margin-top: 8px;
+  border: 1px solid #c6f0c2;
+  border-radius: 8px;
+  padding: 14px 16px;
+  background: #eafbe7;
+  font-size: 13px;
+  color: #2f6846;
+`;
+const SuccessTitle = styled__default.default.div`
+  font-weight: 700;
+  margin-bottom: 4px;
+`;
+const TaskLink = styled__default.default(reactRouterDom.Link)`
+  color: #4945ff;
+  font-weight: 600;
+  text-decoration: none;
+  font-size: 12px;
+
+  &:hover {
+    text-decoration: underline;
+  }
+`;
+const ErrorText = styled__default.default.div`
+  color: #d02b20;
+  font-size: 12px;
+  margin-top: 4px;
+`;
+function TaskConfirmCard({ proposed }) {
+  const [consequence, setConsequence] = react.useState(null);
+  const [impact, setImpact] = react.useState(null);
+  const [dueDate, setDueDate] = react.useState(proposed.dueDate ?? "");
+  const [submitting, setSubmitting] = react.useState(false);
+  const [created, setCreated] = react.useState(null);
+  const [error, setError] = react.useState(null);
+  const score = consequence != null && impact != null ? consequence * impact : null;
+  async function handleCreate() {
+    if (consequence == null || impact == null) return;
+    setSubmitting(true);
+    setError(null);
+    try {
+      const token = getToken();
+      const backend = getBackendURL();
+      const res = await fetch(`${backend}/ai-sdk/tasks`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...token ? { Authorization: `Bearer ${token}` } : {}
+        },
+        body: JSON.stringify({
+          title: proposed.title,
+          description: proposed.description,
+          content: proposed.content,
+          priority: proposed.priority,
+          consequence,
+          impact,
+          dueDate: dueDate || void 0
+        })
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(body.error ?? `HTTP ${res.status}`);
+      }
+      const { data } = await res.json();
+      setCreated({
+        documentId: data.documentId,
+        title: data.title,
+        consequence: data.consequence,
+        impact: data.impact,
+        priority: data.priority
+      });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setSubmitting(false);
+    }
+  }
+  if (created) {
+    const s = created.consequence * created.impact;
+    return /* @__PURE__ */ jsxRuntime.jsxs(SuccessBanner, { children: [
+      /* @__PURE__ */ jsxRuntime.jsxs(SuccessTitle, { children: [
+        "Task created: ",
+        created.title
+      ] }),
+      /* @__PURE__ */ jsxRuntime.jsxs("span", { children: [
+        "Score: ",
+        created.consequence,
+        " x ",
+        created.impact,
+        " = ",
+        s,
+        " · Priority: ",
+        created.priority
+      ] }),
+      /* @__PURE__ */ jsxRuntime.jsx("div", { style: { marginTop: 6 }, children: /* @__PURE__ */ jsxRuntime.jsx(TaskLink, { to: `/content-manager/collection-types/plugin::ai-sdk.task/${created.documentId}`, children: "Open in Content Manager" }) })
+    ] });
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  return /* @__PURE__ */ jsxRuntime.jsxs(Card, { children: [
+    /* @__PURE__ */ jsxRuntime.jsx(Title, { children: proposed.title }),
+    proposed.description && /* @__PURE__ */ jsxRuntime.jsx(Description, { children: proposed.description }),
+    /* @__PURE__ */ jsxRuntime.jsxs(Row, { children: [
+      /* @__PURE__ */ jsxRuntime.jsx(Label, { children: "Consequence" }),
+      /* @__PURE__ */ jsxRuntime.jsxs(
+        Select,
+        {
+          value: consequence ?? "",
+          onChange: (e) => setConsequence(e.target.value ? Number(e.target.value) : null),
+          children: [
+            /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", children: "Select…" }),
+            [1, 2, 3, 4, 5].map((n) => /* @__PURE__ */ jsxRuntime.jsxs("option", { value: n, children: [
+              n,
+              " — ",
+              SCORE_LABELS[n]
+            ] }, n))
+          ]
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsxRuntime.jsxs(Row, { children: [
+      /* @__PURE__ */ jsxRuntime.jsx(Label, { children: "Impact" }),
+      /* @__PURE__ */ jsxRuntime.jsxs(
+        Select,
+        {
+          value: impact ?? "",
+          onChange: (e) => setImpact(e.target.value ? Number(e.target.value) : null),
+          children: [
+            /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", children: "Select…" }),
+            [1, 2, 3, 4, 5].map((n) => /* @__PURE__ */ jsxRuntime.jsxs("option", { value: n, children: [
+              n,
+              " — ",
+              SCORE_LABELS[n]
+            ] }, n))
+          ]
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsxRuntime.jsxs(Row, { children: [
+      /* @__PURE__ */ jsxRuntime.jsx(Label, { children: "Due date" }),
+      /* @__PURE__ */ jsxRuntime.jsx(
+        DateInput,
+        {
+          type: "date",
+          value: dueDate,
+          onChange: (e) => setDueDate(e.target.value)
+        }
+      ),
+      /* @__PURE__ */ jsxRuntime.jsx(AsapButton, { type: "button", onClick: () => setDueDate(today), children: "ASAP" })
+    ] }),
+    score != null && /* @__PURE__ */ jsxRuntime.jsxs(ScorePreview, { children: [
+      "Score: ",
+      consequence,
+      " x ",
+      impact,
+      " = ",
+      score
+    ] }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      CreateButton,
+      {
+        disabled: consequence == null || impact == null || submitting,
+        onClick: handleCreate,
+        children: submitting ? "Creating…" : "Create Task"
+      }
+    ),
+    error && /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { children: error })
+  ] });
+}
 function buildContentManagerUrl(contentType, documentId) {
   const base = `/content-manager/collection-types/${contentType}`;
   return documentId ? `${base}/${documentId}` : base;
@@ -663,6 +924,31 @@ function extractContentLinks(toolCall) {
   }
   return [];
 }
+const TASK_CONTENT_TYPE = "plugin::ai-sdk.task";
+function extractTaskLinks(toolCall) {
+  if (toolCall.toolName !== "manageTask" || toolCall.output == null) return [];
+  const output = toolCall.output;
+  if (!output.success) return [];
+  const data = output.data;
+  if (!data) return [];
+  if (!Array.isArray(data)) {
+    const docId = data.documentId;
+    const title = data.title || docId;
+    if (docId && title) {
+      return [{ label: title, to: buildContentManagerUrl(TASK_CONTENT_TYPE, docId) }];
+    }
+    return [];
+  }
+  const links = [];
+  for (const task of data.slice(0, 5)) {
+    const docId = task.documentId;
+    const title = task.title || docId;
+    if (docId && title) {
+      links.push({ label: title, to: buildContentManagerUrl(TASK_CONTENT_TYPE, docId) });
+    }
+  }
+  return links;
+}
 const ToolCallBox = styled__default.default.div`
   margin-top: 8px;
   border: 1px solid #dcdce4;
@@ -747,6 +1033,13 @@ const HIDDEN_TOOLS = /* @__PURE__ */ new Set();
 function ToolCallDisplay({ toolCall }) {
   const [expanded, setExpanded] = react.useState(false);
   const contentLinks = extractContentLinks(toolCall);
+  const taskLinks = extractTaskLinks(toolCall);
+  if (toolCall.toolName === "manageTask" && toolCall.output != null) {
+    const output = toolCall.output;
+    if (output.status === "pending_confirmation" && output.proposed) {
+      return /* @__PURE__ */ jsxRuntime.jsx(TaskConfirmCard, { proposed: output.proposed });
+    }
+  }
   return /* @__PURE__ */ jsxRuntime.jsxs(ToolCallBox, { children: [
     /* @__PURE__ */ jsxRuntime.jsxs(ToolCallHeader, { onClick: () => setExpanded(!expanded), children: [
       /* @__PURE__ */ jsxRuntime.jsx("span", { children: expanded ? "▼" : "▶" }),
@@ -756,7 +1049,10 @@ function ToolCallDisplay({ toolCall }) {
       ] }),
       toolCall.output === void 0 ? /* @__PURE__ */ jsxRuntime.jsx(Spinner, {}) : /* @__PURE__ */ jsxRuntime.jsx("span", { style: { marginLeft: "auto", fontWeight: 400, opacity: 0.6 }, children: "completed" })
     ] }),
-    contentLinks.length > 0 && /* @__PURE__ */ jsxRuntime.jsx(ContentLinksRow, { children: contentLinks.map((link) => /* @__PURE__ */ jsxRuntime.jsx(ContentLinkChip, { to: link.to, children: link.label }, link.to)) }),
+    (contentLinks.length > 0 || taskLinks.length > 0) && /* @__PURE__ */ jsxRuntime.jsxs(ContentLinksRow, { children: [
+      contentLinks.map((link) => /* @__PURE__ */ jsxRuntime.jsx(ContentLinkChip, { to: link.to, children: link.label }, link.to)),
+      taskLinks.map((link) => /* @__PURE__ */ jsxRuntime.jsx(ContentLinkChip, { to: link.to, children: link.label }, link.to))
+    ] }),
     expanded && /* @__PURE__ */ jsxRuntime.jsx(ToolCallContent, { children: toolCall.output === void 0 ? "Waiting for result..." : JSON.stringify(toolCall.output, null, 2) })
   ] });
 }