@frontmcp/skills 1.0.0-beta.9 → 1.0.0

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

package/catalog/frontmcp-guides/examples/example-task-manager/auth-and-crud-tools.md

@@ -0,0 +1,135 @@
+---
+name: auth-and-crud-tools
+reference: example-task-manager
+level: basic
+description: 'Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection.'
+tags: [guides, auth, session, task-manager, task, manager]
+features:
+  - 'Using `this.context.session?.userId` for per-user data isolation'
+  - 'Using `this.get(TASK_STORE)` for dependency injection of providers'
+  - 'Enforcing authentication with `this.fail()` when no session exists'
+  - 'Optional input fields with `.optional()` for filtering'
+  - '`outputSchema` with nested `z.array(z.object(...))` for structured responses'
+---
+
+# Task Manager: Authenticated CRUD Tools
+
+Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection.
+
+## Code
+
+```typescript
+// src/tools/create-task.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { TASK_STORE } from '../providers/task-store.provider';
+
+@Tool({
+  name: 'create_task',
+  description: 'Create a new task for the authenticated user',
+  inputSchema: {
+    title: z.string().min(1).max(200).describe('Task title'),
+    priority: z.enum(['low', 'medium', 'high']).default('medium').describe('Task priority'),
+  },
+  outputSchema: {
+    id: z.string(),
+    title: z.string(),
+    priority: z.string(),
+    status: z.string(),
+    createdAt: z.string(),
+  },
+})
+export class CreateTaskTool extends ToolContext {
+  async execute(input: { title: string; priority: 'low' | 'medium' | 'high' }) {
+    // Inject the task store via DI
+    const store = this.get(TASK_STORE);
+
+    // Get the authenticated user's ID from the session
+    const userId = this.context.session?.userId;
+    if (!userId) {
+      this.fail(new Error('Authentication required'));
+    }
+
+    const task = await store.create({
+      title: input.title,
+      priority: input.priority,
+      status: 'pending',
+      userId,
+    });
+
+    return {
+      id: task.id,
+      title: task.title,
+      priority: task.priority,
+      status: task.status,
+      createdAt: task.createdAt,
+    };
+  }
+}
+```
+
+```typescript
+// src/tools/list-tasks.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { TASK_STORE } from '../providers/task-store.provider';
+
+@Tool({
+  name: 'list_tasks',
+  description: 'List all tasks for the authenticated user',
+  inputSchema: {
+    status: z.enum(['pending', 'in_progress', 'done']).optional().describe('Filter by status'),
+  },
+  outputSchema: {
+    tasks: z.array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        priority: z.string(),
+        status: z.string(),
+        createdAt: z.string(),
+      }),
+    ),
+    total: z.number(),
+  },
+})
+export class ListTasksTool extends ToolContext {
+  async execute(input: { status?: 'pending' | 'in_progress' | 'done' }) {
+    const store = this.get(TASK_STORE);
+    const userId = this.context.session?.userId;
+
+    if (!userId) {
+      this.fail(new Error('Authentication required'));
+    }
+
+    let tasks = await store.list(userId);
+
+    if (input.status) {
+      tasks = tasks.filter((t) => t.status === input.status);
+    }
+
+    return {
+      tasks: tasks.map((t) => ({
+        id: t.id,
+        title: t.title,
+        priority: t.priority,
+        status: t.status,
+        createdAt: t.createdAt,
+      })),
+      total: tasks.length,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `this.context.session?.userId` for per-user data isolation
+- Using `this.get(TASK_STORE)` for dependency injection of providers
+- Enforcing authentication with `this.fail()` when no session exists
+- Optional input fields with `.optional()` for filtering
+- `outputSchema` with nested `z.array(z.object(...))` for structured responses
+
+## Related
+
+- See `example-task-manager` for the full task manager example with provider, auth, and tests

package/catalog/frontmcp-guides/examples/example-task-manager/authenticated-e2e-tests.md

@@ -0,0 +1,148 @@
+---
+name: authenticated-e2e-tests
+reference: example-task-manager
+level: advanced
+description: 'Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.'
+tags: [guides, auth, session, e2e, unit-test, task-manager]
+features:
+  - 'Using `TestTokenFactory` to create JWT tokens for authenticated E2E tests'
+  - 'Chaining `.withToken(token).buildAndConnect()` for authenticated clients'
+  - 'Unit testing with mocked DI tokens via `this.get()` mock'
+  - 'Mocking session context (`context: { session: { userId } }`) for auth-dependent tools'
+  - 'Testing the unauthenticated error path (no session)'
+---
+
+# Task Manager: Authenticated E2E Tests
+
+Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.
+
+## Code
+
+```typescript
+// test/tasks.e2e.spec.ts
+import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
+
+describe('Task Manager E2E', () => {
+  let client: McpTestClient;
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await TestServer.start({ command: 'npx tsx src/main.ts' });
+
+    // Create a test token for authenticated requests
+    const tokenFactory = new TestTokenFactory();
+    const token = await tokenFactory.createTestToken({ sub: 'user-e2e', scopes: ['tasks'] });
+
+    // Build client with the auth token
+    client = await McpTestClient.create({ baseUrl: server.info.baseUrl }).withToken(token).buildAndConnect();
+  });
+
+  afterAll(async () => {
+    await client.disconnect();
+    await server.stop();
+  });
+
+  it('should list all CRUD tools', async () => {
+    const { tools } = await client.listTools();
+    const names = tools.map((t) => t.name);
+
+    expect(names).toContain('create_task');
+    expect(names).toContain('list_tasks');
+    expect(names).toContain('update_task');
+    expect(names).toContain('delete_task');
+  });
+
+  it('should create and list a task', async () => {
+    const createResult = await client.callTool('create_task', {
+      title: 'E2E test task',
+      priority: 'high',
+    });
+    expect(createResult).toBeSuccessful();
+
+    const listResult = await client.callTool('list_tasks', {});
+    expect(listResult).toBeSuccessful();
+
+    const parsed = JSON.parse(listResult.content[0].text);
+    expect(parsed.tasks.length).toBeGreaterThan(0);
+    expect(parsed.tasks.some((t: { title: string }) => t.title === 'E2E test task')).toBe(true);
+  });
+});
+```
+
+```typescript
+// test/create-task.tool.spec.ts — Unit test with mocked session
+import { ToolContext } from '@frontmcp/sdk';
+import { CreateTaskTool } from '../src/tools/create-task.tool';
+import { TASK_STORE, type TaskStore } from '../src/providers/task-store.provider';
+import type { Task } from '../src/types/task';
+
+describe('CreateTaskTool', () => {
+  let tool: CreateTaskTool;
+  let mockStore: jest.Mocked<TaskStore>;
+
+  beforeEach(() => {
+    tool = new CreateTaskTool();
+    mockStore = {
+      create: jest.fn(),
+      list: jest.fn(),
+      update: jest.fn(),
+      delete: jest.fn(),
+    };
+  });
+
+  function applyContext(userId: string | undefined): void {
+    const ctx = {
+      get: jest.fn((token: symbol) => {
+        if (token === TASK_STORE) return mockStore;
+        throw new Error(`Unknown token: ${String(token)}`);
+      }),
+      tryGet: jest.fn(),
+      fail: jest.fn((err: Error) => {
+        throw err;
+      }),
+      mark: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+      context: { session: userId ? { userId } : undefined },
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+  }
+
+  it('should create a task for an authenticated user', async () => {
+    const mockTask: Task = {
+      id: 'task-001',
+      title: 'Write tests',
+      priority: 'high',
+      status: 'pending',
+      userId: 'user-123',
+      createdAt: '2026-03-27T10:00:00.000Z',
+    };
+    mockStore.create.mockResolvedValue(mockTask);
+    applyContext('user-123');
+
+    const result = await tool.execute({ title: 'Write tests', priority: 'high' });
+
+    expect(result.id).toBe('task-001');
+    expect(result.title).toBe('Write tests');
+    expect(mockStore.create).toHaveBeenCalledWith(expect.objectContaining({ userId: 'user-123', status: 'pending' }));
+  });
+
+  it('should fail when user is not authenticated', async () => {
+    applyContext(undefined);
+
+    await expect(tool.execute({ title: 'Write tests', priority: 'medium' })).rejects.toThrow('Authentication required');
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using `TestTokenFactory` to create JWT tokens for authenticated E2E tests
+- Chaining `.withToken(token).buildAndConnect()` for authenticated clients
+- Unit testing with mocked DI tokens via `this.get()` mock
+- Mocking session context (`context: { session: { userId } }`) for auth-dependent tools
+- Testing the unauthenticated error path (no session)
+
+## Related
+
+- See `example-task-manager` for the full task manager example with server setup and Vercel deployment

package/catalog/frontmcp-guides/examples/example-task-manager/redis-provider-with-di.md

@@ -0,0 +1,129 @@
+---
+name: redis-provider-with-di
+reference: example-task-manager
+level: intermediate
+description: 'Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.'
+tags: [guides, redis, node, task-manager, task, manager]
+features:
+  - "Defining an interface and DI token (`Symbol('TaskStore')`) for the provider"
+  - 'Using `@Provider({ token: TASK_STORE })` to register the provider for DI'
+  - 'Lifecycle hooks: `onInit()` for connection setup, `onDestroy()` for cleanup'
+  - 'Lazy-loading `ioredis` via dynamic `import()` in `onInit()`'
+  - 'Using `@frontmcp/utils` for `randomUUID()` instead of `node:crypto`'
+  - 'Per-user data isolation using Redis hash keys (`tasks:${userId}`)'
+---
+
+# Task Manager: Redis Provider with Dependency Injection
+
+Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.
+
+## Code
+
+```typescript
+// src/types/task.ts
+export interface Task {
+  id: string;
+  title: string;
+  priority: 'low' | 'medium' | 'high';
+  status: 'pending' | 'in_progress' | 'done';
+  userId: string;
+  createdAt: string;
+}
+```
+
+```typescript
+// src/providers/task-store.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import type { Token } from '@frontmcp/di';
+import type { Task } from '../types/task';
+
+export interface TaskStore {
+  create(task: Omit<Task, 'id' | 'createdAt'>): Promise<Task>;
+  list(userId: string): Promise<Task[]>;
+  update(id: string, userId: string, data: Partial<Pick<Task, 'title' | 'priority' | 'status'>>): Promise<Task>;
+  delete(id: string, userId: string): Promise<void>;
+}
+
+// DI token — tools use this.get(TASK_STORE) to access the provider
+export const TASK_STORE: Token<TaskStore> = Symbol('TaskStore');
+
+@Provider({ token: TASK_STORE })
+export class RedisTaskStoreProvider implements TaskStore {
+  private redis!: import('ioredis').default;
+
+  // Lifecycle: initialize Redis connection
+  async onInit(): Promise<void> {
+    const Redis = (await import('ioredis')).default;
+    this.redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379');
+  }
+
+  async create(input: Omit<Task, 'id' | 'createdAt'>): Promise<Task> {
+    const { randomUUID } = await import('@frontmcp/utils');
+    const task: Task = {
+      ...input,
+      id: randomUUID(),
+      createdAt: new Date().toISOString(),
+    };
+    await this.redis.hset(`tasks:${task.userId}`, task.id, JSON.stringify(task));
+    return task;
+  }
+
+  async list(userId: string): Promise<Task[]> {
+    const entries = await this.redis.hgetall(`tasks:${userId}`);
+    return Object.values(entries).map((v) => JSON.parse(v) as Task);
+  }
+
+  async update(id: string, userId: string, data: Partial<Pick<Task, 'title' | 'priority' | 'status'>>): Promise<Task> {
+    const raw = await this.redis.hget(`tasks:${userId}`, id);
+    if (!raw) {
+      throw new Error(`Task not found: ${id}`);
+    }
+    const task: Task = { ...(JSON.parse(raw) as Task), ...data };
+    await this.redis.hset(`tasks:${userId}`, id, JSON.stringify(task));
+    return task;
+  }
+
+  async delete(id: string, userId: string): Promise<void> {
+    const removed = await this.redis.hdel(`tasks:${userId}`, id);
+    if (removed === 0) {
+      throw new Error(`Task not found: ${id}`);
+    }
+  }
+
+  // Lifecycle: close Redis connection on shutdown
+  async onDestroy(): Promise<void> {
+    await this.redis.quit();
+  }
+}
+```
+
+```typescript
+// src/tasks.app.ts
+import { App } from '@frontmcp/sdk';
+import { RedisTaskStoreProvider } from './providers/task-store.provider';
+import { CreateTaskTool } from './tools/create-task.tool';
+import { ListTasksTool } from './tools/list-tasks.tool';
+import { UpdateTaskTool } from './tools/update-task.tool';
+import { DeleteTaskTool } from './tools/delete-task.tool';
+
+@App({
+  name: 'Tasks',
+  description: 'Task management with CRUD operations',
+  providers: [RedisTaskStoreProvider],
+  tools: [CreateTaskTool, ListTasksTool, UpdateTaskTool, DeleteTaskTool],
+})
+export class TasksApp {}
+```
+
+## What This Demonstrates
+
+- Defining an interface and DI token (`Symbol('TaskStore')`) for the provider
+- Using `@Provider({ token: TASK_STORE })` to register the provider for DI
+- Lifecycle hooks: `onInit()` for connection setup, `onDestroy()` for cleanup
+- Lazy-loading `ioredis` via dynamic `import()` in `onInit()`
+- Using `@frontmcp/utils` for `randomUUID()` instead of `node:crypto`
+- Per-user data isolation using Redis hash keys (`tasks:${userId}`)
+
+## Related
+
+- See `example-task-manager` for the full task manager example with auth and E2E tests

package/catalog/frontmcp-guides/examples/example-weather-api/server-and-app-setup.md

@@ -0,0 +1,75 @@
+---
+name: server-and-app-setup
+reference: example-weather-api
+level: basic
+description: 'Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.'
+tags: [guides, weather, api, app, setup]
+features:
+  - 'Server entry point with `@FrontMcp` decorator and `info` configuration'
+  - 'App registration with `@App` grouping tools and resources together'
+  - 'Static resource that returns JSON data via `read()`'
+  - 'Clean separation between server, app, tools, and resources'
+---
+
+# Weather API: Server and App Setup
+
+Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { WeatherApp } from './weather.app';
+
+@FrontMcp({
+  info: { name: 'weather-api', version: '1.0.0' },
+  apps: [WeatherApp],
+})
+export default class WeatherServer {}
+```
+
+```typescript
+// src/weather.app.ts
+import { App } from '@frontmcp/sdk';
+import { GetWeatherTool } from './tools/get-weather.tool';
+import { CitiesResource } from './resources/cities.resource';
+
+@App({
+  name: 'Weather',
+  description: 'Weather lookup tools and city data',
+  tools: [GetWeatherTool],
+  resources: [CitiesResource],
+})
+export class WeatherApp {}
+```
+
+```typescript
+// src/resources/cities.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+const SUPPORTED_CITIES = ['London', 'Tokyo', 'New York', 'Paris', 'Sydney', 'Berlin', 'Toronto', 'Mumbai'];
+
+@Resource({
+  uri: 'weather://cities',
+  name: 'Supported Cities',
+  description: 'List of cities with available weather data',
+  mimeType: 'application/json',
+})
+export class CitiesResource extends ResourceContext {
+  async read() {
+    return JSON.stringify(SUPPORTED_CITIES);
+  }
+}
+```
+
+## What This Demonstrates
+
+- Server entry point with `@FrontMcp` decorator and `info` configuration
+- App registration with `@App` grouping tools and resources together
+- Static resource that returns JSON data via `read()`
+- Clean separation between server, app, tools, and resources
+
+## Related
+
+- See `example-weather-api` for the full end-to-end weather API example