agentfront/frontmcp-extensibility

FrontMCP Extensibility

Patterns and examples for extending FrontMCP servers with external npm packages. The core SDK handles MCP protocol, DI, and lifecycle — this skill shows how to integrate third-party libraries as providers and tools.

When to Use This Skill

Must Use

• Adding semantic search or similarity matching to your server (VectoriaDB)
• Integrating an external npm package as a FrontMCP provider
• Building tools that wrap third-party services (databases, APIs, ML models)

Recommended

• Looking for patterns to structure external service integrations
• Deciding between provider-based vs direct integration for a library
• Adding capabilities like applescript automation, VM execution, or data processing

Skip When

• You need to build core MCP components (see frontmcp-development)
• You need to configure auth, transport, or CORS (see frontmcp-config)
• You need to write a plugin with hooks and context extensions (see create-plugin)

Decision: Use this skill when integrating external libraries into your FrontMCP server as providers or tools.

Prerequisites

• A FrontMCP project (see frontmcp-setup if you don't have one).
• The external library installed as a runtime dependency (not devDependency).
• Familiarity with FrontMCP providers and tools (see create-provider, create-tool).

Steps

1. Pick the integration shape — provider for stateful clients (DB, search index), tool-only for stateless one-shot calls.
2. Wrap the library in a provider — declare a typed DI token and a @Provider class so consumers depend on the boundary, not the library.
3. Register it — add to @App({ providers: [...] }) or @FrontMcp({ providers: [...] }).
4. Expose via tools/resources — call this.get(TOKEN) in ToolContext/ResourceContext; never import the library directly from the tool.
5. Handle errors at the boundary — translate library-specific errors into PublicMcpError/InvalidInputError so MCP clients see structured failures.

Scenario Routing Table

| Scenario | Reference | Description | | --------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- | | Add in-memory semantic search with VectoriaDB | references/vectoriadb.md | TF-IDF or ML semantic indexing, provider+tool pattern | | Add tamper-evident skill audit logging | references/skill-audit-log.md | Hash-chained, signed audit records for skill executions | | Load an app from an npm package | multi-app-composition (in frontmcp-setup) | App.esm('@scope/pkg@^1.0.0', 'AppName') pattern | | Connect to a remote MCP server | multi-app-composition (in frontmcp-setup) | App.remote('https://...', 'ns') pattern | | Build a reusable plugin with hooks | create-plugin-hooks (in frontmcp-development) | DynamicPlugin, context extensions, lifecycle hooks | | Build a custom adapter for an external source | create-adapter (in frontmcp-development) | DynamicAdapter for OpenAPI, GraphQL, or custom sources | | Auto-generate tools from an OpenAPI spec | official-adapters (in frontmcp-development) | OpenapiAdapter with filtering, auth, and transforms |

Integration Pattern

The standard pattern for integrating any external library:

1. Create a provider — wraps the library as a singleton or scoped service
2. Register the provider — add to @App({ providers: [...] }) or @FrontMcp({ providers: [...] })
3. Create tools — expose the provider's capabilities as MCP tools via this.get(ProviderClass) (the class itself is the DI token)
4. Optionally create resources — expose data as MCP resources with autocompletion

// 1. Provider wraps the library (the class itself is the DI token)
@Provider({ name: 'my-search', scope: ProviderScope.GLOBAL })
export class SearchProvider {
  private client: ExternalLibrary;
  constructor() {
    this.client = new ExternalLibrary({
      /* config */
    });
  }
  async search(query: string) {
    return this.client.query(query);
  }
}

// 2. Tool exposes it
@Tool({ name: 'search', inputSchema: { query: z.string() } })
export default class SearchTool extends ToolContext {
  async execute(input: { query: string }) {
    return this.get(SearchProvider).search(input.query);
  }
}

Available Integrations

| Library | Purpose | Reference | | ------------------- | ---------------------------------------------------- | ------------------------------- | | VectoriaDB | In-memory TF-IDF semantic search | references/vectoriadb.md | | Skill audit log | Tamper-evident hash-chained audit log for skill runs | references/skill-audit-log.md |

More integrations can be added as references (e.g., enclave-vm, applescript, database clients).

Common Patterns

| Pattern | Correct | Incorrect | Why | | -------------------- | ------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------- | | Library access | this.get(SearchToken) from a tool | import { client } from 'lib' in a tool | DI boundary lets you swap implementations and test in isolation | | Provider scope | ProviderScope.GLOBAL for shared clients | New instance per request | Library clients (DB pools, indices) are expensive to construct | | Async initialisation | onInit() lifecycle hook on the provider | Constructor await | Constructors can't be async; onInit is the framework's init seam | | Error surfaces | Throw PublicMcpError/InvalidInputError | Re-throw raw library errors | Library stack traces leak internals and aren't JSON-RPC error-coded |

Verification Checklist

• [ ] External library is in dependencies (not devDependencies)
• [ ] Provider wraps the library with proper initialization and cleanup
• [ ] Provider class is listed in @App or @FrontMcp providers: [...] array (the class itself is the DI token)
• [ ] Tools use this.get(ProviderClass) to access the provider (not direct imports)
• [ ] Error handling wraps library-specific errors into MCP error classes

Troubleshooting

| Problem | Cause | Solution | | -------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Cannot find module '<lib>' at runtime | Library declared as devDependency only | Move to dependencies; rebuild the bundle if deploying as MCPB/CLI | | Provider constructed once per request | Default scope used; expensive client recreated each call | Set scope: ProviderScope.GLOBAL on the @Provider decorator | | Tool sees undefined from this.get(TOKEN) | Provider not registered in the active @App/@FrontMcp scope | Add the provider class to the scope's providers: [...] array | | Browser build fails with Node-only library | Library uses node: modules not available at the target | Gate behind availableWhen.platform, or move the integration into a server-only app and call it via a remote transport |

Examples

Each reference has matching examples under examples/<reference>/:

vectoriadb

| Example | Level | Description | | ----------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | product-catalog-search | 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 | Intermediate | Shows how to use VectoriaDB for semantic search with transformer models, filtered search, and FileStorageAdapter for persistence across restarts. | | tfidf-keyword-search | Basic | Shows how to use TFIDFVectoria for zero-dependency keyword search in a FrontMCP provider, with field weights and index building. |

Accessing This Skill

Skills are distributed as plain SKILL.md files plus a sibling references/ and examples/ tree, so consumers can pick whichever access mode fits:

| Mode | How it works | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Filesystem | Read libs/skills/catalog/frontmcp-extensibility/ directly from a clone of the catalog repo, or from a published @frontmcp/skills install. SKILL.md is the entry point. | | frontmcp CLI | frontmcp skills list, frontmcp skills read frontmcp-extensibility, frontmcp skills read frontmcp-extensibility:references/<file>.md, frontmcp skills install frontmcp-extensibility — no server required. | | MCP skill:// | When a developer mounts this skill into their own FrontMCP server (@FrontMcp({ skills: [...] })), the SDK exposes it via SEP-2640 resources: skill://frontmcp-extensibility/SKILL.md, skill://frontmcp-extensibility/references/{file}.md, etc. The server’s skill://index.json returns the SEP-2640 discovery document for everything mounted on it. |

The catalog itself is not an MCP server. The skill:// URIs only resolve when a server has been configured to host this skill.

Reference

• Related skills: create-provider, create-tool, frontmcp-development