@frontmcp/skills 0.0.1 → 1.0.0-beta.10

package/catalog/frontmcp-development/references/official-adapters.md

@@ -0,0 +1,194 @@
+# Official Adapters
+
+Adapters convert external definitions (OpenAPI specs, Lambda functions, etc.) into MCP tools, resources, and prompts automatically.
+
+## When to Use This Skill
+
+### Must Use
+
+- Converting an OpenAPI/Swagger specification into MCP tools automatically
+- Integrating a REST API that provides a public OpenAPI spec (Petstore, GitHub, Jira, Slack)
+- Setting up authentication (API key, bearer token, OAuth) for an adapter-generated API integration
+
+### Recommended
+
+- Registering multiple external APIs as namespaced tool sets in a single server
+- Enabling spec polling to auto-refresh tool definitions when the upstream API changes
+- Providing an inline OpenAPI spec for APIs without a hosted spec URL
+
+### Skip When
+
+- The external API has no OpenAPI spec and uses a custom protocol (see `create-adapter`)
+- You need cross-cutting behavior like caching or logging (see `create-plugin` or `official-plugins`)
+- You are building tools manually without an external spec (see `create-tool`)
+
+> **Decision:** Use this skill when you have an OpenAPI/Swagger spec and want to automatically generate MCP tools from it using `OpenapiAdapter`.
+
+## OpenAPI Adapter
+
+The primary official adapter. Converts OpenAPI/Swagger specifications into MCP tools — one tool per operation.
+
+### Installation
+
+```typescript
+import { OpenapiAdapter } from '@frontmcp/adapters';
+
+@App({
+  name: 'MyApp',
+  adapters: [
+    OpenapiAdapter.init({
+      name: 'petstore',
+      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
+    }),
+  ],
+})
+class MyApp {}
+```
+
+Each OpenAPI operation becomes an MCP tool named `petstore:operationId`.
+
+### With Authentication
+
+```typescript
+// API Key via static auth
+OpenapiAdapter.init({
+  name: 'my-api',
+  url: 'https://api.example.com/openapi.json',
+  baseUrl: 'https://api.example.com',
+  staticAuth: {
+    apiKey: process.env.API_KEY!,
+  },
+});
+
+// API Key via additional headers
+OpenapiAdapter.init({
+  name: 'my-api',
+  url: 'https://api.example.com/openapi.json',
+  baseUrl: 'https://api.example.com',
+  additionalHeaders: {
+    'X-API-Key': process.env.API_KEY!,
+  },
+});
+
+// Bearer token via static auth
+OpenapiAdapter.init({
+  name: 'my-api',
+  url: 'https://api.example.com/openapi.json',
+  baseUrl: 'https://api.example.com',
+  staticAuth: {
+    jwt: process.env.API_TOKEN!,
+  },
+});
+
+// Dynamic auth per tool using securityResolver
+OpenapiAdapter.init({
+  name: 'my-api',
+  url: 'https://api.example.com/openapi.json',
+  baseUrl: 'https://api.example.com',
+  securityResolver: (tool, ctx) => {
+    return { jwt: ctx.authInfo?.token };
+  },
+});
+```
+
+### Spec Polling
+
+Automatically refresh the OpenAPI spec at intervals:
+
+```typescript
+OpenapiAdapter.init({
+  name: 'evolving-api',
+  url: 'https://api.example.com/openapi.json',
+  polling: {
+    intervalMs: 300000, // Re-fetch every 5 minutes
+  },
+});
+```
+
+### Inline Spec
+
+Provide the OpenAPI spec directly instead of fetching from URL:
+
+```typescript
+OpenapiAdapter.init({
+  name: 'my-api',
+  spec: {
+    openapi: '3.0.0',
+    info: { title: 'My API', version: '1.0.0' },
+    paths: { ... },
+  },
+})
+```
+
+### Multiple Adapters
+
+Register adapters from different APIs in the same app:
+
+```typescript
+@App({
+  name: 'IntegrationHub',
+  adapters: [
+    OpenapiAdapter.init({ name: 'github', url: 'https://api.github.com/openapi.json' }),
+    OpenapiAdapter.init({ name: 'jira', url: 'https://jira.example.com/openapi.json' }),
+    OpenapiAdapter.init({ name: 'slack', url: 'https://slack.com/openapi.json' }),
+  ],
+})
+class IntegrationHub {}
+// Tools: github:createIssue, jira:createTicket, slack:postMessage, etc.
+```
+
+## Adapter vs Plugin
+
+| Aspect      | Adapter                              | Plugin                              |
+| ----------- | ------------------------------------ | ----------------------------------- |
+| Purpose     | Generate tools from external sources | Add cross-cutting behavior          |
+| Output      | Tools, resources, prompts            | Lifecycle hooks, context extensions |
+| Examples    | OpenAPI → MCP tools                  | Caching, auth, logging              |
+| When to use | Integrating APIs                     | Adding middleware                   |
+
+## Common Patterns
+
+| Pattern              | Correct                                                                      | Incorrect                                           | Why                                                                              |
+| -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Adapter registration | `OpenapiAdapter.init({ name: 'petstore', url: '...' })` in `adapters` array  | Placing adapter in `plugins` array                  | Adapters go in `adapters`, not `plugins`; they serve different purposes          |
+| Tool naming          | Tools auto-named as `petstore:operationId` using adapter `name` as namespace | Expecting flat names like `listPets`                | Adapter name is prepended to prevent collisions across multiple adapters         |
+| Auth configuration   | `staticAuth: { jwt: process.env.API_TOKEN! }` or `additionalHeaders`         | Hardcoding secrets: `staticAuth: { jwt: 'sk-xxx' }` | Always use environment variables for secrets; never commit tokens                |
+| Spec source          | Use `url` for hosted specs or `spec` for inline definitions                  | Using both `url` and `spec` simultaneously          | Only one source should be provided; `spec` takes precedence and `url` is ignored |
+| Multiple APIs        | Register separate `OpenapiAdapter.init()` calls with unique `name` values    | Using the same `name` for different adapters        | Duplicate names cause tool naming collisions                                     |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@frontmcp/adapters` package is installed
+- [ ] `OpenapiAdapter.init()` is in the `adapters` array of `@App`
+- [ ] Adapter has a unique `name` for tool namespacing
+- [ ] `url` points to a valid, reachable OpenAPI JSON/YAML endpoint (or `spec` is inline)
+
+### Runtime
+
+- [ ] Generated tools appear in `tools/list` with `<name>:<operationId>` naming
+- [ ] Auth headers are sent correctly on API calls
+- [ ] Spec polling refreshes tool definitions at the configured interval
+- [ ] Invalid spec URL produces a clear startup error
+
+### Production
+
+- [ ] API tokens and secrets are loaded from environment variables
+- [ ] Polling interval is appropriate for the API's update frequency
+- [ ] Multiple adapter registrations use distinct names
+
+## Troubleshooting
+
+| Problem                            | Cause                                                  | Solution                                                                                                                                                                        |
+| ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No tools generated from spec       | Spec URL returns non-OpenAPI content or is unreachable | Verify URL returns valid OpenAPI 3.x JSON; check network access                                                                                                                 |
+| Authentication errors on API calls | Wrong auth config or missing credentials               | Configure `staticAuth` for fixed credentials, `securityResolver`/`authProviderMapper` for dynamic auth, or `additionalHeaders` for header-based tokens; verify env vars are set |
+| Duplicate tool name error          | Two adapters registered with the same `name`           | Give each adapter a unique `name` (e.g., `'github'`, `'jira'`)                                                                                                                  |
+| Stale tools after API update       | Spec polling not configured                            | Add `polling: { intervalMs: 300000 }` to refresh every 5 minutes                                                                                                                |
+| TypeScript error importing adapter | Wrong import path                                      | Import from `@frontmcp/adapters`: `import { OpenapiAdapter } from '@frontmcp/adapters'`                                                                                         |
+
+## Reference
+
+- [Adapter Overview Documentation](https://docs.agentfront.dev/frontmcp/adapters/overview)
+- Related skills: `create-adapter`, `create-plugin`, `create-tool`

package/catalog/{plugins/official-plugins/SKILL.md → frontmcp-development/references/official-plugins.md}

@@ -1,17 +1,30 @@
----
-name: official-plugins
-description: Install and configure official FrontMCP plugins including CodeCall, Remember, Approval, Cache, Feature Flags, and Dashboard. Use when adding caching, memory, tool approval, feature gating, or CodeCall orchestration.
-tags: [plugins, codecall, remember, approval, cache, feature-flags, dashboard]
-priority: 9
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/plugins/overview
----
-
 # Official FrontMCP Plugins
 
-FrontMCP ships 6 official plugins that extend server behavior with cross-cutting concerns: semantic tool discovery, session memory, authorization workflows, result caching, feature gating, and visual monitoring. Install individually or via `@frontmcp/plugins` (meta-package re-exporting cache, codecall, dashboard, and remember).
+FrontMCP ships 6 official plugins that extend server behavior with cross-cutting concerns: semantic tool discovery, session memory, authorization workflows, result caching, feature gating, and visual monitoring. Install individually or via `@frontmcp/plugins` (meta-package re-exporting cache, codecall, and remember).
+
+> **Note:** The Dashboard plugin (`@frontmcp/plugin-dashboard`) is currently in **beta** and may not work correctly in all environments. It is not recommended for production use at this time.
+
+## When to Use This Skill
+
+### Must Use
+
+- Installing and configuring any official FrontMCP plugin (CodeCall, Remember, Approval, Cache, Feature Flags)
+- Adding session memory, tool caching, or authorization workflows to an existing server
+- Integrating feature flag services (LaunchDarkly, Split.io, Unleash) to gate tools at runtime
+
+### Recommended
+
+- Exploring the Dashboard plugin for visual monitoring (beta — not recommended for production)
+- Configuring CodeCall for semantic tool discovery when the server has many tools
+- Combining multiple official plugins in a production deployment
+
+### Skip When
+
+- You need to build a custom plugin with your own providers and context extensions (see `create-plugin`)
+- You only need lifecycle hooks without installing an official plugin (see `create-plugin-hooks`)
+- You need to generate tools from an OpenAPI spec (see `official-adapters`)
+
+> **Decision:** Use this skill when you need to install, configure, or customize one or more of the 5 stable official FrontMCP plugins. The Dashboard plugin is in beta — see its section below for details.
 
 All plugins follow the `DynamicPlugin` pattern and are registered via `@FrontMcp({ plugins: [...] })`.
 
@@ -22,9 +35,9 @@ import RememberPlugin from '@frontmcp/plugin-remember';
 import { ApprovalPlugin } from '@frontmcp/plugin-approval';
 import CachePlugin from '@frontmcp/plugin-cache';
 import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
-import DashboardPlugin from '@frontmcp/plugin-dashboard';
+// import DashboardPlugin from '@frontmcp/plugin-dashboard'; // Beta — not recommended for production
 
-@App()
+@App({ name: 'MyApp' })
 class MyApp {}
 
 @FrontMcp({
@@ -36,7 +49,7 @@ class MyApp {}
     ApprovalPlugin.init({ mode: 'recheck' }),
     CachePlugin.init({ type: 'memory', defaultTTL: 86400 }),
     FeatureFlagPlugin.init({ adapter: 'static', flags: { 'new-tool': true } }),
-    DashboardPlugin.init({ enabled: true }),
+    // DashboardPlugin.init({ enabled: true }), // Beta — see Dashboard section below
   ],
   tools: [
     /* your tools */
@@ -79,10 +92,25 @@ class MyServer {}
 
 ### Modes
 
-- `codecall_only` -- Hides all tools from `list_tools` except CodeCall meta-tools. All other tools are discovered only via `codecall:search`. Best when the server has a large number of tools and you want the AI to search-then-execute.
+- `codecall_only` -- Hides all tools from `list_tools` except CodeCall meta-tools. All other tools are discovered only via `codecall:search`. Best when the server has a large number of tools and you want the AI to search-then-execute. When `appIds` is set, only tools from those apps are hidden — tools from other apps remain visible.
 - `codecall_opt_in` -- Shows all tools in `list_tools` normally. Tools opt-in to CodeCall execution via metadata. Useful when only some tools benefit from orchestrated execution.
 - `metadata_driven` -- Per-tool `metadata.codecall` controls visibility and CodeCall availability independently. Most granular control.
 
+### Multi-App Scoping
+
+Use `appIds` to scope CodeCall to specific apps in a multi-app server:
+
+```typescript
+// Only hide ecommerce tools — calc tools remain visible in list_tools
+CodeCallPlugin.init({
+  mode: 'codecall_only',
+  appIds: ['ecommerce'],
+  vm: { preset: 'secure' },
+});
+```
+
+Without `appIds`, `codecall_only` mode hides ALL tools in the server. With `appIds`, only tools from the specified apps are hidden — tools from other apps remain directly callable.
+
 ### VM Presets
 
 The sandboxed VM runs AgentScript (a restricted JavaScript subset). Presets control security boundaries:
@@ -96,9 +124,9 @@ The sandboxed VM runs AgentScript (a restricted JavaScript subset). Presets cont
 
 CodeCall contributes 4 tools to your server:
 
-- `codecall:search` -- Semantic search over all registered tools using TF-IDF scoring with synonym expansion. Returns ranked tool names, descriptions, and relevance scores.
-- `codecall:describe` -- Returns full input/output JSON schemas for one or more tools. Use after search to understand tool interfaces before execution.
-- `codecall:execute` -- Runs an AgentScript program in the sandboxed VM. The script can call multiple tools, branch on results, and compose outputs.
+- `codecall:search` -- Semantic search over all registered tools using TF-IDF scoring with synonym expansion. Input: `{ queries: string[] }` (array of atomic action phrases, max 10). Decompose complex requests into simple actions (e.g., "delete users and send email" becomes `queries: ["delete user", "send email"]`). Returns ranked tool names, descriptions, and relevance scores.
+- `codecall:describe` -- Returns full input/output JSON schemas for one or more tools. Input: `{ toolNames: string[] }` (tool names from search results). Use after search to understand tool interfaces before execution. If `notFound` array is non-empty in the response, re-search with corrected queries.
+- `codecall:execute` -- Runs an AgentScript program in the sandboxed VM. Input: `{ script: string }` (AgentScript code). Use `callTool(name, args)` to invoke tools within scripts. The script can call multiple tools, branch on results, and compose outputs.
 - `codecall:invoke` -- Direct single-tool invocation (available when `directCalls` is enabled). Bypasses the VM for simple one-shot calls.
 
 ### Per-Tool CodeCall Metadata
@@ -430,7 +458,7 @@ A tool is cached if it matches any pattern OR has `cache: true` (or a cache obje
 
 Send the bypass header to skip caching for a specific request:
 
-```
+```text
 x-frontmcp-disable-cache: true
 ```
 
@@ -569,7 +597,9 @@ The plugin hooks into listing and execution flows for tools, resources, prompts,
 
 ---
 
-## 6. Dashboard Plugin (`@frontmcp/plugin-dashboard`)
+## 6. Dashboard Plugin (`@frontmcp/plugin-dashboard`) — BETA
+
+> **Warning:** The Dashboard plugin is currently in **beta** and may not work correctly. It is not recommended for production use. Expect breaking changes and missing features.
 
 Visual monitoring web UI for your FrontMCP server. View server structure (tools, resources, prompts, apps, plugins) as an interactive graph.
 
@@ -645,7 +675,7 @@ All official plugins use the static `init()` pattern inherited from `DynamicPlug
     ApprovalPlugin.init({ mode: 'recheck' }),
     CachePlugin.init({ type: 'redis', config: { host: 'redis.internal' }, defaultTTL: 86400 }),
     FeatureFlagPlugin.init({ adapter: 'launchdarkly', config: { sdkKey: 'sdk-xxx' } }),
-    DashboardPlugin.init({ enabled: true, auth: { enabled: true, token: process.env.DASH_TOKEN } }),
+    // DashboardPlugin.init({ enabled: true, auth: { ... } }), // Beta — not recommended for production
   ],
   tools: [
     /* ... */
@@ -654,14 +684,49 @@ All official plugins use the static `init()` pattern inherited from `DynamicPlug
 class ProductionServer {}
 ```
 
+## Common Patterns
+
+| Pattern                  | Correct                                                            | Incorrect                                                                       | Why                                                                                                      |
+| ------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Plugin registration      | `plugins: [RememberPlugin.init({ type: 'memory' })]`               | `plugins: [new RememberPlugin({ type: 'memory' })]`                             | Official plugins use `DynamicPlugin.init()` static method; direct instantiation bypasses provider wiring |
+| Remember storage in prod | `RememberPlugin.init({ type: 'redis', config: { host: '...' } })`  | `RememberPlugin.init({ type: 'memory' })` in production                         | Memory storage loses data on restart; use Redis or Vercel KV for persistence                             |
+| Cache TTL units          | `defaultTTL: 3600` (seconds)                                       | `defaultTTL: 3600000` (milliseconds)                                            | Cache TTL is in seconds, not milliseconds; 3600000 = 41 days                                             |
+| Feature flag gating      | `@Tool({ featureFlag: 'my-flag' })` on the tool decorator          | Checking `this.featureFlags.isEnabled()` inside `execute()` and returning early | Decorator-level gating hides the tool from `list_tools`; manual check still exposes it                   |
+| Dashboard (beta)         | Avoid in production — plugin is in beta and may not work correctly | `DashboardPlugin.init({})` in production                                        | Dashboard plugin is unstable; use only for local development experimentation                             |
+
+## Verification Checklist
+
+### Installation
+
+- [ ] Plugin package is installed (`@frontmcp/plugin-codecall`, `@frontmcp/plugin-remember`, etc.)
+- [ ] Plugin is registered via `.init()` in the `plugins` array of `@FrontMcp`
+- [ ] Required configuration options are provided (storage type, API keys, endpoints)
+
+### Runtime
+
+- [ ] `this.remember` / `this.approval` / `this.featureFlags` resolves in tool context
+- [ ] Cache plugin returns cached results on repeated identical calls
+- [ ] Feature-flagged tools are hidden from `list_tools` when flag is off
+- [ ] Dashboard is accessible at configured `basePath` (default: `/dashboard`) — beta, may not work
+- [ ] Approval plugin blocks unapproved tools and grants approval correctly
+
+### Production
+
+- [ ] Redis or external storage is configured for Remember and Cache plugins
+- [ ] Dashboard authentication is enabled with a secret token (if using beta Dashboard plugin)
+- [ ] Feature flag adapter connects to external service (not `'static'`)
+
+## Troubleshooting
+
+| Problem                           | Cause                                                                            | Solution                                                                             |
+| --------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `this.remember` is undefined      | RememberPlugin not registered or missing `.init()`                               | Add `RememberPlugin.init({ type: 'memory' })` to `plugins` array                     |
+| Cache not working for a tool      | Tool name does not match any `toolPatterns` glob and `cache` metadata is not set | Add `cache: true` to `@Tool` decorator or add matching pattern to `toolPatterns`     |
+| Feature flag always returns false | Using `'static'` adapter with flag not in the `flags` map                        | Add the flag key to `flags: { 'my-flag': true }` or check adapter connection         |
+| Dashboard returns 404             | Plugin is in beta and auto-disabled in production (`NODE_ENV=production`)        | Dashboard is unstable — avoid in production. For dev: set `enabled: true` explicitly |
+| Approval webhook times out        | Callback URL not reachable from the external approval service                    | Verify `callbackPath` is publicly accessible and matches the webhook configuration   |
+
 ## Reference
 
-- Plugins docs: [docs.agentfront.dev/frontmcp/plugins/overview](https://docs.agentfront.dev/frontmcp/plugins/overview)
-- `DynamicPlugin` base class: import from `@frontmcp/sdk`
-- CodeCall: `@frontmcp/plugin-codecall` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-codecall) | [docs](https://docs.agentfront.dev/frontmcp/plugins/codecall/overview)
-- Remember: `@frontmcp/plugin-remember` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-remember) | [docs](https://docs.agentfront.dev/frontmcp/plugins/remember-plugin)
-- Approval: `@frontmcp/plugin-approval` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-approval)
-- Cache: `@frontmcp/plugin-cache` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-cache) | [docs](https://docs.agentfront.dev/frontmcp/plugins/cache-plugin)
-- Feature Flags: `@frontmcp/plugin-feature-flags` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-feature-flags) | [docs](https://docs.agentfront.dev/frontmcp/plugins/feature-flags-plugin)
-- Dashboard: `@frontmcp/plugin-dashboard` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-dashboard)
-- Meta-package: `@frontmcp/plugins` (re-exports cache, codecall, dashboard, remember)
+- [Plugins Overview Documentation](https://docs.agentfront.dev/frontmcp/plugins/overview)
+- Related skills: `create-plugin`, `create-plugin-hooks`, `create-tool`