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

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

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

Common Patterns

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

Examples

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

vectoriadb

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:

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