@frontmcp/skills 1.0.0-beta.13 → 1.0.0-beta.14

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

package/catalog/frontmcp-extensibility/examples/vectoriadb/tfidf-keyword-search.md

@@ -0,0 +1,103 @@
+---
+name: tfidf-keyword-search
+reference: vectoriadb
+level: basic
+description: 'Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.'
+tags: [extensibility, vectoriadb, keyword-search, tfidf, keyword, search]
+features:
+  - 'Using `TFIDFVectoria` for zero-dependency keyword search (no model downloads)'
+  - 'Configuring field weights to control scoring influence'
+  - 'Calling `buildIndex()` after adding documents (required for TFIDFVectoria)'
+  - 'Wrapping the search engine in a FrontMCP provider with `ProviderScope.GLOBAL`'
+  - 'Injecting the provider into tools via `this.get(FAQSearch)`'
+---
+
+# TFIDFVectoria: Lightweight Keyword Search Provider
+
+Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.
+
+## Code
+
+```typescript
+// src/providers/faq-search.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+import { TFIDFVectoria } from 'vectoriadb';
+
+export const FAQSearch = Symbol('FAQSearch');
+
+@Provider({ name: 'faq-search', provide: FAQSearch, scope: ProviderScope.GLOBAL })
+export class FAQSearchProvider {
+  private db = new TFIDFVectoria({
+    fields: {
+      question: { weight: 3 }, // Question matches are 3x more important
+      answer: { weight: 1 }, // Answer matches are baseline
+      tags: { weight: 2 }, // Tag matches are 2x
+    },
+  });
+
+  async initialize(faqs: Array<{ id: string; question: string; answer: string; tags: string }>) {
+    for (const faq of faqs) {
+      this.db.addDocument(faq.id, {
+        question: faq.question,
+        answer: faq.answer,
+        tags: faq.tags,
+      });
+    }
+    // Required after adding documents — builds the TF-IDF index
+    this.db.buildIndex();
+  }
+
+  search(query: string, limit = 5) {
+    return this.db.search(query, limit);
+  }
+}
+```
+
+```typescript
+// src/tools/search-faq.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { FAQSearch } from '../providers/faq-search.provider';
+
+@Tool({
+  name: 'search_faq',
+  description: 'Search the FAQ knowledge base using keyword matching',
+  inputSchema: {
+    query: z.string().min(1).describe('Search query'),
+    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(),
+      }),
+    ),
+  },
+})
+export class SearchFaqTool extends ToolContext {
+  async execute(input: { query: string; limit: number }) {
+    const faqSearch = this.get(FAQSearch);
+    const results = faqSearch.search(input.query, input.limit);
+
+    return {
+      results: results.map((r) => ({
+        id: r.id,
+        score: r.score,
+      })),
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `TFIDFVectoria` for zero-dependency keyword search (no model downloads)
+- Configuring field weights to control scoring influence
+- Calling `buildIndex()` after adding documents (required for TFIDFVectoria)
+- Wrapping the search engine in a FrontMCP provider with `ProviderScope.GLOBAL`
+- Injecting the provider into tools via `this.get(FAQSearch)`
+
+## Related
+
+- See `vectoriadb` for the full API reference and engine comparison

package/catalog/frontmcp-extensibility/references/vectoriadb.md

@@ -282,6 +282,16 @@ export class KnowledgeBaseProvider {
 - [ ] Storage adapter configured if persistence is needed
 - [ ] Search tool injects provider via `this.get(TOKEN)`
 
+## Examples
+
+| Example                                                                                          | Level        | Description                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`product-catalog-search`](../examples/vectoriadb/product-catalog-search.md)                     | Advanced     | Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog. |
+| [`semantic-search-with-persistence`](../examples/vectoriadb/semantic-search-with-persistence.md) | Intermediate | Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.          |
+| [`tfidf-keyword-search`](../examples/vectoriadb/tfidf-keyword-search.md)                         | Basic        | Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.                             |
+
+> See all examples in [`examples/vectoriadb/`](../examples/vectoriadb/)
+
 ## Reference
 
 - [VectoriaDB Documentation](https://docs.agentfront.dev/vectoriadb/get-started/welcome)

package/catalog/frontmcp-guides/SKILL.md

@@ -9,7 +9,7 @@ priority: 10
 visibility: both
 license: Apache-2.0
 metadata:
-  docs: https://docs.agentfront.dev/frontmcp/guides/overview
+  docs: https://docs.agentfront.dev/frontmcp/guides/your-first-tool
 examples:
   - scenario: Build a simple weather API MCP server from scratch
     expected-outcome: Working server with tools, resources, and tests deployed to Node
@@ -415,6 +415,6 @@ export class ResearcherAgent extends AgentContext {
 
 ## Reference
 
-- [Guides Documentation](https://docs.agentfront.dev/frontmcp/guides/overview)
+- [Your First Tool](https://docs.agentfront.dev/frontmcp/guides/your-first-tool)
 - Domain routers: `frontmcp-development`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-config`
 - Core skills: `setup-project`, `create-tool`, `create-resource`, `create-provider`, `create-agent`, `configure-auth`, `setup-testing`

package/catalog/frontmcp-guides/examples/example-knowledge-base/agent-and-plugin.md

@@ -0,0 +1,160 @@
+---
+name: agent-and-plugin
+reference: example-knowledge-base
+level: advanced
+description: 'Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.'
+tags: [guides, knowledge-base, knowledge, base, agent, plugin]
+features:
+  - 'Agent with `@Agent` decorator, LLM config, inner tools, and system instructions'
+  - 'Using `this.run(prompt, { maxIterations })` to execute the LLM tool-use loop'
+  - "Configurable behavior via input schema (`depth: 'shallow' | 'deep'`)"
+  - 'Plugin hooks: `onToolExecuteBefore`, `onToolExecuteAfter`, `onToolExecuteError`'
+  - 'Using `ctx.state.set/get()` for flow state instead of mutating `rawInput`'
+  - 'Non-blocking audit logging (`.catch()` prevents audit failures from breaking tools)'
+---
+
+# Knowledge Base: Research Agent and Audit Log Plugin
+
+Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.
+
+## Code
+
+```typescript
+// src/research/agents/researcher.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { SearchDocsTool } from '../../search/tools/search-docs.tool';
+import { IngestDocumentTool } from '../../ingestion/tools/ingest-document.tool';
+
+@Agent({
+  name: 'research_topic',
+  description: 'Research a topic across the knowledge base and synthesize findings into a structured report',
+  inputSchema: {
+    topic: z.string().min(1).describe('Research topic or question'),
+    depth: z.enum(['shallow', 'deep']).default('shallow').describe('Research depth'),
+  },
+  outputSchema: {
+    topic: z.string(),
+    summary: z.string(),
+    sources: z.array(
+      z.object({
+        documentId: z.string(),
+        title: z.string(),
+        relevance: z.string(),
+      }),
+    ),
+    confidence: z.enum(['low', 'medium', 'high']),
+  },
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    apiKey: { env: 'ANTHROPIC_API_KEY' },
+    maxTokens: 4096,
+  },
+  // Inner tools: the agent can call these during its execution
+  tools: [SearchDocsTool, IngestDocumentTool],
+  systemInstructions: `You are a research assistant with access to a knowledge base.
+Your job is to:
+1. Search the knowledge base for relevant documents using the search_docs tool.
+2. Analyze the results and identify key themes.
+3. If depth is "deep", perform multiple searches with refined queries.
+4. Synthesize findings into a structured summary with source attribution.
+Always cite which documents support your findings.`,
+})
+export class ResearcherAgent extends AgentContext {
+  async execute(input: { topic: string; depth: 'shallow' | 'deep' }) {
+    const maxIterations = input.depth === 'deep' ? 5 : 2;
+    const prompt = [
+      `Research the following topic: "${input.topic}"`,
+      `Depth: ${input.depth} (max ${maxIterations} search iterations)`,
+      'Search the knowledge base, analyze results, and produce a structured summary.',
+      'Return your findings as JSON matching the output schema.',
+    ].join('\n');
+
+    // this.run() executes the LLM loop with inner tools
+    return this.run(prompt, { maxIterations });
+  }
+}
+```
+
+```typescript
+// src/plugins/audit-log.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import type { PluginHookContext } from '@frontmcp/sdk';
+
+@Plugin({
+  name: 'AuditLog',
+  description: 'Logs all tool invocations for audit compliance',
+})
+export class AuditLogPlugin {
+  private readonly logs: Array<{
+    timestamp: string;
+    tool: string;
+    userId: string | undefined;
+    duration: number;
+    success: boolean;
+  }> = [];
+
+  async onToolExecuteBefore(ctx: PluginHookContext): Promise<void> {
+    // Store start time in flow state (not in rawInput)
+    ctx.state.set('audit:startTime', Date.now());
+  }
+
+  async onToolExecuteAfter(ctx: PluginHookContext): Promise<void> {
+    const startTime = ctx.state.get('audit:startTime') as number;
+    const duration = Date.now() - startTime;
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      tool: ctx.toolName,
+      userId: ctx.session?.userId,
+      duration,
+      success: true,
+    };
+    this.logs.push(entry);
+
+    // In production, send to an external logging service
+    if (process.env.AUDIT_LOG_ENDPOINT) {
+      await ctx
+        .fetch(process.env.AUDIT_LOG_ENDPOINT, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(entry),
+        })
+        .catch(() => {
+          // Audit logging should not block tool execution
+        });
+    }
+  }
+
+  async onToolExecuteError(ctx: PluginHookContext): Promise<void> {
+    const startTime = ctx.state.get('audit:startTime') as number;
+    const duration = Date.now() - startTime;
+
+    this.logs.push({
+      timestamp: new Date().toISOString(),
+      tool: ctx.toolName,
+      userId: ctx.session?.userId,
+      duration,
+      success: false,
+    });
+  }
+
+  getLogs(): typeof this.logs {
+    return [...this.logs];
+  }
+}
+```
+
+## What This Demonstrates
+
+- Agent with `@Agent` decorator, LLM config, inner tools, and system instructions
+- Using `this.run(prompt, { maxIterations })` to execute the LLM tool-use loop
+- Configurable behavior via input schema (`depth: 'shallow' | 'deep'`)
+- Plugin hooks: `onToolExecuteBefore`, `onToolExecuteAfter`, `onToolExecuteError`
+- Using `ctx.state.set/get()` for flow state instead of mutating `rawInput`
+- Non-blocking audit logging (`.catch()` prevents audit failures from breaking tools)
+
+## Related
+
+- See `example-knowledge-base` for the full knowledge base example with vector store and tests

package/catalog/frontmcp-guides/examples/example-knowledge-base/multi-app-composition.md

@@ -0,0 +1,92 @@
+---
+name: multi-app-composition
+reference: example-knowledge-base
+level: basic
+description: 'Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration.'
+tags: [guides, multi-app, knowledge-base, knowledge, base, multi]
+features:
+  - 'Composing three apps into one server: Ingestion (tools + providers), Search (tools + resources), Research (agents)'
+  - 'Sharing providers across apps (VectorStoreProvider used by both Ingestion and Search)'
+  - 'Registering plugins at the server level (AuditLogPlugin applies to all tools)'
+  - 'Registering agents in a dedicated app for AI-powered features'
+---
+
+# Knowledge Base: Multi-App Composition
+
+Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { IngestionApp } from './ingestion/ingestion.app';
+import { SearchApp } from './search/search.app';
+import { ResearchApp } from './research/research.app';
+import { AuditLogPlugin } from './plugins/audit-log.plugin';
+
+@FrontMcp({
+  info: { name: 'knowledge-base', version: '1.0.0' },
+  apps: [IngestionApp, SearchApp, ResearchApp],
+  plugins: [AuditLogPlugin],
+  auth: { mode: 'remote', provider: 'https://auth.example.com', clientId: 'my-client-id' },
+  redis: { provider: 'redis', host: process.env.REDIS_URL ?? 'localhost' },
+})
+export default class KnowledgeBaseServer {}
+```
+
+```typescript
+// src/ingestion/ingestion.app.ts
+import { App } from '@frontmcp/sdk';
+import { VectorStoreProvider } from './providers/vector-store.provider';
+import { IngestDocumentTool } from './tools/ingest-document.tool';
+
+@App({
+  name: 'Ingestion',
+  description: 'Document ingestion and chunking pipeline',
+  providers: [VectorStoreProvider],
+  tools: [IngestDocumentTool],
+})
+export class IngestionApp {}
+```
+
+```typescript
+// src/search/search.app.ts
+import { App } from '@frontmcp/sdk';
+import { VectorStoreProvider } from '../ingestion/providers/vector-store.provider';
+import { SearchDocsTool } from './tools/search-docs.tool';
+import { DocResource } from './resources/doc.resource';
+
+@App({
+  name: 'Search',
+  description: 'Semantic search and document retrieval',
+  providers: [VectorStoreProvider],
+  tools: [SearchDocsTool],
+  resources: [DocResource],
+})
+export class SearchApp {}
+```
+
+```typescript
+// src/research/research.app.ts
+import { App } from '@frontmcp/sdk';
+import { ResearcherAgent } from './agents/researcher.agent';
+
+@App({
+  name: 'Research',
+  description: 'AI-powered research agent for knowledge synthesis',
+  agents: [ResearcherAgent],
+})
+export class ResearchApp {}
+```
+
+## What This Demonstrates
+
+- Composing three apps into one server: Ingestion (tools + providers), Search (tools + resources), Research (agents)
+- Sharing providers across apps (VectorStoreProvider used by both Ingestion and Search)
+- Registering plugins at the server level (AuditLogPlugin applies to all tools)
+- Registering agents in a dedicated app for AI-powered features
+
+## Related
+
+- See `example-knowledge-base` for the full knowledge base example with vector store, search, and agent code

package/catalog/frontmcp-guides/examples/example-knowledge-base/vector-search-and-resources.md

@@ -0,0 +1,135 @@
+---
+name: vector-search-and-resources
+reference: example-knowledge-base
+level: intermediate
+description: 'Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.'
+tags: [guides, openai, semantic-search, knowledge-base, knowledge, base]
+features:
+  - 'Semantic search tool that generates query embeddings via `this.fetch()` to OpenAI'
+  - 'Using `this.mark()` for execution phase tracing'
+  - "Resource template with `uriTemplate: 'kb://documents/{documentId}'` for parameterized URIs"
+  - 'Typed params via `ResourceContext<{ documentId: string }>` for type-safe URI parameters'
+  - 'Returning `ReadResourceResult` with proper MCP protocol structure'
+---
+
+# Knowledge Base: Semantic Search Tool and Resource Template
+
+Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.
+
+## Code
+
+```typescript
+// src/search/tools/search-docs.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { VECTOR_STORE } from '../../ingestion/providers/vector-store.provider';
+
+@Tool({
+  name: 'search_docs',
+  description: 'Semantic search across the knowledge base',
+  inputSchema: {
+    query: z.string().min(1).describe('Natural language search query'),
+    topK: z.number().int().min(1).max(20).default(5).describe('Number of results'),
+  },
+  outputSchema: {
+    results: z.array(
+      z.object({
+        documentId: z.string(),
+        content: z.string(),
+        score: z.number(),
+        title: z.string(),
+      }),
+    ),
+    total: z.number(),
+  },
+})
+export class SearchDocsTool extends ToolContext {
+  async execute(input: { query: string; topK: number }) {
+    const store = this.get(VECTOR_STORE);
+
+    // Mark execution phases for observability
+    this.mark('embedding-query');
+    const queryEmbedding = await this.generateQueryEmbedding(input.query);
+
+    this.mark('searching');
+    const chunks = await store.search(queryEmbedding, input.topK);
+
+    const results = chunks.map((chunk) => ({
+      documentId: chunk.documentId,
+      content: chunk.content,
+      score: chunk.metadata.score ? parseFloat(chunk.metadata.score) : 0,
+      title: chunk.metadata.title ?? 'Untitled',
+    }));
+
+    return { results, total: results.length };
+  }
+
+  private async generateQueryEmbedding(query: string): Promise<number[]> {
+    const response = await this.fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+      },
+      body: JSON.stringify({ input: query, model: 'text-embedding-3-small' }),
+    });
+    const data = await response.json();
+    return data.data[0].embedding;
+  }
+}
+```
+
+```typescript
+// src/search/resources/doc.resource.ts
+import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
+import type { ReadResourceResult } from '@frontmcp/protocol';
+import { VECTOR_STORE } from '../../ingestion/providers/vector-store.provider';
+
+@ResourceTemplate({
+  name: 'document',
+  uriTemplate: 'kb://documents/{documentId}',
+  description: 'Retrieve all chunks of a document by its ID',
+  mimeType: 'application/json',
+})
+export class DocResource extends ResourceContext<{ documentId: string }> {
+  async execute(uri: string, params: { documentId: string }): Promise<ReadResourceResult> {
+    const store = this.get(VECTOR_STORE);
+    const chunks = await store.getByDocumentId(params.documentId);
+
+    if (chunks.length === 0) {
+      this.fail(new Error(`Document not found: ${params.documentId}`));
+    }
+
+    const document = {
+      documentId: params.documentId,
+      title: chunks[0].metadata.title ?? 'Untitled',
+      chunks: chunks.map((c) => ({
+        chunkIndex: c.metadata.chunkIndex,
+        content: c.content,
+      })),
+    };
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(document, null, 2),
+        },
+      ],
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Semantic search tool that generates query embeddings via `this.fetch()` to OpenAI
+- Using `this.mark()` for execution phase tracing
+- Resource template with `uriTemplate: 'kb://documents/{documentId}'` for parameterized URIs
+- Typed params via `ResourceContext<{ documentId: string }>` for type-safe URI parameters
+- Returning `ReadResourceResult` with proper MCP protocol structure
+
+## Related
+
+- See `example-knowledge-base` for the full knowledge base example with ingestion, agent, and plugin code