@frontmcp/skills 1.0.3 → 1.1.0-beta.1

package/catalog/frontmcp-development/examples/decorators-guide/multi-app-with-plugins-and-providers.md

@@ -47,8 +47,7 @@ class AuditPlugin {}
 
 ```typescript
 // src/tools/query.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'run_query',
@@ -68,8 +67,7 @@ class QueryTool extends ToolContext {
 
 ```typescript
 // src/tools/report.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'generate_report',
@@ -90,7 +88,7 @@ class ReportTool extends ToolContext {
 
 ```typescript
 // src/resources/dashboard.resource.ts
-import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
+import { ResourceContext, ResourceTemplate } from '@frontmcp/sdk';
 
 @ResourceTemplate({
   name: 'dashboard',
@@ -109,7 +107,7 @@ class DashboardResource extends ResourceContext {
 
 ```typescript
 // src/server.ts
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'analytics',

package/catalog/frontmcp-development/examples/official-plugins/cache-and-feature-flags.md

@@ -21,9 +21,9 @@ Demonstrates combining the Cache plugin for tool result caching with the Feature
 
 ```typescript
 // src/server.ts
-import { FrontMcp, App } from '@frontmcp/sdk';
 import CachePlugin from '@frontmcp/plugin-cache';
 import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'api',
@@ -55,8 +55,7 @@ class MyServer {}
 
 ```typescript
 // src/tools/get-weather.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 // Per-tool cache metadata with custom TTL and sliding window
 @Tool({
@@ -80,8 +79,7 @@ class GetWeatherTool extends ToolContext {
 
 ```typescript
 // src/tools/beta-search.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 // Tool gated behind a feature flag -- hidden from list_tools when flag is off
 @Tool({

package/catalog/frontmcp-development/examples/official-plugins/production-multi-plugin-setup.md

@@ -24,12 +24,12 @@ Demonstrates a production-ready server configuration combining CodeCall, Remembe
 
 ```typescript
 // src/server.ts
-import { FrontMcp, App } from '@frontmcp/sdk';
-import CodeCallPlugin from '@frontmcp/plugin-codecall';
-import RememberPlugin from '@frontmcp/plugin-remember';
 import { ApprovalPlugin } from '@frontmcp/plugin-approval';
 import CachePlugin from '@frontmcp/plugin-cache';
+import CodeCallPlugin from '@frontmcp/plugin-codecall';
 import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
+import RememberPlugin from '@frontmcp/plugin-remember';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({ name: 'core', tools: [ReadDataTool, WriteDataTool, DeleteDataTool] })
 class CoreApp {}
@@ -89,8 +89,7 @@ class ProductionServer {}
 
 ```typescript
 // src/tools/delete-data.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'delete_data',

package/catalog/frontmcp-development/examples/official-plugins/remember-plugin-session-memory.md

@@ -20,8 +20,8 @@ Demonstrates installing the Remember plugin and using `this.remember` in tools t
 
 ```typescript
 // src/server.ts
-import { FrontMcp, App } from '@frontmcp/sdk';
 import RememberPlugin from '@frontmcp/plugin-remember';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({ name: 'my-app', tools: [PreferencesTool, GreetingTool] })
 class MyApp {}
@@ -41,8 +41,7 @@ class MyServer {}
 
 ```typescript
 // src/tools/preferences.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'set_preferences',
@@ -64,8 +63,7 @@ class PreferencesTool extends ToolContext {
 
 ```typescript
 // src/tools/greeting.tool.ts
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'get_greeting',

package/catalog/frontmcp-development/examples/{official-adapters → openapi-adapter}/authenticated-adapter-with-polling.md

@@ -1,6 +1,6 @@
 ---
 name: authenticated-adapter-with-polling
-reference: official-adapters
+reference: openapi-adapter
 level: intermediate
 description: 'Demonstrates configuring authentication (API key and bearer token) and automatic spec polling for OpenAPI adapters.'
 tags: [development, auth, openapi, security, adapters, authenticated]
@@ -80,5 +80,5 @@ class MyServer {}
 
 ## Related
 
-- See `official-adapters` for inline specs, multiple adapter registration, and troubleshooting
+- See `openapi-adapter` for all five auth strategies, format resolution, and $ref security
 - See `decorators-guide` for the full `@App` and `@FrontMcp` field reference

package/catalog/frontmcp-development/examples/{official-adapters → openapi-adapter}/basic-openapi-adapter.md

@@ -1,6 +1,6 @@
 ---
 name: basic-openapi-adapter
-reference: official-adapters
+reference: openapi-adapter
 level: basic
 description: 'Demonstrates converting an OpenAPI specification into MCP tools automatically using `OpenapiAdapter` with minimal configuration.'
 tags: [development, openapi, adapters, adapter]
@@ -51,4 +51,4 @@ class MyServer {}
 
 ## Related
 
-- See `official-adapters` for authentication options, spec polling, and inline specs
+- See `openapi-adapter` for authentication, filtering, transforms, and security options

package/catalog/frontmcp-development/examples/openapi-adapter/format-resolution-and-custom-resolvers.md

@@ -0,0 +1,108 @@
+---
+name: format-resolution-and-custom-resolvers
+reference: openapi-adapter
+level: intermediate
+description: 'Demonstrates using built-in and custom format resolvers to enrich tool input schemas with concrete constraints from OpenAPI format values.'
+tags: [development, openapi, adapters, format, schema, validation]
+features:
+  - 'Enabling built-in format resolvers with `resolveFormats: true` for uuid, date-time, email, int32, etc.'
+  - 'Adding custom format resolvers for domain-specific formats (phone, currency)'
+  - 'Merging custom resolvers with built-ins where custom takes precedence'
+  - 'Using custom-only resolvers without built-ins for full control'
+---
+
+# Format Resolution and Custom Resolvers
+
+Demonstrates using built-in and custom format resolvers to enrich tool input schemas with concrete constraints from OpenAPI format values.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { OpenapiAdapter } from '@frontmcp/adapters';
+
+@App({
+  name: 'format-demo',
+  adapters: [
+    // Built-in format resolvers only
+    // uuid fields get regex patterns, date-time gets ISO 8601 format,
+    // int32 gets min/max constraints, email gets validation pattern
+    OpenapiAdapter.init({
+      name: 'users-api',
+      url: 'https://api.example.com/openapi.json',
+      baseUrl: 'https://api.example.com',
+      generateOptions: {
+        resolveFormats: true,
+      },
+    }),
+
+    // Built-in + custom format resolvers
+    // Custom resolvers are merged with built-ins; custom takes precedence
+    OpenapiAdapter.init({
+      name: 'payments-api',
+      url: 'https://payments.example.com/openapi.json',
+      baseUrl: 'https://payments.example.com',
+      generateOptions: {
+        resolveFormats: true,
+        formatResolvers: {
+          // Domain-specific formats
+          phone: (schema) => ({
+            ...schema,
+            pattern: '^\\+[1-9]\\d{1,14}$',
+            description: 'E.164 international phone number (e.g., +14155552671)',
+          }),
+          currency: (schema) => ({
+            ...schema,
+            pattern: '^[A-Z]{3}$',
+            description: 'ISO 4217 currency code (e.g., USD, EUR, GBP)',
+          }),
+          'country-code': (schema) => ({
+            ...schema,
+            pattern: '^[A-Z]{2}$',
+            description: 'ISO 3166-1 alpha-2 country code (e.g., US, GB, DE)',
+          }),
+        },
+      },
+    }),
+
+    // Custom resolvers only (no built-ins)
+    // Only the formats you explicitly define are resolved
+    OpenapiAdapter.init({
+      name: 'legacy-api',
+      url: 'https://legacy.example.com/openapi.json',
+      baseUrl: 'https://legacy.example.com',
+      generateOptions: {
+        // Without resolveFormats: true, only custom resolvers apply
+        formatResolvers: {
+          'social-security': (schema) => ({
+            ...schema,
+            pattern: '^\\d{3}-\\d{2}-\\d{4}$',
+            description: 'US Social Security Number (XXX-XX-XXXX)',
+          }),
+        },
+      },
+    }),
+  ],
+})
+class FormatDemoApp {}
+
+@FrontMcp({
+  info: { name: 'format-demo-server', version: '1.0.0' },
+  apps: [FormatDemoApp],
+  http: { port: 3000 },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Enabling built-in format resolvers with `resolveFormats: true` for uuid, date-time, email, int32, etc.
+- Adding custom format resolvers for domain-specific formats (phone, currency)
+- Merging custom resolvers with built-ins where custom takes precedence
+- Using custom-only resolvers without built-ins for full control
+
+## Related
+
+- See `openapi-adapter` for all generate options, authentication, and $ref security
+- See `create-tool` for building tools with manual schema definitions

package/catalog/frontmcp-development/examples/{official-adapters → openapi-adapter}/multi-api-hub-with-inline-spec.md

@@ -1,6 +1,6 @@
 ---
 name: multi-api-hub-with-inline-spec
-reference: official-adapters
+reference: openapi-adapter
 level: advanced
 description: 'Demonstrates registering multiple OpenAPI adapters from different APIs in a single app, including one with an inline spec definition instead of a remote URL.'
 tags: [development, openapi, remote, adapters, multi, api]
@@ -126,5 +126,5 @@ class MyServer {}
 
 ## Related
 
-- See `official-adapters` for spec polling, `securityResolver`, and the adapter vs plugin comparison
+- See `openapi-adapter` for spec polling, `securityResolver`, and filtering operations
 - See `decorators-guide` for the `@Adapter` decorator and how adapters fit in the hierarchy

package/catalog/frontmcp-development/examples/openapi-adapter/ref-security-and-filtering.md

@@ -0,0 +1,111 @@
+---
+name: ref-security-and-filtering
+reference: openapi-adapter
+level: intermediate
+description: 'Demonstrates configuring $ref resolution security to prevent SSRF attacks and filtering which API operations become MCP tools.'
+tags: [development, openapi, adapters, security, ssrf, filtering]
+features:
+  - 'Configuring `refResolution` to restrict which hosts and protocols are allowed for external `$ref` pointers'
+  - 'Using `allowedHosts` to restrict $refs to trusted schema servers'
+  - 'Using `allowedProtocols` to enable or disable file://, http://, https://, and other protocols'
+  - 'Filtering operations with `includeOperations`, `excludeOperations`, and `filterFn`'
+  - 'Combining security hardening with operation filtering for a production-ready setup'
+---
+
+# $ref Security and Operation Filtering
+
+Demonstrates configuring $ref resolution security to prevent SSRF attacks and filtering which API operations become MCP tools.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { OpenapiAdapter } from '@frontmcp/adapters';
+
+@App({
+  name: 'secure-app',
+  adapters: [
+    // Production-hardened: restrict $refs to trusted hosts + filter operations
+    OpenapiAdapter.init({
+      name: 'partner-api',
+      url: 'https://api.partner.com/openapi.json',
+      baseUrl: 'https://api.partner.com',
+      loadOptions: {
+        refResolution: {
+          // Only allow $refs pointing to the partner's own schema server
+          allowedHosts: ['schemas.partner.com', 'api.partner.com'],
+          // Block additional hosts known to be problematic
+          blockedHosts: ['internal.partner.com'],
+        },
+      },
+      generateOptions: {
+        // Only expose read operations to MCP clients
+        filterFn: (op) => op.method === 'get',
+        // Skip deprecated endpoints
+        includeDeprecated: false,
+      },
+      staticAuth: {
+        apiKey: process.env.PARTNER_API_KEY!,
+      },
+    }),
+
+    // Internal API: allow internal IPs but lock down to specific operations
+    OpenapiAdapter.init({
+      name: 'internal-api',
+      url: 'http://10.0.0.5:8080/openapi.json',
+      baseUrl: 'http://10.0.0.5:8080',
+      loadOptions: {
+        refResolution: {
+          // Allow internal IPs since this is a trusted internal service
+          allowInternalIPs: true,
+        },
+      },
+      generateOptions: {
+        // Only include specific safe operations
+        includeOperations: ['getStatus', 'listMetrics', 'getConfig'],
+      },
+    }),
+
+    // Maximum lockdown: no external $refs at all
+    OpenapiAdapter.init({
+      name: 'sandbox-api',
+      url: 'https://sandbox.example.com/openapi.json',
+      baseUrl: 'https://sandbox.example.com',
+      loadOptions: {
+        refResolution: {
+          // Block ALL external $ref resolution — only local #/ pointers work
+          allowedProtocols: [],
+        },
+      },
+      generateOptions: {
+        // Exclude admin and dangerous operations
+        excludeOperations: ['deleteAll', 'resetDatabase', 'adminPanel'],
+        // Only include billing-related paths
+        filterFn: (op) => op.path.startsWith('/billing') || op.path.startsWith('/invoices'),
+      },
+    }),
+  ],
+})
+class SecureApp {}
+
+@FrontMcp({
+  info: { name: 'secure-server', version: '1.0.0' },
+  apps: [SecureApp],
+  http: { port: 3000 },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Configuring `refResolution` to restrict which hosts and protocols are allowed for external `$ref` pointers
+- Using `allowedHosts` to restrict $refs to trusted schema servers
+- Using `allowedProtocols` to enable or disable file://, http://, https://, and other protocols
+- Filtering operations with `includeOperations`, `excludeOperations`, and `filterFn`
+- Combining security hardening with operation filtering for a production-ready setup
+
+## Related
+
+- See `openapi-adapter` for all `refResolution` options and the full blocked IP list
+- See `official-adapters` for the adapter vs plugin comparison

package/catalog/frontmcp-development/references/create-agent.md

@@ -43,8 +43,7 @@ Agents are autonomous AI entities that use an LLM to reason, plan, and invoke in
 Create a class extending `AgentContext<In, Out>` and optionally override the `execute(input: In): Promise<Out>` method. The `@Agent` decorator requires `name`, `description`, and `llm` configuration.
 
 ```typescript
-import { Agent, AgentContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Agent, AgentContext, z } from '@frontmcp/sdk';
 
 @Agent({
   name: 'code_reviewer',
@@ -242,8 +241,7 @@ async execute(input: { text: string }) {
 The `tools` array in `@Agent` metadata defines tools that the agent itself can invoke during its reasoning loop. These are NOT exposed to external callers -- they are private to the agent.
 
 ```typescript
-import { Tool, ToolContext, Agent, AgentContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Agent, AgentContext, Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'fetch_pr',
@@ -406,8 +404,7 @@ class BillingAgent extends AgentContext {}
 For agents that do not need a class, use the `agent()` function builder.
 
 ```typescript
-import { agent } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { agent, z } from '@frontmcp/sdk';
 
 const QuickSummarizer = agent({
   name: 'quick_summarizer',
@@ -458,7 +455,7 @@ Both return values that can be registered in `agents: [ExternalAgent, CloudAgent
 Add agent classes (or function-style agents) to the `agents` array in `@FrontMcp` or `@App`.
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'review-app',

package/catalog/frontmcp-development/references/create-job.md

@@ -50,8 +50,7 @@ Create a class extending `JobContext<In, Out>` and implement the `execute(input:
 ### Basic Example
 
 ```typescript
-import { Job, JobContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Job, JobContext, z } from '@frontmcp/sdk';
 
 @Job({
   name: 'generate-report',
@@ -339,8 +338,7 @@ permissions: {
 For simple jobs that do not need a class, use the `job()` function builder. The callback receives `(input, ctx)` where `ctx` provides all `JobContext` methods.
 
 ```typescript
-import { job } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { job, z } from '@frontmcp/sdk';
 
 const CleanupTempFiles = job({
   name: 'cleanup-temp-files',
@@ -444,8 +442,7 @@ This creates the job file, spec file, and updates barrel exports.
 ## Complete Example: Data Pipeline Job
 
 ```typescript
-import { Job, JobContext, FrontMcp, App, job } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { App, FrontMcp, Job, job, JobContext, z } from '@frontmcp/sdk';
 
 @Job({
   name: 'etl-pipeline',

package/catalog/frontmcp-development/references/create-plugin-hooks.md

@@ -72,7 +72,7 @@ In addition to flow-based hooks, plugins can register callbacks for server lifec
 Runs after the HTTP server is fully initialized and listening. Use for warming caches, starting background indexing, or logging readiness.
 
 ```typescript
-import { Plugin, DynamicPlugin } from '@frontmcp/sdk';
+import { DynamicPlugin, Plugin } from '@frontmcp/sdk';
 
 @Plugin({
   name: 'cache-warmer',
@@ -105,12 +105,12 @@ For convenience, FrontMCP exports typed aliases so you do not need to call `Flow
 
 ```typescript
 import {
-  ToolHook, // FlowHooksOf('tools:call-tool')
-  ListToolsHook, // FlowHooksOf('tools:list-tools')
-  ResourceHook, // FlowHooksOf('resources:read-resource')
-  ListResourcesHook, // FlowHooksOf('resources:list-resources')
   AgentCallHook, // FlowHooksOf('agents:call-agent')
   HttpHook, // FlowHooksOf('http:request')
+  ListResourcesHook, // FlowHooksOf('resources:list-resources')
+  ListToolsHook, // FlowHooksOf('tools:list-tools')
+  ResourceHook, // FlowHooksOf('resources:read-resource')
+  ToolHook, // FlowHooksOf('tools:call-tool')
 } from '@frontmcp/sdk';
 ```
 
@@ -152,8 +152,7 @@ Both `@Will` and `@Did` (and `@Around`) accept an optional options object:
 ### Logging Plugin
 
 ```typescript
-import { Plugin } from '@frontmcp/sdk';
-import { ToolHook } from '@frontmcp/sdk';
+import { Plugin, ToolHook } from '@frontmcp/sdk';
 
 const { Will, Did } = ToolHook;
 
@@ -174,8 +173,7 @@ export class LoggingPlugin {
 ### Authorization Check Plugin
 
 ```typescript
-import { Plugin } from '@frontmcp/sdk';
-import { ToolHook } from '@frontmcp/sdk';
+import { Plugin, ToolHook } from '@frontmcp/sdk';
 
 const { Will } = ToolHook;
 
@@ -194,8 +192,7 @@ export class AuthCheckPlugin {
 ### Caching Plugin with @Around
 
 ```typescript
-import { Plugin } from '@frontmcp/sdk';
-import { ToolHook } from '@frontmcp/sdk';
+import { Plugin, ToolHook } from '@frontmcp/sdk';
 
 const { Around } = ToolHook;
 
@@ -227,8 +224,7 @@ export class CachePlugin {
 ### Stage Replacement
 
 ```typescript
-import { Plugin } from '@frontmcp/sdk';
-import { ToolHook } from '@frontmcp/sdk';
+import { Plugin, ToolHook } from '@frontmcp/sdk';
 
 const { Stage } = ToolHook;
 
@@ -249,8 +245,9 @@ Register plugins in your `@App` decorator:
 
 ```typescript
 import { App } from '@frontmcp/sdk';
-import { LoggingPlugin } from './plugins/logging.plugin';
+
 import { CachePlugin } from './plugins/cache.plugin';
+import { LoggingPlugin } from './plugins/logging.plugin';
 
 @App({
   name: 'my-app',
@@ -266,8 +263,7 @@ Plugins are initialized in array order. Hook priority determines execution order
 You can add hook methods directly on a `@Tool` class to intercept its own execution flow. The hooks apply only when **this tool** is called:
 
 ```typescript
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 const { Will, Did } = ToolHook;
 

package/catalog/frontmcp-development/references/create-skill-with-tools.md

@@ -431,7 +431,7 @@ Both return values that can be registered in `skills: [ExternalSkill, CloudSkill
 Add skill classes (or function-style skills) to the `skills` array in `@FrontMcp` or `@App`.
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'devops-app',
@@ -505,8 +505,7 @@ GET /skills
 ## Complete Example: Multi-Tool Orchestration Skill
 
 ```typescript
-import { Skill, SkillContext, Tool, ToolContext, FrontMcp, App } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { App, FrontMcp, Skill, SkillContext, Tool, ToolContext, z } from '@frontmcp/sdk';
 
 // Define the tools that the skill references