@frontmcp/skills 0.0.1

package/catalog/development/create-tool/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: create-tool
+description: Create and register an MCP tool with Zod input validation and typed output. Use when building tools, defining input schemas, adding output validation, or registering tools in an app.
+tags: [tools, mcp, zod, schema, decorator]
+tools:
+  - name: create_tool
+    purpose: Scaffold a new tool class
+parameters:
+  - name: name
+    description: Tool name in snake_case
+    type: string
+    required: true
+examples:
+  - scenario: Create a calculator tool with add operation
+    expected-outcome: Tool registered and callable via MCP
+  - scenario: Create a tool with DI and error handling
+    expected-outcome: Tool using providers and proper error classes
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/servers/tools
+---
+
+# Creating an MCP Tool
+
+Tools are the primary way to expose executable actions to AI clients in the MCP protocol. In FrontMCP, tools are TypeScript classes that extend `ToolContext`, decorated with `@Tool`, and registered on a `@FrontMcp` server or inside an `@App`.
+
+## When to Use @Tool
+
+Use `@Tool` when you need to expose an action that an AI client can invoke. Tools accept validated input, perform work (database queries, API calls, computations), and return structured results. Every tool goes through Zod-based input validation before `execute()` runs.
+
+## Class-Based Pattern
+
+Create a class extending `ToolContext<In, Out>` and implement the `execute(input: In): Promise<Out>` method. The `@Tool` decorator requires at minimum a `name` and an `inputSchema`.
+
+```typescript
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'greet_user',
+  description: 'Greet a user by name',
+  inputSchema: {
+    name: z.string().describe('The name of the user to greet'),
+  },
+})
+class GreetUserTool extends ToolContext {
+  async execute(input: { name: string }) {
+    return `Hello, ${input.name}!`;
+  }
+}
+```
+
+### Available Context Methods and Properties
+
+`ToolContext` extends `ExecutionContextBase`, which provides:
+
+**Methods:**
+
+- `execute(input: In): Promise<Out>` -- the main method you implement
+- `this.get(token)` -- resolve a dependency from DI (throws if not found)
+- `this.tryGet(token)` -- resolve a dependency from DI (returns `undefined` if not found)
+- `this.fail(err)` -- abort execution, triggers error flow (never returns)
+- `this.mark(stage)` -- set the active execution stage for debugging/tracking
+- `this.fetch(input, init?)` -- HTTP fetch with context propagation
+- `this.notify(message, level?)` -- send a log-level notification to the client
+- `this.respondProgress(value, total?)` -- send a progress notification to the client
+
+**Properties:**
+
+- `this.input` -- the validated input object
+- `this.output` -- the output (available after execute)
+- `this.metadata` -- tool metadata from the decorator
+- `this.scope` -- the current scope instance
+- `this.context` -- the execution context
+
+## Input Schema: Zod Raw Shapes
+
+The `inputSchema` accepts a **Zod raw shape** -- a plain object mapping field names to Zod types. Do NOT wrap it in `z.object()`. The framework wraps it internally.
+
+```typescript
+@Tool({
+  name: 'search_documents',
+  description: 'Search documents by query and optional filters',
+  inputSchema: {
+    // This is a raw shape, NOT z.object({...})
+    query: z.string().min(1).describe('Search query'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results'),
+    category: z.enum(['blog', 'docs', 'api']).optional().describe('Filter by category'),
+  },
+})
+class SearchDocumentsTool extends ToolContext {
+  async execute(input: { query: string; limit: number; category?: 'blog' | 'docs' | 'api' }) {
+    // input is already validated by Zod before execute() is called
+    return { results: [], total: 0 };
+  }
+}
+```
+
+The `execute()` parameter type must match the inferred output of `z.object(inputSchema)`. Validated input is also available via `this.input`.
+
+## Output Schema (Recommended Best Practice)
+
+**Always define `outputSchema` for every tool.** This is a best practice for three critical reasons:
+
+1. **Output validation** -- Prevents data leaks by ensuring your tool only returns fields you explicitly declare. Without `outputSchema`, any data in the return value passes through unvalidated, risking accidental exposure of sensitive fields (internal IDs, tokens, PII).
+2. **CodeCall plugin compatibility** -- The CodeCall plugin uses `outputSchema` to understand what a tool returns, enabling correct VM-based orchestration and pass-by-reference. Tools without `outputSchema` degrade CodeCall's ability to chain results.
+3. **Type safety** -- The `Out` generic on `ToolContext<In, Out>` is inferred from `outputSchema`, giving you compile-time guarantees that `execute()` returns the correct shape.
+
+```typescript
+@Tool({
+  name: 'get_weather',
+  description: 'Get current weather for a location',
+  inputSchema: {
+    city: z.string().describe('City name'),
+  },
+  // Always define outputSchema to validate output and prevent data leaks
+  outputSchema: {
+    temperature: z.number(),
+    unit: z.enum(['celsius', 'fahrenheit']),
+    description: z.string(),
+  },
+})
+class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string }): Promise<{
+    temperature: number;
+    unit: 'celsius' | 'fahrenheit';
+    description: string;
+  }> {
+    const response = await this.fetch(`https://api.weather.example.com/v1/current?city=${input.city}`);
+    const weather = await response.json();
+    // Only temperature, unit, and description are returned.
+    // Any extra fields from the API (e.g., internalId, apiKey) are stripped by outputSchema validation.
+    return {
+      temperature: weather.temp,
+      unit: 'celsius',
+      description: weather.summary,
+    };
+  }
+}
+```
+
+**Why not omit outputSchema?** Without it:
+
+- The tool returns raw unvalidated data — any field your code accidentally includes leaks to the client
+- CodeCall cannot infer return types for chaining tool calls in VM scripts
+- No compile-time type checking on the return value
+
+Supported `outputSchema` types:
+
+- **Zod raw shapes** (recommended): `{ field: z.string(), count: z.number() }` — structured JSON output with validation
+- **Zod schemas**: `z.object(...)`, `z.array(...)`, `z.union([...])` — for complex types
+- **Primitive literals**: `'string'`, `'number'`, `'boolean'`, `'date'` — for simple returns
+- **Media types**: `'image'`, `'audio'`, `'resource'`, `'resource_link'` — for binary/link content
+- **Arrays**: `['string', 'image']` for multi-content responses
+
+## Dependency Injection
+
+Access providers registered in the scope using `this.get(token)` (throws if not found) or `this.tryGet(token)` (returns `undefined` if not found).
+
+```typescript
+import type { Token } from '@frontmcp/di';
+
+interface DatabaseService {
+  query(sql: string, params: unknown[]): Promise<unknown[]>;
+}
+const DATABASE: Token<DatabaseService> = Symbol('database');
+
+@Tool({
+  name: 'run_query',
+  description: 'Execute a database query',
+  inputSchema: {
+    sql: z.string().describe('SQL query to execute'),
+  },
+})
+class RunQueryTool extends ToolContext {
+  async execute(input: { sql: string }) {
+    const db = this.get(DATABASE); // throws if DATABASE not registered
+    const rows = await db.query(input.sql, []);
+    return { rows, count: rows.length };
+  }
+}
+```
+
+Use `this.tryGet(token)` when the dependency is optional:
+
+```typescript
+async execute(input: { data: string }) {
+  const cache = this.tryGet(CACHE); // returns undefined if not registered
+  if (cache) {
+    const cached = await cache.get(input.data);
+    if (cached) return cached;
+  }
+  // proceed without cache
+}
+```
+
+## Error Handling
+
+Use `this.fail(err)` to abort execution and trigger the error flow. The method throws internally and never returns.
+
+```typescript
+@Tool({
+  name: 'delete_record',
+  description: 'Delete a record by ID',
+  inputSchema: {
+    id: z.string().uuid().describe('Record UUID'),
+  },
+})
+class DeleteRecordTool extends ToolContext {
+  async execute(input: { id: string }) {
+    const record = await this.findRecord(input.id);
+    if (!record) {
+      this.fail(new Error(`Record not found: ${input.id}`));
+    }
+
+    await this.deleteRecord(record);
+    return `Record ${input.id} deleted successfully`;
+  }
+
+  private async findRecord(id: string) {
+    return null;
+  }
+
+  private async deleteRecord(record: unknown) {
+    // delete implementation
+  }
+}
+```
+
+For MCP-specific errors, use error classes with JSON-RPC codes:
+
+```typescript
+import { ResourceNotFoundError, PublicMcpError, MCP_ERROR_CODES } from '@frontmcp/sdk';
+
+this.fail(new ResourceNotFoundError(`Record ${input.id}`));
+```
+
+## Progress and Notifications
+
+Use `this.notify(message, level?)` to send log-level notifications and `this.respondProgress(value, total?)` to send progress updates to the client.
+
+```typescript
+@Tool({
+  name: 'batch_process',
+  description: 'Process a batch of items',
+  inputSchema: {
+    items: z.array(z.string()).min(1).describe('Items to process'),
+  },
+})
+class BatchProcessTool extends ToolContext {
+  async execute(input: { items: string[] }) {
+    this.mark('validation');
+    this.validateItems(input.items);
+
+    this.mark('processing');
+    const results: string[] = [];
+    for (let i = 0; i < input.items.length; i++) {
+      await this.respondProgress(i + 1, input.items.length);
+      const result = await this.processItem(input.items[i]);
+      results.push(result);
+    }
+
+    this.mark('complete');
+    await this.notify(`Processed ${results.length} items`, 'info');
+    return { processed: results.length, results };
+  }
+
+  private validateItems(items: string[]) {
+    /* ... */
+  }
+  private async processItem(item: string): Promise<string> {
+    return item;
+  }
+}
+```
+
+## Tool Annotations
+
+Provide behavioral hints to clients using `annotations`. These hints help clients decide how to present and gate tool usage.
+
+```typescript
+@Tool({
+  name: 'web_search',
+  description: 'Search the web',
+  inputSchema: {
+    query: z.string(),
+  },
+  annotations: {
+    title: 'Web Search',
+    readOnlyHint: true,
+    openWorldHint: true,
+  },
+})
+class WebSearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return await this.performSearch(input.query);
+  }
+
+  private async performSearch(query: string) {
+    return [];
+  }
+}
+```
+
+Annotation fields:
+
+- `title` -- Human-readable title for the tool
+- `readOnlyHint` -- Tool does not modify its environment (default: false)
+- `destructiveHint` -- Tool may perform destructive updates (default: true, meaningful only when readOnlyHint is false)
+- `idempotentHint` -- Calling repeatedly with same args has no additional effect (default: false)
+- `openWorldHint` -- Tool interacts with external entities (default: true)
+
+## Function-Style Builder
+
+For simple tools that do not need a class, use the `tool()` function builder. It returns a value you register the same way as a class tool.
+
+```typescript
+import { tool } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const AddNumbers = tool({
+  name: 'add_numbers',
+  description: 'Add two numbers',
+  inputSchema: {
+    a: z.number().describe('First number'),
+    b: z.number().describe('Second number'),
+  },
+  outputSchema: 'number',
+})((input) => {
+  return input.a + input.b;
+});
+```
+
+The callback receives `(input, ctx)` where `ctx` provides access to the same context methods (`get`, `tryGet`, `fail`, `mark`, `fetch`, `notify`, `respondProgress`).
+
+Register it the same way as a class tool: `tools: [AddNumbers]`.
+
+## Remote and ESM Loading
+
+Load tools from external modules or remote URLs without importing them directly.
+
+**ESM loading** -- load a tool from an ES module:
+
+```typescript
+const RemoteTool = Tool.esm('@my-org/tools@^1.0.0', 'MyTool', {
+  description: 'A tool loaded from an ES module',
+});
+```
+
+**Remote loading** -- load a tool from a remote URL:
+
+```typescript
+const CloudTool = Tool.remote('https://example.com/tools/cloud-tool', 'CloudTool', {
+  description: 'A tool loaded from a remote server',
+});
+```
+
+Both return values that can be registered in `tools: [RemoteTool, CloudTool]`.
+
+## Registration
+
+Add tool classes (or function-style tools) to the `tools` array in `@FrontMcp` or `@App`.
+
+```typescript
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'my-app',
+  tools: [GreetUserTool, SearchDocumentsTool, AddNumbers],
+})
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  tools: [RunQueryTool], // can also register tools directly on the server
+})
+class MyServer {}
+```
+
+## Nx Generator
+
+Scaffold a new tool using the Nx generator:
+
+```bash
+nx generate @frontmcp/nx:tool
+```
+
+This creates the tool file, spec file, and updates barrel exports.
+
+## Rate Limiting and Concurrency
+
+Protect tools with throttling controls:
+
+```typescript
+@Tool({
+  name: 'expensive_operation',
+  description: 'An expensive operation that should be rate limited',
+  inputSchema: {
+    data: z.string(),
+  },
+  rateLimit: { maxRequests: 10, windowMs: 60_000 },
+  concurrency: { maxConcurrent: 2 },
+  timeout: { executeMs: 30_000 },
+})
+class ExpensiveOperationTool extends ToolContext {
+  async execute(input: { data: string }) {
+    // At most 10 calls per minute, 2 concurrent, 30s timeout
+    return await this.heavyComputation(input.data);
+  }
+
+  private async heavyComputation(data: string) {
+    return data;
+  }
+}
+```

package/catalog/development/create-tool/references/output-schema-types.md

@@ -0,0 +1,56 @@
+# Output Schema Types Reference
+
+All supported `outputSchema` types for `@Tool`:
+
+## Zod Raw Shapes (Recommended)
+
+```typescript
+outputSchema: {
+  name: z.string(),
+  count: z.number(),
+  items: z.array(z.string()),
+}
+```
+
+Produces structured JSON output. **Best practice for CodeCall compatibility and data leak prevention.**
+
+## Zod Schemas
+
+```typescript
+outputSchema: z.object({ result: z.number() })
+outputSchema: z.array(z.string())
+outputSchema: z.union([z.string(), z.number()])
+outputSchema: z.discriminatedUnion('type', [...])
+```
+
+## Primitive Literals
+
+```typescript
+outputSchema: 'string'; // Returns plain text
+outputSchema: 'number'; // Returns a number
+outputSchema: 'boolean'; // Returns true/false
+outputSchema: 'date'; // Returns an ISO date string
+```
+
+## Media Types
+
+```typescript
+outputSchema: 'image'; // Returns base64 image data
+outputSchema: 'audio'; // Returns base64 audio data
+outputSchema: 'resource'; // Returns a resource content
+outputSchema: 'resource_link'; // Returns a resource URI link
+```
+
+## Multi-Content Arrays
+
+```typescript
+outputSchema: ['string', 'image']; // Returns text + image content
+```
+
+## No OutputSchema (Not Recommended)
+
+When `outputSchema` is omitted, the tool returns unvalidated content. This:
+
+- Risks leaking internal fields to the client
+- Prevents CodeCall from inferring return types
+- Loses compile-time type checking on `Out` generic

package/catalog/development/create-tool/references/tool-annotations.md

@@ -0,0 +1,34 @@
+# Tool Annotations Reference
+
+Annotations provide hints to MCP clients about tool behavior:
+
+```typescript
+@Tool({
+  name: 'my_tool',
+  inputSchema: { ... },
+  annotations: {
+    title: 'My Tool',              // Human-readable display name
+    readOnlyHint: true,            // Tool only reads data, no side effects
+    destructiveHint: false,        // Tool does NOT destroy/delete data
+    idempotentHint: true,          // Safe to call multiple times with same input
+    openWorldHint: false,          // Tool does NOT interact with external world
+  },
+})
+```
+
+## Fields
+
+| Field             | Type      | Default | Description                        |
+| ----------------- | --------- | ------- | ---------------------------------- |
+| `title`           | `string`  | —       | Human-friendly display name        |
+| `readOnlyHint`    | `boolean` | `false` | Tool only reads, no mutations      |
+| `destructiveHint` | `boolean` | `true`  | Tool may delete/overwrite data     |
+| `idempotentHint`  | `boolean` | `false` | Repeated calls produce same result |
+| `openWorldHint`   | `boolean` | `true`  | Tool may access external services  |
+
+## Usage Guidance
+
+- Set `readOnlyHint: true` for query/lookup tools
+- Set `destructiveHint: true` for delete/overwrite operations (triggers client warnings)
+- Set `idempotentHint: true` for safe-to-retry tools
+- Set `openWorldHint: false` for tools that only access local data