@frontmcp/skills 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,299 @@
+---
+name: vectoriadb
+description: Use VectoriaDB for in-memory vector search with ML-based or TF-IDF engines in FrontMCP servers
+---
+
+# VectoriaDB Integration
+
+Use VectoriaDB for in-memory vector search in FrontMCP servers. Two engines are available:
+
+- **VectoriaDB** — ML-based semantic search using transformer models. Best for understanding meaning ("find users" matches "list accounts").
+- **TFIDFVectoria** — Zero-dependency keyword search using TF-IDF scoring. Best for exact/fuzzy keyword matching with no model downloads.
+
+Both are included in the `vectoriadb` package (already a FrontMCP dependency).
+
+## When to Use
+
+| Engine          | Use When                                                          | Dependencies    | Init                                 |
+| --------------- | ----------------------------------------------------------------- | --------------- | ------------------------------------ |
+| `TFIDFVectoria` | Keyword matching, zero deps, no network, small corpus (<10K docs) | None            | Synchronous                          |
+| `VectoriaDB`    | Semantic understanding, similarity matching, large corpus         | transformers.js | Async (downloads model on first run) |
+
+## TFIDFVectoria — Lightweight Keyword Search
+
+Zero dependencies, synchronous initialization. Good for tool discovery, FAQ matching, and simple search features.
+
+### Basic Usage
+
+```typescript
+import { TFIDFVectoria } from 'vectoriadb';
+
+const db = new TFIDFVectoria({
+  defaultSimilarityThreshold: 0.0,
+  defaultTopK: 10,
+});
+
+// Add documents (id, text)
+db.addDocument('users-list', 'List all users with pagination and filtering');
+db.addDocument('users-create', 'Create a new user account with email and password');
+db.addDocument('orders-list', 'List orders for a customer with date range filters');
+
+// Build the index (required after adding documents)
+db.buildIndex();
+
+// Search
+const results = db.search('find users', 5);
+// results: [{ id: 'users-list', score: 0.82 }, { id: 'users-create', score: 0.65 }]
+```
+
+### With Field Weights
+
+Weight different fields to control scoring influence:
+
+```typescript
+const db = new TFIDFVectoria({
+  fields: {
+    name: { weight: 3 }, // Name matches are 3x more important
+    description: { weight: 2 }, // Description matches are 2x
+    tags: { weight: 1 }, // Tags are baseline
+  },
+});
+
+db.addDocument('weather-tool', {
+  name: 'get_weather',
+  description: 'Fetch current weather conditions for a city',
+  tags: 'weather forecast temperature',
+});
+
+db.buildIndex();
+const results = db.search('temperature forecast', 5);
+```
+
+### FrontMCP Provider Pattern
+
+```typescript
+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 },
+      answer: { weight: 1 },
+      tags: { weight: 2 },
+    },
+  });
+
+  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,
+      });
+    }
+    this.db.buildIndex();
+  }
+
+  search(query: string, limit = 5) {
+    return this.db.search(query, limit);
+  }
+}
+```
+
+## VectoriaDB — Semantic ML Search
+
+Uses transformer models for true semantic understanding. "find users" matches "list accounts" even without shared keywords.
+
+### Basic Usage
+
+```typescript
+import { VectoriaDB, DocumentMetadata } from 'vectoriadb';
+
+interface ProductDoc extends DocumentMetadata {
+  name: string;
+  category: string;
+  price: number;
+}
+
+const db = new VectoriaDB<ProductDoc>({
+  modelName: 'Xenova/all-MiniLM-L6-v2', // Default model
+  cacheDir: './.cache/transformers', // Model cache
+  defaultSimilarityThreshold: 0.4,
+  defaultTopK: 10,
+  useHNSW: true, // Enable HNSW for fast search on large datasets
+});
+
+// Must initialize before use (downloads model on first run)
+await db.initialize();
+
+// Add documents
+await db.add('prod-1', 'Wireless noise-canceling headphones with 30h battery', {
+  id: 'prod-1',
+  name: 'QuietComfort Ultra',
+  category: 'audio',
+  price: 349,
+});
+
+// Semantic search — understands meaning, not just keywords
+const results = await db.search('something to block office noise', {
+  topK: 5,
+  threshold: 0.4,
+});
+// results[0].metadata.name === 'QuietComfort Ultra' (semantic match!)
+```
+
+### Batch Operations
+
+```typescript
+await db.addMany([
+  {
+    id: 'doc-1',
+    text: 'First document content',
+    metadata: {
+      /* ... */
+    },
+  },
+  {
+    id: 'doc-2',
+    text: 'Second document content',
+    metadata: {
+      /* ... */
+    },
+  },
+]);
+```
+
+### Filtered Search
+
+```typescript
+const results = await db.search('wireless audio', {
+  topK: 5,
+  filter: (meta) => meta.category === 'audio' && meta.price < 300,
+});
+```
+
+### Persistence with Storage Adapters
+
+```typescript
+import { VectoriaDB, FileStorageAdapter } from 'vectoriadb';
+
+const db = new VectoriaDB<MyDoc>({
+  storageAdapter: new FileStorageAdapter({ cacheDir: './.cache/vectors' }),
+});
+
+await db.initialize();
+// After adding documents, persist to disk
+await db.saveToStorage();
+// On next startup, restores without re-embedding
+await db.loadFromStorage();
+```
+
+### FrontMCP Provider Pattern
+
+```typescript
+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>({
+      useHNSW: true,
+      storageAdapter: new FileStorageAdapter({ cacheDir: './.cache/kb-vectors' }),
+    });
+    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,
+      filter: options?.category ? (m) => m.category === options.category : undefined,
+    });
+  }
+
+  async index(id: string, text: string, metadata: Article) {
+    await this.ready;
+    if (this.db.has(id)) {
+      await this.db.update(id, { text, metadata });
+    } else {
+      await this.db.add(id, text, metadata);
+    }
+    await this.db.saveToStorage();
+  }
+}
+```
+
+## Configuration Reference
+
+### VectoriaDB Options
+
+| Option                       | Type           | Default                     | Description                              |
+| ---------------------------- | -------------- | --------------------------- | ---------------------------------------- |
+| `modelName`                  | string         | `'Xenova/all-MiniLM-L6-v2'` | Transformer model for embeddings         |
+| `cacheDir`                   | string         | `'./.cache/transformers'`   | Model download cache directory           |
+| `defaultSimilarityThreshold` | number         | `0.3`                       | Minimum similarity score (0-1)           |
+| `defaultTopK`                | number         | `10`                        | Default results limit                    |
+| `useHNSW`                    | boolean        | `false`                     | Enable HNSW index for O(log n) search    |
+| `maxDocuments`               | number         | `100000`                    | Max documents (DoS protection)           |
+| `storageAdapter`             | StorageAdapter | None                        | Persistence adapter (FileStorageAdapter) |
+
+### TFIDFVectoria Options
+
+| Option                       | Type                       | Default | Description              |
+| ---------------------------- | -------------------------- | ------- | ------------------------ |
+| `defaultSimilarityThreshold` | number                     | `0.0`   | Minimum similarity score |
+| `defaultTopK`                | number                     | `10`    | Default results limit    |
+| `fields`                     | Record<string, { weight }> | None    | Field-weighted indexing  |
+
+## Choosing Between Engines
+
+| Criterion          | TFIDFVectoria                  | VectoriaDB                                |
+| ------------------ | ------------------------------ | ----------------------------------------- |
+| **Dependencies**   | Zero                           | transformers.js (~50MB model)             |
+| **Initialization** | Synchronous, instant           | Async, first-run model download           |
+| **Search quality** | Keyword-based (exact/fuzzy)    | Semantic (understands meaning)            |
+| **Best for**       | Tool discovery, FAQ, <10K docs | Knowledge base, recommendations, any size |
+| **Reindex needed** | Yes (`buildIndex()` after add) | No (auto-indexed on add)                  |
+| **Persistence**    | Not built-in                   | FileStorageAdapter                        |
+
+## Verification Checklist
+
+- [ ] Correct engine chosen based on requirements (TFIDFVectoria vs VectoriaDB)
+- [ ] Provider wraps the database with proper initialization
+- [ ] `buildIndex()` called after adding documents (TFIDFVectoria only)
+- [ ] `await db.initialize()` called before any operations (VectoriaDB only)
+- [ ] Field weights configured based on domain relevance
+- [ ] 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)
+- [TFIDFVectoria API](https://docs.agentfront.dev/vectoriadb/api-reference/tfidf-vectoria/constructor)
+- Related skills: `create-provider`, `create-tool`, `frontmcp-development`

package/catalog/frontmcp-guides/SKILL.md

@@ -1,12 +1,15 @@
 ---
 name: frontmcp-guides
-description: 'End-to-end examples and best practices for building FrontMCP MCP servers. Use when starting a new project from scratch, learning architectural patterns, or following a complete build walkthrough.'
+description: 'Tutorials, walkthroughs, and end-to-end examples for building FrontMCP servers. Use when you want a getting started guide, how to build a complete project, learn best practices, or follow a step-by-step example. Triggers: tutorial, walkthrough, how to build, getting started, learn FrontMCP.'
 tags: [guides, examples, best-practices, architecture, walkthrough, end-to-end]
+category: guides
+targets: [all]
+bundle: [recommended, full]
 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
@@ -44,7 +47,7 @@ Complete build walkthroughs and best practices for FrontMCP servers. Each exampl
 
 ## Prerequisites
 
-- Node.js 22+ and npm/yarn installed
+- Node.js 24+ and npm/yarn installed
 - Familiarity with TypeScript and decorators
 - `frontmcp` CLI available globally (`npm install -g frontmcp`)
 
@@ -412,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