@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-development/references/official-plugins.md

@@ -1,18 +1,25 @@
+---
+name: official-plugins
+description: Guide to the 6 official plugins for discovery, memory, auth, caching, flags, and monitoring
+---
+
 # Official FrontMCP Plugins
 
-FrontMCP ships 6 official plugins that extend server behavior with cross-cutting concerns: semantic tool discovery, session memory, authorization workflows, result caching, feature gating, and visual monitoring. Install individually or via `@frontmcp/plugins` (meta-package re-exporting cache, codecall, dashboard, and remember).
+FrontMCP ships 6 official plugins that extend server behavior with cross-cutting concerns: semantic tool discovery, session memory, authorization workflows, result caching, feature gating, and visual monitoring. Install individually or via `@frontmcp/plugins` (meta-package re-exporting cache, codecall, and remember).
+
+> **Note:** The Dashboard plugin (`@frontmcp/plugin-dashboard`) is currently in **beta** and may not work correctly in all environments. It is not recommended for production use at this time.
 
 ## When to Use This Skill
 
 ### Must Use
 
-- Installing and configuring any official FrontMCP plugin (CodeCall, Remember, Approval, Cache, Feature Flags, Dashboard)
+- Installing and configuring any official FrontMCP plugin (CodeCall, Remember, Approval, Cache, Feature Flags)
 - Adding session memory, tool caching, or authorization workflows to an existing server
 - Integrating feature flag services (LaunchDarkly, Split.io, Unleash) to gate tools at runtime
 
 ### Recommended
 
-- Setting up the Dashboard plugin for visual monitoring of server structure in development
+- Exploring the Dashboard plugin for visual monitoring (beta — not recommended for production)
 - Configuring CodeCall for semantic tool discovery when the server has many tools
 - Combining multiple official plugins in a production deployment
 
@@ -22,7 +29,7 @@ FrontMCP ships 6 official plugins that extend server behavior with cross-cutting
 - You only need lifecycle hooks without installing an official plugin (see `create-plugin-hooks`)
 - You need to generate tools from an OpenAPI spec (see `official-adapters`)
 
-> **Decision:** Use this skill when you need to install, configure, or customize one or more of the 6 official FrontMCP plugins.
+> **Decision:** Use this skill when you need to install, configure, or customize one or more of the 5 stable official FrontMCP plugins. The Dashboard plugin is in beta — see its section below for details.
 
 All plugins follow the `DynamicPlugin` pattern and are registered via `@FrontMcp({ plugins: [...] })`.
 
@@ -33,7 +40,7 @@ import RememberPlugin from '@frontmcp/plugin-remember';
 import { ApprovalPlugin } from '@frontmcp/plugin-approval';
 import CachePlugin from '@frontmcp/plugin-cache';
 import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
-import DashboardPlugin from '@frontmcp/plugin-dashboard';
+// import DashboardPlugin from '@frontmcp/plugin-dashboard'; // Beta — not recommended for production
 
 @App({ name: 'MyApp' })
 class MyApp {}
@@ -47,7 +54,7 @@ class MyApp {}
     ApprovalPlugin.init({ mode: 'recheck' }),
     CachePlugin.init({ type: 'memory', defaultTTL: 86400 }),
     FeatureFlagPlugin.init({ adapter: 'static', flags: { 'new-tool': true } }),
-    DashboardPlugin.init({ enabled: true }),
+    // DashboardPlugin.init({ enabled: true }), // Beta — see Dashboard section below
   ],
   tools: [
     /* your tools */
@@ -90,10 +97,25 @@ class MyServer {}
 
 ### Modes
 
-- `codecall_only` -- Hides all tools from `list_tools` except CodeCall meta-tools. All other tools are discovered only via `codecall:search`. Best when the server has a large number of tools and you want the AI to search-then-execute.
+- `codecall_only` -- Hides all tools from `list_tools` except CodeCall meta-tools. All other tools are discovered only via `codecall:search`. Best when the server has a large number of tools and you want the AI to search-then-execute. When `appIds` is set, only tools from those apps are hidden — tools from other apps remain visible.
 - `codecall_opt_in` -- Shows all tools in `list_tools` normally. Tools opt-in to CodeCall execution via metadata. Useful when only some tools benefit from orchestrated execution.
 - `metadata_driven` -- Per-tool `metadata.codecall` controls visibility and CodeCall availability independently. Most granular control.
 
+### Multi-App Scoping
+
+Use `appIds` to scope CodeCall to specific apps in a multi-app server:
+
+```typescript
+// Only hide ecommerce tools — calc tools remain visible in list_tools
+CodeCallPlugin.init({
+  mode: 'codecall_only',
+  appIds: ['ecommerce'],
+  vm: { preset: 'secure' },
+});
+```
+
+Without `appIds`, `codecall_only` mode hides ALL tools in the server. With `appIds`, only tools from the specified apps are hidden — tools from other apps remain directly callable.
+
 ### VM Presets
 
 The sandboxed VM runs AgentScript (a restricted JavaScript subset). Presets control security boundaries:
@@ -107,9 +129,9 @@ The sandboxed VM runs AgentScript (a restricted JavaScript subset). Presets cont
 
 CodeCall contributes 4 tools to your server:
 
-- `codecall:search` -- Semantic search over all registered tools using TF-IDF scoring with synonym expansion. Returns ranked tool names, descriptions, and relevance scores.
-- `codecall:describe` -- Returns full input/output JSON schemas for one or more tools. Use after search to understand tool interfaces before execution.
-- `codecall:execute` -- Runs an AgentScript program in the sandboxed VM. The script can call multiple tools, branch on results, and compose outputs.
+- `codecall:search` -- Semantic search over all registered tools using TF-IDF scoring with synonym expansion. Input: `{ queries: string[] }` (array of atomic action phrases, max 10). Decompose complex requests into simple actions (e.g., "delete users and send email" becomes `queries: ["delete user", "send email"]`). Returns ranked tool names, descriptions, and relevance scores.
+- `codecall:describe` -- Returns full input/output JSON schemas for one or more tools. Input: `{ toolNames: string[] }` (tool names from search results). Use after search to understand tool interfaces before execution. If `notFound` array is non-empty in the response, re-search with corrected queries.
+- `codecall:execute` -- Runs an AgentScript program in the sandboxed VM. Input: `{ script: string }` (AgentScript code). Use `callTool(name, args)` to invoke tools within scripts. The script can call multiple tools, branch on results, and compose outputs.
 - `codecall:invoke` -- Direct single-tool invocation (available when `directCalls` is enabled). Bypasses the VM for simple one-shot calls.
 
 ### Per-Tool CodeCall Metadata
@@ -580,7 +602,9 @@ The plugin hooks into listing and execution flows for tools, resources, prompts,
 
 ---
 
-## 6. Dashboard Plugin (`@frontmcp/plugin-dashboard`)
+## 6. Dashboard Plugin (`@frontmcp/plugin-dashboard`) — BETA
+
+> **Warning:** The Dashboard plugin is currently in **beta** and may not work correctly. It is not recommended for production use. Expect breaking changes and missing features.
 
 Visual monitoring web UI for your FrontMCP server. View server structure (tools, resources, prompts, apps, plugins) as an interactive graph.
 
@@ -656,7 +680,7 @@ All official plugins use the static `init()` pattern inherited from `DynamicPlug
     ApprovalPlugin.init({ mode: 'recheck' }),
     CachePlugin.init({ type: 'redis', config: { host: 'redis.internal' }, defaultTTL: 86400 }),
     FeatureFlagPlugin.init({ adapter: 'launchdarkly', config: { sdkKey: 'sdk-xxx' } }),
-    DashboardPlugin.init({ enabled: true, auth: { enabled: true, token: process.env.DASH_TOKEN } }),
+    // DashboardPlugin.init({ enabled: true, auth: { ... } }), // Beta — not recommended for production
   ],
   tools: [
     /* ... */
@@ -667,13 +691,13 @@ class ProductionServer {}
 
 ## Common Patterns
 
-| Pattern                  | Correct                                                                          | Incorrect                                                                       | Why                                                                                                      |
-| ------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| Plugin registration      | `plugins: [RememberPlugin.init({ type: 'memory' })]`                             | `plugins: [new RememberPlugin({ type: 'memory' })]`                             | Official plugins use `DynamicPlugin.init()` static method; direct instantiation bypasses provider wiring |
-| Remember storage in prod | `RememberPlugin.init({ type: 'redis', config: { host: '...' } })`                | `RememberPlugin.init({ type: 'memory' })` in production                         | Memory storage loses data on restart; use Redis or Vercel KV for persistence                             |
-| Cache TTL units          | `defaultTTL: 3600` (seconds)                                                     | `defaultTTL: 3600000` (milliseconds)                                            | Cache TTL is in seconds, not milliseconds; 3600000 = 41 days                                             |
-| Feature flag gating      | `@Tool({ featureFlag: 'my-flag' })` on the tool decorator                        | Checking `this.featureFlags.isEnabled()` inside `execute()` and returning early | Decorator-level gating hides the tool from `list_tools`; manual check still exposes it                   |
-| Dashboard in production  | `DashboardPlugin.init({ enabled: true, auth: { enabled: true, token: '...' } })` | `DashboardPlugin.init({})` without auth in production                           | Dashboard auto-disables in production; if enabled, always set auth token                                 |
+| Pattern                  | Correct                                                            | Incorrect                                                                       | Why                                                                                                      |
+| ------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Plugin registration      | `plugins: [RememberPlugin.init({ type: 'memory' })]`               | `plugins: [new RememberPlugin({ type: 'memory' })]`                             | Official plugins use `DynamicPlugin.init()` static method; direct instantiation bypasses provider wiring |
+| Remember storage in prod | `RememberPlugin.init({ type: 'redis', config: { host: '...' } })`  | `RememberPlugin.init({ type: 'memory' })` in production                         | Memory storage loses data on restart; use Redis or Vercel KV for persistence                             |
+| Cache TTL units          | `defaultTTL: 3600` (seconds)                                       | `defaultTTL: 3600000` (milliseconds)                                            | Cache TTL is in seconds, not milliseconds; 3600000 = 41 days                                             |
+| Feature flag gating      | `@Tool({ featureFlag: 'my-flag' })` on the tool decorator          | Checking `this.featureFlags.isEnabled()` inside `execute()` and returning early | Decorator-level gating hides the tool from `list_tools`; manual check still exposes it                   |
+| Dashboard (beta)         | Avoid in production — plugin is in beta and may not work correctly | `DashboardPlugin.init({})` in production                                        | Dashboard plugin is unstable; use only for local development experimentation                             |
 
 ## Verification Checklist
 
@@ -688,24 +712,34 @@ class ProductionServer {}
 - [ ] `this.remember` / `this.approval` / `this.featureFlags` resolves in tool context
 - [ ] Cache plugin returns cached results on repeated identical calls
 - [ ] Feature-flagged tools are hidden from `list_tools` when flag is off
-- [ ] Dashboard is accessible at configured `basePath` (default: `/dashboard`)
+- [ ] Dashboard is accessible at configured `basePath` (default: `/dashboard`) — beta, may not work
 - [ ] Approval plugin blocks unapproved tools and grants approval correctly
 
 ### Production
 
 - [ ] Redis or external storage is configured for Remember and Cache plugins
-- [ ] Dashboard authentication is enabled with a secret token
+- [ ] Dashboard authentication is enabled with a secret token (if using beta Dashboard plugin)
 - [ ] Feature flag adapter connects to external service (not `'static'`)
 
 ## Troubleshooting
 
-| Problem                           | Cause                                                                            | Solution                                                                           |
-| --------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `this.remember` is undefined      | RememberPlugin not registered or missing `.init()`                               | Add `RememberPlugin.init({ type: 'memory' })` to `plugins` array                   |
-| Cache not working for a tool      | Tool name does not match any `toolPatterns` glob and `cache` metadata is not set | Add `cache: true` to `@Tool` decorator or add matching pattern to `toolPatterns`   |
-| Feature flag always returns false | Using `'static'` adapter with flag not in the `flags` map                        | Add the flag key to `flags: { 'my-flag': true }` or check adapter connection       |
-| Dashboard returns 404             | Plugin auto-disabled in production (`NODE_ENV=production`)                       | Set `enabled: true` explicitly in `DashboardPlugin.init()` options                 |
-| Approval webhook times out        | Callback URL not reachable from the external approval service                    | Verify `callbackPath` is publicly accessible and matches the webhook configuration |
+| Problem                           | Cause                                                                            | Solution                                                                             |
+| --------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `this.remember` is undefined      | RememberPlugin not registered or missing `.init()`                               | Add `RememberPlugin.init({ type: 'memory' })` to `plugins` array                     |
+| Cache not working for a tool      | Tool name does not match any `toolPatterns` glob and `cache` metadata is not set | Add `cache: true` to `@Tool` decorator or add matching pattern to `toolPatterns`     |
+| Feature flag always returns false | Using `'static'` adapter with flag not in the `flags` map                        | Add the flag key to `flags: { 'my-flag': true }` or check adapter connection         |
+| Dashboard returns 404             | Plugin is in beta and auto-disabled in production (`NODE_ENV=production`)        | Dashboard is unstable — avoid in production. For dev: set `enabled: true` explicitly |
+| Approval webhook times out        | Callback URL not reachable from the external approval service                    | Verify `callbackPath` is publicly accessible and matches the webhook configuration   |
+
+## Examples
+
+| Example                                                                                            | Level        | Description                                                                                                                                                                  |
+| -------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`cache-and-feature-flags`](../examples/official-plugins/cache-and-feature-flags.md)               | Intermediate | Demonstrates combining the Cache plugin for tool result caching with the Feature Flags plugin for gating tools behind flags.                                                 |
+| [`production-multi-plugin-setup`](../examples/official-plugins/production-multi-plugin-setup.md)   | Advanced     | Demonstrates a production-ready server configuration combining CodeCall, Remember, Approval, Cache, and Feature Flags plugins with Redis storage and external flag services. |
+| [`remember-plugin-session-memory`](../examples/official-plugins/remember-plugin-session-memory.md) | Basic        | Demonstrates installing the Remember plugin and using `this.remember` in tools to store and retrieve session memory.                                                         |
+
+> See all examples in [`examples/official-plugins/`](../examples/official-plugins/)
 
 ## Reference
 

package/catalog/frontmcp-extensibility/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: frontmcp-extensibility
+description: 'Extend FrontMCP servers with external npm packages and libraries. Covers VectoriaDB for semantic search, and patterns for integrating third-party services into providers and tools. Use when adding search, ML, database, or external API capabilities beyond the core SDK.'
+tags: [extensibility, vectoriadb, search, integration, npm, provider, external-services]
+category: extensibility
+targets: [all]
+bundle: [full]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/extensibility/providers
+---
+
+# FrontMCP Extensibility
+
+Patterns and examples for extending FrontMCP servers with external npm packages. The core SDK handles MCP protocol, DI, and lifecycle — this skill shows how to integrate third-party libraries as providers and tools.
+
+## When to Use This Skill
+
+### Must Use
+
+- Adding semantic search or similarity matching to your server (VectoriaDB)
+- Integrating an external npm package as a FrontMCP provider
+- Building tools that wrap third-party services (databases, APIs, ML models)
+
+### Recommended
+
+- Looking for patterns to structure external service integrations
+- Deciding between provider-based vs direct integration for a library
+- Adding capabilities like applescript automation, VM execution, or data processing
+
+### Skip When
+
+- You need to build core MCP components (see `frontmcp-development`)
+- You need to configure auth, transport, or CORS (see `frontmcp-config`)
+- You need to write a plugin with hooks and context extensions (see `create-plugin`)
+
+> **Decision:** Use this skill when integrating external libraries into your FrontMCP server as providers or tools.
+
+## Scenario Routing Table
+
+| Scenario                                      | Reference                                       | Description                                              |
+| --------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- |
+| Add in-memory semantic search with VectoriaDB | `references/vectoriadb.md`                      | TF-IDF indexing, field weighting, provider+tool pattern  |
+| Load an app from an npm package               | `multi-app-composition` (in frontmcp-setup)     | `App.esm('@scope/pkg@^1.0.0', 'AppName')` pattern        |
+| Connect to a remote MCP server                | `multi-app-composition` (in frontmcp-setup)     | `App.remote('https://...', 'ns')` pattern                |
+| Build a reusable plugin with hooks            | `create-plugin-hooks` (in frontmcp-development) | `DynamicPlugin`, context extensions, lifecycle hooks     |
+| Build a custom adapter for an external source | `create-adapter` (in frontmcp-development)      | `DynamicAdapter` for OpenAPI, GraphQL, or custom sources |
+| Auto-generate tools from an OpenAPI spec      | `official-adapters` (in frontmcp-development)   | `OpenapiAdapter` with filtering, auth, and transforms    |
+
+## Integration Pattern
+
+The standard pattern for integrating any external library:
+
+1. **Create a provider** — wraps the library as a singleton or scoped service
+2. **Register the provider** — add to `@App({ providers: [...] })` or `@FrontMcp({ providers: [...] })`
+3. **Create tools** — expose the provider's capabilities as MCP tools via `this.get(TOKEN)`
+4. **Optionally create resources** — expose data as MCP resources with autocompletion
+
+```typescript
+// 1. Provider wraps the library
+@Provider({ name: 'my-search', provide: SearchToken, scope: ProviderScope.GLOBAL })
+export class SearchProvider {
+  private client: ExternalLibrary;
+  constructor() {
+    this.client = new ExternalLibrary({
+      /* config */
+    });
+  }
+  async search(query: string) {
+    return this.client.query(query);
+  }
+}
+
+// 2. Tool exposes it
+@Tool({ name: 'search', inputSchema: { query: z.string() } })
+export default class SearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return this.get(SearchToken).search(input.query);
+  }
+}
+```
+
+## Available Integrations
+
+| Library        | Purpose                          | Reference                  |
+| -------------- | -------------------------------- | -------------------------- |
+| **VectoriaDB** | In-memory TF-IDF semantic search | `references/vectoriadb.md` |
+
+More integrations can be added as references (e.g., enclave-vm, applescript, database clients).
+
+## Verification Checklist
+
+- [ ] External library is in `dependencies` (not `devDependencies`)
+- [ ] Provider wraps the library with proper initialization and cleanup
+- [ ] Provider is registered in `@App` or `@FrontMcp` with a typed DI token
+- [ ] Tools use `this.get(TOKEN)` to access the provider (not direct imports)
+- [ ] Error handling wraps library-specific errors into MCP error classes
+
+## Reference
+
+- Related skills: `create-provider`, `create-tool`, `frontmcp-development`

package/catalog/frontmcp-extensibility/examples/vectoriadb/product-catalog-search.md

@@ -0,0 +1,175 @@
+---
+name: product-catalog-search
+reference: vectoriadb
+level: advanced
+description: 'Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog.'
+tags: [extensibility, vectoriadb, product, catalog, search]
+features:
+  - 'Typed document metadata with `ProductDoc extends DocumentMetadata`'
+  - 'Batch operations with `db.addMany()` for efficient catalog indexing'
+  - 'Multi-criteria filtered search combining category, price, and stock status'
+  - '`maxDocuments` option for DoS protection on large datasets'
+  - '`FileStorageAdapter` for persisting the entire product index to disk'
+  - 'Semantic matching: "something to block office noise" finds "noise-canceling headphones"'
+---
+
+# VectoriaDB: Product Catalog with Typed Metadata and Batch Operations
+
+Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog.
+
+## Code
+
+```typescript
+// src/providers/product-search.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+import { VectoriaDB, FileStorageAdapter } from 'vectoriadb';
+import type { DocumentMetadata } from 'vectoriadb';
+
+export const ProductSearch = Symbol('ProductSearch');
+
+// Typed metadata for product documents
+interface ProductDoc extends DocumentMetadata {
+  name: string;
+  category: string;
+  price: number;
+  inStock: boolean;
+}
+
+@Provider({ name: 'product-search', provide: ProductSearch, scope: ProviderScope.GLOBAL })
+export class ProductSearchProvider {
+  private db: VectoriaDB<ProductDoc>;
+  private ready: Promise<void>;
+
+  constructor() {
+    this.db = new VectoriaDB<ProductDoc>({
+      modelName: 'Xenova/all-MiniLM-L6-v2',
+      cacheDir: './.cache/transformers',
+      useHNSW: true,
+      defaultSimilarityThreshold: 0.3,
+      defaultTopK: 10,
+      maxDocuments: 100000, // DoS protection
+      storageAdapter: new FileStorageAdapter({ cacheDir: './.cache/product-vectors' }),
+    });
+    this.ready = this.db.initialize();
+  }
+
+  // Batch indexing for large catalogs
+  async indexProducts(
+    products: Array<{
+      id: string;
+      description: string;
+      name: string;
+      category: string;
+      price: number;
+      inStock: boolean;
+    }>,
+  ) {
+    await this.ready;
+
+    // Use addMany for efficient batch operations
+    await this.db.addMany(
+      products.map((p) => ({
+        id: p.id,
+        text: `${p.name}: ${p.description}`,
+        metadata: {
+          id: p.id,
+          name: p.name,
+          category: p.category,
+          price: p.price,
+          inStock: p.inStock,
+        },
+      })),
+    );
+
+    await this.db.saveToStorage();
+  }
+
+  // Multi-criteria filtered search
+  async search(query: string, filters?: { category?: string; maxPrice?: number; inStockOnly?: boolean }, limit = 10) {
+    await this.ready;
+
+    return this.db.search(query, {
+      topK: limit,
+      threshold: 0.4,
+      filter: (meta) => {
+        if (filters?.category && meta.category !== filters.category) return false;
+        if (filters?.maxPrice !== undefined && meta.price > filters.maxPrice) return false;
+        if (filters?.inStockOnly && !meta.inStock) return false;
+        return true;
+      },
+    });
+  }
+}
+```
+
+```typescript
+// src/tools/find-products.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { ProductSearch } from '../providers/product-search.provider';
+
+@Tool({
+  name: 'find_products',
+  description: 'Find products using natural language (e.g., "something to block office noise")',
+  inputSchema: {
+    query: z.string().min(1).describe('Natural language product search'),
+    category: z.string().optional().describe('Filter by category'),
+    maxPrice: z.number().positive().optional().describe('Maximum price'),
+    inStockOnly: z.boolean().default(true).describe('Only show in-stock products'),
+    limit: z.number().int().min(1).max(20).default(5).describe('Max results'),
+  },
+  outputSchema: {
+    products: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        category: z.string(),
+        price: z.number(),
+        score: z.number(),
+        inStock: z.boolean(),
+      }),
+    ),
+    total: z.number(),
+  },
+})
+export class FindProductsTool extends ToolContext {
+  async execute(input: { query: string; category?: string; maxPrice?: number; inStockOnly: boolean; limit: number }) {
+    const search = this.get(ProductSearch);
+
+    const results = await search.search(
+      input.query,
+      {
+        category: input.category,
+        maxPrice: input.maxPrice,
+        inStockOnly: input.inStockOnly,
+      },
+      input.limit,
+    );
+
+    return {
+      products: results.map((r) => ({
+        id: r.id,
+        name: r.metadata.name,
+        category: r.metadata.category,
+        price: r.metadata.price,
+        score: r.score,
+        inStock: r.metadata.inStock,
+      })),
+      total: results.length,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Typed document metadata with `ProductDoc extends DocumentMetadata`
+- Batch operations with `db.addMany()` for efficient catalog indexing
+- Multi-criteria filtered search combining category, price, and stock status
+- `maxDocuments` option for DoS protection on large datasets
+- `FileStorageAdapter` for persisting the entire product index to disk
+- Semantic matching: "something to block office noise" finds "noise-canceling headphones"
+
+## Related
+
+- See `vectoriadb` for the full configuration reference, engine comparison, and TFIDFVectoria examples

package/catalog/frontmcp-extensibility/examples/vectoriadb/semantic-search-with-persistence.md

@@ -0,0 +1,138 @@
+---
+name: semantic-search-with-persistence
+reference: vectoriadb
+level: intermediate
+description: 'Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.'
+tags: [extensibility, vectoriadb, semantic-search, semantic, search, persistence]
+features:
+  - 'Using `VectoriaDB` with transformer models for true semantic search'
+  - 'Configuring HNSW index (`useHNSW: true`) for fast O(log n) search on large datasets'
+  - 'Filtered search with a callback: `filter: (m) => m.category === category`'
+  - '`FileStorageAdapter` for persisting vectors to disk (restored without re-embedding)'
+  - 'Async initialization with `await db.initialize()` (downloads model on first run)'
+  - 'Update-or-add pattern with `db.has(id)` check'
+---
+
+# VectoriaDB: Semantic ML Search with Persistence
+
+Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.
+
+## Code
+
+```typescript
+// src/providers/knowledge-base.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+import { VectoriaDB, FileStorageAdapter } from 'vectoriadb';
+import type { DocumentMetadata } from 'vectoriadb';
+
+export const KnowledgeBase = Symbol('KnowledgeBase');
+
+interface Article extends DocumentMetadata {
+  title: string;
+  category: string;
+}
+
+@Provider({ name: 'knowledge-base', provide: KnowledgeBase, scope: ProviderScope.GLOBAL })
+export class KnowledgeBaseProvider {
+  private db: VectoriaDB<Article>;
+  private ready: Promise<void>;
+
+  constructor() {
+    this.db = new VectoriaDB<Article>({
+      modelName: 'Xenova/all-MiniLM-L6-v2', // Default transformer model
+      cacheDir: './.cache/transformers', // Model cache directory
+      useHNSW: true, // HNSW index for O(log n) search
+      defaultSimilarityThreshold: 0.4,
+      defaultTopK: 10,
+      storageAdapter: new FileStorageAdapter({ cacheDir: './.cache/kb-vectors' }),
+    });
+    // Initialize async — downloads model on first run
+    this.ready = this.db.initialize();
+  }
+
+  async search(query: string, options?: { category?: string; limit?: number }) {
+    await this.ready;
+    return this.db.search(query, {
+      topK: options?.limit ?? 10,
+      // Filtered search: narrow results by category
+      filter: options?.category ? (m) => m.category === options.category : undefined,
+    });
+  }
+
+  async index(id: string, text: string, metadata: Article) {
+    await this.ready;
+    // Update if exists, add if new
+    if (this.db.has(id)) {
+      await this.db.update(id, { text, metadata });
+    } else {
+      await this.db.add(id, text, metadata);
+    }
+    // Persist to disk — restored without re-embedding on next startup
+    await this.db.saveToStorage();
+  }
+
+  async loadFromDisk() {
+    await this.ready;
+    await this.db.loadFromStorage();
+  }
+}
+```
+
+```typescript
+// src/tools/semantic-search.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { KnowledgeBase } from '../providers/knowledge-base.provider';
+
+@Tool({
+  name: 'semantic_search',
+  description: 'Search the knowledge base using natural language (understands meaning, not just keywords)',
+  inputSchema: {
+    query: z.string().min(1).describe('Natural language search query'),
+    category: z.string().optional().describe('Filter by category'),
+    limit: z.number().int().min(1).max(20).default(5).describe('Max results'),
+  },
+  outputSchema: {
+    results: z.array(
+      z.object({
+        id: z.string(),
+        score: z.number(),
+        title: z.string(),
+        category: z.string(),
+      }),
+    ),
+  },
+})
+export class SemanticSearchTool extends ToolContext {
+  async execute(input: { query: string; category?: string; limit: number }) {
+    const kb = this.get(KnowledgeBase);
+
+    const results = await kb.search(input.query, {
+      category: input.category,
+      limit: input.limit,
+    });
+
+    return {
+      results: results.map((r) => ({
+        id: r.id,
+        score: r.score,
+        title: r.metadata.title,
+        category: r.metadata.category,
+      })),
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `VectoriaDB` with transformer models for true semantic search
+- Configuring HNSW index (`useHNSW: true`) for fast O(log n) search on large datasets
+- Filtered search with a callback: `filter: (m) => m.category === category`
+- `FileStorageAdapter` for persisting vectors to disk (restored without re-embedding)
+- Async initialization with `await db.initialize()` (downloads model on first run)
+- Update-or-add pattern with `db.has(id)` check
+
+## Related
+
+- See `vectoriadb` for the full configuration reference and engine comparison