@tigerdata/mcp-boilerplate 0.9.2 → 1.0.0

package/README.md

@@ -2,20 +2,17 @@
 
 This provides some common code for creating a [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server in Node.js.
 
-## Setup
+## Usage
 
-1. Clone the repository:
+```bash
+npm install @tigerdata/mcp-boilerplate
+```
 
-   ```bash
-   git clone <repository-url>
-   cd mcp-boilerplate-node
-   ```
+See [tiger-skills-mcp-server](https://github.com/tigerdata/tiger-skills-mcp-server) for an example MCP server using this boilerplate.
 
-2. Install dependencies:
+### Skills
 
-   ```bash
-   ./bun install
-   ```
+Add skills support to your MCP server by leveraging the skills submodule in `@tigerdata/mcp-boilerplate/skills`. See [src/skills/README.md](./skills/README.md) for details.
 
 ## Eslint Plugin
 

package/dist/http/api.d.ts

@@ -2,4 +2,4 @@
  * REST API alternative to MCP for direct use of the same tools.
  */
 import type { BaseApiFactory, RouterFactoryResult } from '../types.js';
-export declare const apiRouterFactory: <Context extends Record<string, unknown>>(context: Context, apiFactories: readonly BaseApiFactory<Context>[]) => RouterFactoryResult;
+export declare const apiRouterFactory: <Context extends Record<string, unknown>>(context: Context, apiFactories: readonly BaseApiFactory<Context>[]) => Promise<RouterFactoryResult>;

package/dist/http/api.js

@@ -4,11 +4,11 @@
 import bodyParser from 'body-parser';
 import { Router } from 'express';
 import { z } from 'zod';
-export const apiRouterFactory = (context, apiFactories) => {
+export const apiRouterFactory = async (context, apiFactories) => {
     const router = Router();
     router.use(bodyParser.json());
     for (const factory of apiFactories) {
-        const tool = factory(context, {});
+        const tool = await factory(context, {});
         if (!tool.method || !tool.route)
             continue;
         router[tool.method](tool.route, async (req, res) => {

package/dist/http/mcp.d.ts

@@ -1,8 +1,8 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { McpFeatureFlags, RouterFactoryResult } from '../types.js';
-export declare const mcpRouterFactory: <Context extends Record<string, unknown>>(context: Context, createServer: (context: Context, featureFlags: McpFeatureFlags) => {
+export declare const mcpRouterFactory: <Context extends Record<string, unknown>>(context: Context, createServer: (context: Context, featureFlags: McpFeatureFlags) => Promise<{
     server: McpServer;
-}, { name, stateful, inspector, }?: {
+}>, { name, stateful, inspector, }?: {
     name?: string;
     stateful?: boolean;
     inspector?: boolean;

package/dist/http/mcp.js

@@ -33,7 +33,7 @@ export const mcpRouterFactory = (context, createServer, { name, stateful = true,
     });
     const handleStatelessRequest = async (req, res) => {
         const featureFlags = parseFeatureFlags(req);
-        const { server } = createServer(context, featureFlags);
+        const { server } = await createServer(context, featureFlags);
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined,
         });
@@ -98,7 +98,7 @@ export const mcpRouterFactory = (context, createServer, { name, stateful = true,
                     }
                 },
             });
-            const { server } = createServer(context, featureFlags);
+            const { server } = await createServer(context, featureFlags);
             await server.connect(transport);
         }
         await transport.handleRequest(req, res, body);
@@ -201,7 +201,7 @@ export const mcpRouterFactory = (context, createServer, { name, stateful = true,
   ${inspector
                 ? `
   <h3>Inspector</h3>
-  <p>You can use the <a href="/inspector">MCP Inspector</a> for testing purposes.</p>`
+  <p>You can use the <a href="/inspector?server=${encodeURIComponent(fullUrl)}">MCP Inspector</a> for testing purposes.</p>`
                 : ''}
   <h3>Claude Code</h3>
   <p>To connect to this MCP server using Claude Code, run the following command in your terminal:</p>

package/dist/httpServer.d.ts

@@ -14,10 +14,10 @@ export declare const httpServerFactory: <Context extends Record<string, unknown>
     cleanupFn?: () => void | Promise<void>;
     stateful?: boolean;
     instructions?: string;
-}) => {
+}) => Promise<{
     app: express.Express;
     server: Server;
     apiRouter: express.Router;
     mcpRouter: express.Router;
     registerCleanupFn: (fn: () => Promise<void>) => void;
-};
+}>;

package/dist/httpServer.js

@@ -7,7 +7,7 @@ import { log } from './logger.js';
 import { mcpServerFactory } from './mcpServer.js';
 import { registerExitHandlers } from './registerExitHandlers.js';
 import { StatusError } from './StatusError.js';
-export const httpServerFactory = ({ name, version, context, apiFactories = [], promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful = true, instructions, }) => {
+export const httpServerFactory = async ({ name, version, context, apiFactories = [], promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful = true, instructions, }) => {
     const cleanupFns = cleanupFn
         ? [cleanupFn]
         : [];
@@ -31,7 +31,7 @@ export const httpServerFactory = ({ name, version, context, apiFactories = [], p
     }), { name, stateful, inspector });
     cleanupFns.push(mcpCleanup);
     app.use('/mcp', mcpRouter);
-    const [apiRouter, apiCleanup] = apiRouterFactory(context, apiFactories);
+    const [apiRouter, apiCleanup] = await apiRouterFactory(context, apiFactories);
     cleanupFns.push(apiCleanup);
     app.use('/api', apiRouter);
     // Error handler
@@ -54,7 +54,9 @@ export const httpServerFactory = ({ name, version, context, apiFactories = [], p
         import('@mcp-use/inspector')
             .then(({ mountInspector }) => {
             app.use(bodyParser.json());
-            mountInspector(app, { autoConnectUrl: `http://localhost:${PORT}/mcp` });
+            mountInspector(app, {
+                autoConnectUrl: process.env.MCP_PUBLIC_URL ?? `http://localhost:${PORT}/mcp`,
+            });
         })
             .catch(log.error);
     }

package/dist/mcpServer.d.ts

@@ -17,6 +17,6 @@ export declare const mcpServerFactory: <Context extends Record<string, unknown>>
     additionalCapabilities?: ServerCapabilities;
     featureFlags?: McpFeatureFlags;
     instructions?: string;
-}) => {
+}) => Promise<{
     server: McpServer;
-};
+}>;

package/dist/mcpServer.js

@@ -25,7 +25,7 @@ const shouldSkip = (item, enabledSets, disabledSets) => {
     }
     return false;
 };
-export const mcpServerFactory = ({ name, version = '1.0.0', context, apiFactories = [], promptFactories = [], resourceFactories = [], additionalSetup, additionalCapabilities = {}, featureFlags = {}, instructions, }) => {
+export const mcpServerFactory = async ({ name, version = '1.0.0', context, apiFactories = [], promptFactories = [], resourceFactories = [], additionalSetup, additionalCapabilities = {}, featureFlags = {}, instructions, }) => {
     const enablePrompts = featureFlags.prompts !== false;
     const enableResources = featureFlags.resources !== false;
     const enableTools = featureFlags.tools !== false;
@@ -45,7 +45,7 @@ export const mcpServerFactory = ({ name, version = '1.0.0', context, apiFactorie
     });
     if (enableTools) {
         for (const factory of apiFactories) {
-            const tool = factory(context, featureFlags);
+            const tool = await factory(context, featureFlags);
             if (shouldSkip(tool, [enabledTools, featureFlags.enabledTools], [disabledTools, featureFlags.disabledTools])) {
                 continue;
             }
@@ -111,7 +111,7 @@ export const mcpServerFactory = ({ name, version = '1.0.0', context, apiFactorie
     }
     if (enablePrompts) {
         for (const factory of promptFactories) {
-            const prompt = factory(context, featureFlags);
+            const prompt = await factory(context, featureFlags);
             if (shouldSkip(prompt, [enabledPrompts, featureFlags.enabledPrompts], [disabledPrompts, featureFlags.disabledPrompts])) {
                 continue;
             }
@@ -139,7 +139,7 @@ export const mcpServerFactory = ({ name, version = '1.0.0', context, apiFactorie
     }
     if (enableResources) {
         for (const factory of resourceFactories) {
-            const resource = factory(context, featureFlags);
+            const resource = await factory(context, featureFlags);
             if (shouldSkip(resource, [enabledResources, featureFlags.enabledResources], [disabledResources, featureFlags.disabledResources])) {
                 continue;
             }

package/dist/skills/index.d.ts

@@ -0,0 +1,5 @@
+export * from './prompts.js';
+export * from './resource.js';
+export * from './tool.js';
+export * from './types.js';
+export * from './utils.js';

package/dist/skills/index.js

@@ -0,0 +1,5 @@
+export * from './prompts.js';
+export * from './resource.js';
+export * from './tool.js';
+export * from './types.js';
+export * from './utils.js';

package/dist/skills/prompts.d.ts

@@ -0,0 +1,8 @@
+import type { Octokit } from '@octokit/rest';
+import type { PromptFactory } from '../types.js';
+import type { ServerContextWithOctokit } from './types.js';
+interface Options {
+    octokit?: Octokit;
+}
+export declare const createSkillsPromptFactories: (options?: Options) => Promise<PromptFactory<ServerContextWithOctokit, Record<string, never>>[]>;
+export {};

package/dist/skills/prompts.js

@@ -0,0 +1,31 @@
+import { loadSkills, parseSkillsFlags, viewSkillContent } from './utils.js';
+// Create a prompt for each skill from the main SKILL.md files.
+export const createSkillsPromptFactories = async (options = {}) => {
+    const skills = await loadSkills(options);
+    return Array.from(skills.entries()).map(([name, skillData]) => ({ octokit }, { query }) => ({
+        name,
+        config: {
+            // Using the dash-separated name as the title to work around a problem in Claude Code
+            // See https://github.com/anthropics/claude-code/issues/7464
+            title: name,
+            description: skillData.description,
+            inputSchema: {}, // No arguments for static skills
+        },
+        fn: async () => {
+            const flags = parseSkillsFlags(query);
+            const content = await viewSkillContent({ octokit, flags, name });
+            return {
+                description: skillData.description || name,
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: content,
+                        },
+                    },
+                ],
+            };
+        },
+    }));
+};

package/dist/skills/resource.d.ts

@@ -0,0 +1,12 @@
+import type { McpFeatureFlags, ResourceFactory } from '../types.js';
+import type { ServerContextWithOctokit } from './types.js';
+interface Options<Context extends ServerContextWithOctokit> {
+    appendSkillsListToDescription?: boolean;
+    description?: string;
+    disabled?: boolean | ((ctx: Context, flags: McpFeatureFlags) => boolean | Promise<boolean>);
+    name?: string;
+    title?: string;
+    uriScheme?: string;
+}
+export declare const createSkillsResourceFactory: <Context extends ServerContextWithOctokit>(options?: Options<Context>) => ResourceFactory<ServerContextWithOctokit>;
+export {};

package/dist/skills/resource.js

@@ -0,0 +1,47 @@
+import { listSkills, loadSkills, parseSkillsFlags, skillsDescription, skillVisible, viewSkillContent, } from './utils.js';
+export const createSkillsResourceFactory = (options = {}) => async (ctx, mcpFlags) => {
+    const { octokit } = ctx;
+    const { query } = mcpFlags;
+    const flags = parseSkillsFlags(query);
+    return {
+        type: 'templated',
+        name: options.name || 'skills',
+        disabled: typeof options.disabled === 'function'
+            ? await options.disabled(ctx, mcpFlags)
+            : options.disabled,
+        config: {
+            title: options.title || 'Skills',
+            description: `${options.description || skillsDescription}${options.appendSkillsListToDescription
+                ? `\n\n## Available Skills\n\n${await listSkills({ octokit, flags: parseSkillsFlags(query) })}`
+                : ''}`,
+        },
+        uriTemplate: `${options.uriScheme || 'skills'}://{name}{?path}`,
+        list: async () => {
+            const skills = await loadSkills({ octokit });
+            return {
+                resources: Array.from(skills.values())
+                    .filter((s) => skillVisible(s.name, flags))
+                    .map((skill) => ({
+                    uri: `${options.uriScheme || 'skills'}://${skill.name}?path=SKILL.md`,
+                    name: skill.name,
+                    title: skill.name,
+                    description: skill.description,
+                    mimeType: 'text/markdown',
+                })),
+            };
+        },
+        read: async (uri, { name, path }) => {
+            if (Array.isArray(name) || Array.isArray(path) || !name) {
+                throw new Error('Invalid parameters');
+            }
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: await viewSkillContent({ octokit, flags, name, path }),
+                    },
+                ],
+            };
+        },
+    };
+};

package/dist/skills/tool.d.ts

@@ -0,0 +1,13 @@
+import type { ApiFactory, McpFeatureFlags } from '../types.js';
+import { type ServerContextWithOctokit, zViewSkillInputSchema, zViewSkillOutputSchema } from './types.js';
+interface Options<Context extends ServerContextWithOctokit> {
+    appendSkillsListToDescription?: boolean;
+    description?: string;
+    disabled?: boolean | ((ctx: Context, flags: McpFeatureFlags) => boolean | Promise<boolean>);
+    method?: 'get' | 'post';
+    name?: string;
+    route?: string;
+    title?: string;
+}
+export declare const createViewSkillToolFactory: <Context extends ServerContextWithOctokit>(options?: Options<Context>) => ApiFactory<ServerContextWithOctokit, typeof zViewSkillInputSchema, typeof zViewSkillOutputSchema>;
+export {};

package/dist/skills/tool.js

@@ -0,0 +1,37 @@
+import { zViewSkillInputSchema, zViewSkillOutputSchema, } from './types.js';
+import { listSkills, parseSkillsFlags, skillsDescription, viewSkillContent, } from './utils.js';
+export const createViewSkillToolFactory = (options = {}) => async (ctx, mcpFlags) => {
+    const { octokit } = ctx;
+    const flags = parseSkillsFlags(mcpFlags.query);
+    return {
+        name: options.name || 'view',
+        disabled: typeof options.disabled === 'function'
+            ? await options.disabled(ctx, mcpFlags)
+            : options.disabled,
+        method: options.method || 'get',
+        route: options.route || '/view',
+        config: {
+            title: options.title || 'View Skill',
+            description: `${options.description || skillsDescription}${options.appendSkillsListToDescription
+                ? `\n\n## Available Skills\n\n${await listSkills({ octokit, flags })}`
+                : ''}`,
+            inputSchema: zViewSkillInputSchema,
+            outputSchema: zViewSkillOutputSchema,
+        },
+        fn: async ({ skill_name: name, path, }) => {
+            if (!name || name === '.') {
+                return {
+                    content: await listSkills({ octokit, flags }),
+                };
+            }
+            return {
+                content: await viewSkillContent({
+                    octokit,
+                    flags,
+                    name,
+                    path,
+                }),
+            };
+        },
+    };
+};

package/dist/skills/types.d.ts

@@ -0,0 +1,363 @@
+import type { Octokit } from '@octokit/rest';
+import { z } from 'zod';
+import type { InferSchema } from '../types.js';
+export declare const zSkillType: z.ZodEnum<["local", "local_collection", "github", "github_collection"]>;
+export type SkillType = z.infer<typeof zSkillType>;
+export declare const zLocalSkillCfg: z.ZodObject<{
+    type: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "local";
+    path: string;
+}, {
+    type: "local";
+    path: string;
+}>;
+export type LocalSkillCfg = z.infer<typeof zLocalSkillCfg>;
+declare const zCollectionFlagsCfg: z.ZodObject<{
+    enabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ignored_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}, {
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}>;
+export type CollectionFlagsCfg = z.infer<typeof zCollectionFlagsCfg>;
+export interface CollectionFlags {
+    enabledSkills: Set<string> | null;
+    disabledSkills: Set<string> | null;
+    ignoredPaths: Set<string> | null;
+}
+export declare const zLocalCollectionSkillCfg: z.ZodObject<{
+    enabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ignored_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"local_collection">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "local_collection";
+    path: string;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}, {
+    type: "local_collection";
+    path: string;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}>;
+export type LocalCollectionSkillCfg = z.infer<typeof zLocalCollectionSkillCfg>;
+export declare const zGitHubSkillCfg: z.ZodObject<{
+    type: z.ZodLiteral<"github">;
+    repo: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github";
+    repo: string;
+    path?: string | undefined;
+}, {
+    type: "github";
+    repo: string;
+    path?: string | undefined;
+}>;
+export type GitHubSkillCfg = z.infer<typeof zGitHubSkillCfg>;
+export declare const zGitHubCollectionSkillCfg: z.ZodObject<{
+    enabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ignored_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"github_collection">;
+    repo: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github_collection";
+    repo: string;
+    path?: string | undefined;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}, {
+    type: "github_collection";
+    repo: string;
+    path?: string | undefined;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}>;
+export type GitHubCollectionSkillCfg = z.infer<typeof zGitHubCollectionSkillCfg>;
+export declare const zSkillCfg: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "local";
+    path: string;
+}, {
+    type: "local";
+    path: string;
+}>, z.ZodObject<{
+    enabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ignored_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"local_collection">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "local_collection";
+    path: string;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}, {
+    type: "local_collection";
+    path: string;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"github">;
+    repo: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github";
+    repo: string;
+    path?: string | undefined;
+}, {
+    type: "github";
+    repo: string;
+    path?: string | undefined;
+}>, z.ZodObject<{
+    enabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ignored_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"github_collection">;
+    repo: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github_collection";
+    repo: string;
+    path?: string | undefined;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}, {
+    type: "github_collection";
+    repo: string;
+    path?: string | undefined;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}>]>;
+export type SkillCfg = z.infer<typeof zSkillCfg>;
+export declare const zSkillCfgMap: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "local";
+    path: string;
+}, {
+    type: "local";
+    path: string;
+}>, z.ZodObject<{
+    enabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ignored_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"local_collection">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "local_collection";
+    path: string;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}, {
+    type: "local_collection";
+    path: string;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"github">;
+    repo: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github";
+    repo: string;
+    path?: string | undefined;
+}, {
+    type: "github";
+    repo: string;
+    path?: string | undefined;
+}>, z.ZodObject<{
+    enabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ignored_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"github_collection">;
+    repo: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github_collection";
+    repo: string;
+    path?: string | undefined;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}, {
+    type: "github_collection";
+    repo: string;
+    path?: string | undefined;
+    enabled_skills?: string[] | undefined;
+    disabled_skills?: string[] | undefined;
+    ignored_paths?: string[] | undefined;
+}>]>>;
+export type SkillCfgMap = z.infer<typeof zSkillCfgMap>;
+export declare const zSkillMatter: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    name: string;
+}, {
+    description: string;
+    name: string;
+}>;
+export type SkillMatter = z.infer<typeof zSkillMatter>;
+export declare const zLocalSkill: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+} & {
+    type: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "local";
+    description: string;
+    name: string;
+    path: string;
+}, {
+    type: "local";
+    description: string;
+    name: string;
+    path: string;
+}>;
+export type LocalSkill = z.infer<typeof zLocalSkill>;
+export declare const zGitHubSkill: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+} & {
+    type: z.ZodLiteral<"github">;
+    repo: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github";
+    description: string;
+    name: string;
+    repo: string;
+    path?: string | undefined;
+}, {
+    type: "github";
+    description: string;
+    name: string;
+    repo: string;
+    path?: string | undefined;
+}>;
+export type GitHubSkill = z.infer<typeof zGitHubSkill>;
+export declare const zSkill: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+} & {
+    type: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "local";
+    description: string;
+    name: string;
+    path: string;
+}, {
+    type: "local";
+    description: string;
+    name: string;
+    path: string;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+} & {
+    type: z.ZodLiteral<"github">;
+    repo: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github";
+    description: string;
+    name: string;
+    repo: string;
+    path?: string | undefined;
+}, {
+    type: "github";
+    description: string;
+    name: string;
+    repo: string;
+    path?: string | undefined;
+}>]>;
+export type Skill = z.infer<typeof zSkill>;
+export declare const zSkillMap: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+} & {
+    type: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "local";
+    description: string;
+    name: string;
+    path: string;
+}, {
+    type: "local";
+    description: string;
+    name: string;
+    path: string;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+} & {
+    type: z.ZodLiteral<"github">;
+    repo: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "github";
+    description: string;
+    name: string;
+    repo: string;
+    path?: string | undefined;
+}, {
+    type: "github";
+    description: string;
+    name: string;
+    repo: string;
+    path?: string | undefined;
+}>]>>;
+export type SkillMap = z.infer<typeof zSkillMap>;
+export interface SkillsFlags {
+    enabledSkills?: Set<string> | null;
+    disabledSkills?: Set<string> | null;
+}
+export interface ServerContextWithOctokit extends Record<string, unknown> {
+    octokit?: Octokit | null;
+}
+export declare const zViewSkillInputSchema: {
+    readonly skill_name: z.ZodString;
+    readonly path: z.ZodString;
+};
+export type ViewSkillInputSchema = InferSchema<typeof zViewSkillInputSchema>;
+export declare const zViewSkillOutputSchema: {
+    readonly content: z.ZodString;
+};
+export type ViewSkillOutputSchema = InferSchema<typeof zViewSkillOutputSchema>;
+export {};

package/dist/skills/types.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+export const zSkillType = z.enum([
+    'local',
+    'local_collection',
+    'github',
+    'github_collection',
+]);
+export const zLocalSkillCfg = z.object({
+    type: z.literal('local'),
+    path: z.string(),
+});
+const zCollectionFlagsCfg = z.object({
+    enabled_skills: z.array(z.string()).optional(),
+    disabled_skills: z.array(z.string()).optional(),
+    ignored_paths: z.array(z.string()).optional(),
+});
+export const zLocalCollectionSkillCfg = zCollectionFlagsCfg.extend({
+    type: z.literal('local_collection'),
+    path: z.string(),
+});
+export const zGitHubSkillCfg = z.object({
+    type: z.literal('github'),
+    repo: z.string(),
+    path: z.string().optional(),
+});
+export const zGitHubCollectionSkillCfg = zCollectionFlagsCfg.extend({
+    type: z.literal('github_collection'),
+    repo: z.string(),
+    path: z.string().optional(),
+});
+export const zSkillCfg = z.discriminatedUnion('type', [
+    zLocalSkillCfg,
+    zLocalCollectionSkillCfg,
+    zGitHubSkillCfg,
+    zGitHubCollectionSkillCfg,
+]);
+export const zSkillCfgMap = z.record(zSkillCfg);
+export const zSkillMatter = z.object({
+    name: z.string().trim().min(1),
+    description: z.string(),
+});
+export const zLocalSkill = zSkillMatter.extend(zLocalSkillCfg.shape);
+export const zGitHubSkill = zSkillMatter.extend(zGitHubSkillCfg.shape);
+export const zSkill = z.discriminatedUnion('type', [zLocalSkill, zGitHubSkill]);
+export const zSkillMap = z.record(zSkill);
+export const zViewSkillInputSchema = {
+    skill_name: z
+        .string()
+        .describe('The name of the skill to browse, or `.` to list all available skills.'),
+    path: z.string().describe(`
+A relative path to a file or directory within the skill to view.
+If empty, will view the \`SKILL.md\` file by default.
+Use \`.\` to list the root directory of the skill.
+`.trim()),
+};
+export const zViewSkillOutputSchema = {
+    content: z.string().describe('The content of the file or directory listing.'),
+};

package/dist/skills/utils.d.ts

@@ -0,0 +1,33 @@
+import type { Octokit } from '@octokit/rest';
+import { type McpFeatureFlags } from '@tigerdata/mcp-boilerplate';
+import { type CollectionFlags, type CollectionFlagsCfg, type Skill, type SkillCfgMap, type SkillMatter, type SkillsFlags } from './types.js';
+export declare const getSkillConfig: (configFilePath?: string) => Promise<SkillCfgMap>;
+export declare const parseSkillFile: (fileContent: string) => Promise<{
+    matter: SkillMatter;
+    content: string;
+}>;
+export declare const loadSkills: ({ octokit, force, }?: {
+    octokit?: Octokit | null;
+    force?: boolean;
+}) => Promise<Map<string, Skill>>;
+export declare const resolveSkill: ({ name, octokit, flags, force, }: {
+    name: string;
+    octokit?: Octokit | null;
+    flags?: SkillsFlags;
+    force?: boolean;
+}) => Promise<Skill | null>;
+export declare const skillVisible: (name: string, flags: SkillsFlags) => boolean;
+export declare const listSkills: ({ octokit, flags, force, }?: {
+    octokit?: Octokit | null;
+    flags?: SkillsFlags;
+    force?: boolean;
+}) => Promise<string>;
+export declare const viewSkillContent: ({ octokit, flags, name, path: passedPath, }: {
+    octokit?: Octokit | null;
+    flags?: SkillsFlags;
+    name: string;
+    path?: string;
+}) => Promise<string>;
+export declare const skillsDescription: string;
+export declare const parseSkillsFlags: (query: McpFeatureFlags["query"]) => SkillsFlags;
+export declare const parseCollectionFlags: (cfg: CollectionFlagsCfg) => CollectionFlags;

package/dist/skills/utils.js

@@ -0,0 +1,404 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import Path from 'node:path';
+import { log, } from '@tigerdata/mcp-boilerplate';
+import { encode } from '@toon-format/toon';
+import matter from 'gray-matter';
+import YAML from 'yaml';
+import { zSkillCfgMap, zSkillMatter, } from './types.js';
+const TTL = process.env.SKILLS_TTL
+    ? parseInt(process.env.SKILLS_TTL, 10)
+    : 5 * 60 * 1000;
+let lastFetchCfg = 0;
+let skillCfgMap = null;
+export const getSkillConfig = async (configFilePath = process.env.SKILLS_FILE || './skills.yaml') => {
+    if (skillCfgMap && Date.now() - lastFetchCfg < TTL)
+        return skillCfgMap;
+    const data = await readFile(configFilePath, 'utf-8');
+    skillCfgMap = zSkillCfgMap.parse(YAML.parse(data));
+    lastFetchCfg = Date.now();
+    return skillCfgMap;
+};
+export const parseSkillFile = async (fileContent) => {
+    const { data, content } = matter(fileContent);
+    const skillMatter = zSkillMatter.parse(data);
+    if (!/^[a-zA-Z0-9-_]+$/.test(skillMatter.name)) {
+        const normalized = skillMatter.name
+            .toLowerCase()
+            .replace(/\s+/g, '-')
+            .replace(/[^a-z0-9-_]/g, '_')
+            .replace(/-[-_]+/g, '-')
+            .replace(/_[_-]+/g, '_')
+            .replace(/(^[-_]+)|([-_]+$)/g, '');
+        log.warn(`Skill name "${skillMatter.name}" contains invalid characters. Normalizing to "${normalized}".`);
+        skillMatter.name = normalized;
+    }
+    return {
+        matter: skillMatter,
+        content,
+    };
+};
+// skill name/path -> content
+const skillContentCache = new Map();
+let lastFetchSkillMap = 0;
+let skillMap = null;
+export const loadSkills = async ({ octokit, force = false, } = {}) => {
+    if (skillMap && !force && Date.now() - lastFetchSkillMap < TTL)
+        return skillMap;
+    skillMap = doLoadSkills(octokit).then((result) => {
+        lastFetchSkillMap = Date.now();
+        return result;
+    }, (err) => {
+        log.error('Failed to load skills, returning empty skill map', err);
+        skillMap = null;
+        return new Map();
+    });
+    return skillMap;
+};
+const doLoadSkills = async (octokit) => {
+    const skillCfgs = await getSkillConfig();
+    skillContentCache.clear();
+    const skills = new Map();
+    const alreadyExists = (name, path, description) => {
+        const existing = skills.get(name);
+        if (existing) {
+            log.warn(`Skill with name "${name}" already loaded from path "${existing.path}". Skipping duplicate at path "${path}".`, { existing, duplicate: { path, name, description } });
+            return true;
+        }
+        return false;
+    };
+    const shouldIgnorePath = (path, flags) => {
+        if (flags?.ignoredPaths?.has(path)) {
+            log.debug(`Ignoring path "${path}" in ignoredPaths`);
+            return true;
+        }
+        return false;
+    };
+    const shouldIgnoreSkill = (name, flags) => {
+        if (flags?.enabledSkills && !flags.enabledSkills.has(name)) {
+            log.debug(`Ignoring skill "${name}" not in enabledSkills`);
+            return true;
+        }
+        if (flags?.disabledSkills?.has(name)) {
+            log.debug(`Ignoring skill "${name}" in disabledSkills`);
+            return true;
+        }
+        return false;
+    };
+    const loadLocalPath = async (path, flags) => {
+        if (shouldIgnorePath(path, flags))
+            return;
+        const skillPath = `${path}/SKILL.md`;
+        try {
+            const fileContent = await readFile(skillPath, 'utf-8');
+            const { matter: { name, description }, content, } = await parseSkillFile(fileContent);
+            if (shouldIgnoreSkill(name, flags))
+                return;
+            if (alreadyExists(name, path, description))
+                return;
+            skills.set(name, {
+                type: 'local',
+                path,
+                name,
+                description,
+            });
+            skillContentCache.set(`${name}/SKILL.md`, content);
+        }
+        catch (err) {
+            log.error(`Failed to load skill at path: ${skillPath}`, err);
+        }
+    };
+    const loadGitHubPath = async (owner, repo, path, flags) => {
+        if (shouldIgnorePath(path, flags))
+            return;
+        const skillPath = `${path}/SKILL.md`;
+        if (!octokit) {
+            log.error(`Octokit instance is required to load GitHub skills: ${owner}/${repo}/${skillPath}`);
+            return;
+        }
+        try {
+            const skillFileResponse = await octokit.repos.getContent({
+                owner,
+                repo,
+                path: skillPath,
+            });
+            if (Array.isArray(skillFileResponse.data) ||
+                skillFileResponse.data.type !== 'file') {
+                log.error(`Expected SKILL.md to be a file`, null, {
+                    owner,
+                    repo,
+                    path: skillPath,
+                });
+                return;
+            }
+            const fileContent = Buffer.from(skillFileResponse.data.content, 'base64').toString('utf-8');
+            const { matter: { name, description }, content, } = await parseSkillFile(fileContent);
+            if (shouldIgnoreSkill(name, flags))
+                return;
+            if (alreadyExists(name, path, description))
+                return;
+            skills.set(name, {
+                type: 'github',
+                repo: `${owner}/${repo}`,
+                path,
+                name,
+                description,
+            });
+            skillContentCache.set(`${name}/SKILL.md`, content);
+        }
+        catch (err) {
+            log.error(`Failed to load skill at GitHub path: ${owner}/${repo}/${skillPath}\n${err.message}`);
+        }
+    };
+    const promises = [];
+    await Promise.all(Object.entries(skillCfgs).map(async ([name, cfg]) => {
+        try {
+            switch (cfg.type) {
+                case 'local': {
+                    promises.push(loadLocalPath(cfg.path));
+                    break;
+                }
+                case 'local_collection': {
+                    const dirEntries = await readdir(cfg.path, {
+                        withFileTypes: true,
+                    });
+                    const flags = parseCollectionFlags(cfg);
+                    for (const entry of dirEntries) {
+                        if (entry.isFile())
+                            continue;
+                        if (!entry.isDirectory()) {
+                            log.warn(`Skipping non-directory entry in local_collection`, {
+                                path: `${cfg.path}/${entry.name}`,
+                            });
+                            continue;
+                        }
+                        promises.push(loadLocalPath(`${cfg.path}/${entry.name}`, flags));
+                    }
+                    break;
+                }
+                case 'github': {
+                    const [owner, repo] = cfg.repo.split('/');
+                    if (!owner || !repo) {
+                        log.error(`Invalid GitHub repo format in skill config: ${cfg.repo}`, null, { name, repo: cfg.repo });
+                        break;
+                    }
+                    promises.push(loadGitHubPath(owner, repo, cfg.path || '.'));
+                    break;
+                }
+                case 'github_collection': {
+                    const [owner, repo] = cfg.repo.split('/');
+                    if (!owner || !repo) {
+                        log.error(`Invalid GitHub repo format in skill config: ${cfg.repo}`, null, { name, repo: cfg.repo });
+                        break;
+                    }
+                    if (!octokit) {
+                        log.error(`Octokit instance is required to load GitHub collection skills: ${cfg.repo}`);
+                        break;
+                    }
+                    const rootPath = cfg.path
+                        ? cfg.path.replace(/(^\.?\/+)|(^\.$)|(\/\.$)/g, '')
+                        : '';
+                    const dirResponse = await octokit.repos.getContent({
+                        owner,
+                        repo,
+                        path: rootPath,
+                    });
+                    if (!Array.isArray(dirResponse.data)) {
+                        log.error(`Expected github_collection repo path to be a directory`, null, { name, owner, repo, path: cfg.path || '.' });
+                        break;
+                    }
+                    const flags = parseCollectionFlags(cfg);
+                    for (const entry of dirResponse.data) {
+                        if (entry.type === 'file')
+                            continue;
+                        if (entry.type !== 'dir') {
+                            log.warn(`Skipping non-directory entry in github_collection`, {
+                                path: `${cfg.repo}/${entry.path}`,
+                                type: entry.type,
+                            });
+                            continue;
+                        }
+                        promises.push(loadGitHubPath(owner, repo, entry.path, flags));
+                    }
+                    break;
+                }
+                default: {
+                    // @ts-expect-error exhaustive check
+                    throw new Error(`Unhandled skill config type: ${cfg.type}`);
+                }
+            }
+        }
+        catch (err) {
+            log.error(`Failed to load skill config "${name}"`, err);
+        }
+    }));
+    await Promise.all(promises);
+    // Sort skills by name
+    return new Map(Array.from(skills.entries()).sort((a, b) => a[0].localeCompare(b[0])));
+};
+export const resolveSkill = async ({ name, octokit, flags = {}, force = false, }) => {
+    if (!skillVisible(name, flags)) {
+        return null;
+    }
+    const skills = await loadSkills({ octokit, force });
+    return skills.get(name) || null;
+};
+export const skillVisible = (name, flags) => {
+    if (flags.enabledSkills && !flags.enabledSkills.has(name)) {
+        return false;
+    }
+    if (flags.disabledSkills?.has(name)) {
+        return false;
+    }
+    return true;
+};
+export const listSkills = async ({ octokit, flags = {}, force = false, } = {}) => {
+    const skills = await loadSkills({ octokit, force });
+    return `<available_skills>
+${encode([...skills.values()]
+        .filter((s) => skillVisible(s.name, flags))
+        .map((s) => ({
+        name: s.name,
+        description: s.description,
+    })), { delimiter: '\t' })}
+</available_skills>`;
+};
+export const viewSkillContent = async ({ octokit, flags = {}, name, path: passedPath, }) => {
+    const skill = await resolveSkill({ octokit, flags, name });
+    if (!skill) {
+        throw new Error(`Skill not found: ${name}`);
+    }
+    const targetPath = passedPath || 'SKILL.md';
+    const cacheKey = `${name}/${normalizeSkillPath(targetPath)}`;
+    const cached = skillContentCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const content = await getSkillContent({ octokit, skill, path: targetPath });
+    skillContentCache.set(cacheKey, content);
+    return content;
+};
+const normalizeSkillPath = (path) => {
+    const normalizedPath = Path.posix
+        .normalize(
+    // treat \ as /
+    path.replace(/\\/g, '/'))
+        // strip leading ./ or /
+        .replace(/^(\.?\/)+/, '');
+    if (normalizedPath.split('/').some((s) => s === '..') ||
+        normalizedPath.includes('\0')) {
+        throw new Error(`Invalid path: ${path}`);
+    }
+    return normalizedPath;
+};
+const getSkillContent = async ({ skill, path: targetPath, octokit, }) => {
+    const normalizedPath = normalizeSkillPath(targetPath);
+    switch (skill.type) {
+        case 'local': {
+            const root = Path.resolve(skill.path);
+            const target = Path.resolve(Path.join(root, normalizedPath));
+            if (targetPath !== '.' && !target.startsWith(root)) {
+                throw new Error(`Invalid path: ${targetPath}`);
+            }
+            const s = await stat(target).catch(() => {
+                throw new Error(`Path not found: ${targetPath}`);
+            });
+            if (s.isDirectory()) {
+                const entries = await readdir(target, {
+                    withFileTypes: true,
+                });
+                const listing = entries
+                    .map((entry) => {
+                    return `${entry.isDirectory() ? '📁' : '📄'} ${entry.name}`;
+                })
+                    .join('\n');
+                return `Directory listing for ${skill.name}/${normalizedPath}:\n${listing}`;
+            }
+            else if (s.isFile()) {
+                return await readFile(target, 'utf-8');
+            }
+            else {
+                throw new Error(`Unsupported file type at path: ${target}`);
+            }
+        }
+        case 'github': {
+            const [owner, repo] = skill.repo.split('/');
+            if (!owner || !repo) {
+                throw new Error(`Invalid GitHub repo format in skill: ${skill.repo}`);
+            }
+            const path = `${skill.path || '.'}/${normalizedPath}`
+                .replace(/\/+/g, '/')
+                .replace(/(^\.?\/+)|(^\.$)|(\/\.$)/g, '');
+            if (!octokit) {
+                throw new Error(`Octokit instance is required to load GitHub skill content: ${owner}/${repo}/${path}`);
+            }
+            const response = await octokit.repos.getContent({
+                owner,
+                repo,
+                path,
+            });
+            if (Array.isArray(response.data)) {
+                // Directory listing
+                const listing = response.data
+                    .map((entry) => {
+                    return `${entry.type === 'dir' ? '📁' : '📄'} ${entry.name}`;
+                })
+                    .join('\n');
+                return `Directory listing for ${skill.name}/${normalizedPath}:\n${listing}`;
+            }
+            if (response.data.type !== 'file') {
+                throw new Error(`Unsupported content type: ${response.data.type}`);
+            }
+            return Buffer.from(response.data.content, 'base64').toString('utf-8');
+        }
+        default: {
+            // @ts-expect-error exhaustive check
+            throw new Error(`Unhandled skill type: ${skill.type}`);
+        }
+    }
+};
+export const skillsDescription = `
+# Skills
+
+This tool provides access to domain-specific skills - structured knowledge and procedures for specialized tasks.
+
+## How to Use Skills
+
+1. **Discover**: If you have not been provided the list of skills, fetch them by invoking this tool with \`name: "."\`
+2. **Read**: Access a skill by reading its SKILL.md file: \`name: "skill-name", path: "SKILL.md"\`
+3. **Explore**: Navigate within the skill directory to find additional resources, examples, or templates.
+   The SKILL.md file and other documents may contain relative links to guide you.
+   You can list the content of directories by specifying the directory path, relative to the skill root.
+4. **Apply**: Follow the procedures and reference the knowledge in the skill to complete your task
+
+## Skill Structure
+
+Each skill contains:
+- **SKILL.md**: Main documentation (always start here)
+- **REFERENCE.md**: Quick reference card (optional)
+- Additional files: Examples, templates, scripts
+
+## When to Use Skills
+
+- Read relevant skills proactively when you identify a task that matches a skill's domain
+- Skills are meant to augment your knowledge, not replace your reasoning
+- Apply skill guidance while adapting to the specific user request
+- Skills use progressive disclosure - start with high-level guidance and drill down only as needed
+- Skills may also refer to tools or resources external to the skill itself
+- Use other tools to execute any code or scripts provided by the skill
+`.trim();
+const toSet = (flag) => flag
+    ? Array.isArray(flag)
+        ? new Set(flag)
+        : typeof flag === 'string'
+            ? new Set(flag.split(',').map((s) => s.trim()))
+            : null
+    : null;
+export const parseSkillsFlags = (query) => ({
+    enabledSkills: toSet(query?.enabled_skills),
+    disabledSkills: toSet(query?.disabled_skills),
+});
+export const parseCollectionFlags = (cfg) => ({
+    enabledSkills: toSet(cfg.enabled_skills),
+    disabledSkills: toSet(cfg.disabled_skills),
+    ignoredPaths: toSet(cfg.ignored_paths),
+});

package/dist/stdio.js

@@ -6,7 +6,7 @@ export const stdioServerFactory = async ({ name, version, context, apiFactories,
     try {
         console.error('Starting default (STDIO) server...');
         const transport = new StdioServerTransport();
-        const { server } = mcpServerFactory({
+        const { server } = await mcpServerFactory({
             name,
             version,
             context,

package/dist/types.d.ts

@@ -18,7 +18,7 @@ export interface BaseApiDefinition {
     fn(args: Record<string, unknown>): Promise<Record<string, unknown>>;
     pickResult?(result: Record<string, unknown>): unknown;
 }
-export type BaseApiFactory<Context extends Record<string, unknown>> = (ctx: Context, featureFlags: McpFeatureFlags) => BaseApiDefinition;
+export type BaseApiFactory<Context extends Record<string, unknown>> = (ctx: Context, featureFlags: McpFeatureFlags) => BaseApiDefinition | Promise<BaseApiDefinition>;
 export type BasePromptConfig = {
     title?: string;
     description?: string;
@@ -30,7 +30,7 @@ export interface BasePromptDefinition {
     disabled?: boolean;
     fn(args: Record<string, unknown>): Promise<GetPromptResult>;
 }
-export type BasePromptFactory<Context extends Record<string, unknown>> = (ctx: Context, featureFlags: McpFeatureFlags) => BasePromptDefinition;
+export type BasePromptFactory<Context extends Record<string, unknown>> = (ctx: Context, featureFlags: McpFeatureFlags) => BasePromptDefinition | Promise<BasePromptDefinition>;
 export type ToolConfig<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape> = {
     title?: string;
     description?: string;
@@ -43,7 +43,7 @@ export interface ApiDefinition<InputArgs extends ZodRawShape, OutputArgs extends
     fn(args: z.objectOutputType<InputArgs, ZodTypeAny>): Promise<z.objectOutputType<OutputArgs, ZodTypeAny>>;
     pickResult?(result: z.objectOutputType<OutputArgs, ZodTypeAny>): SimplifiedOutputArgs;
 }
-export type ApiFactory<Context extends Record<string, unknown>, Input extends ZodRawShape, Output extends ZodRawShape, RestOutput = Output> = (ctx: Context, featureFlags: McpFeatureFlags) => ApiDefinition<Input, Output, RestOutput>;
+export type ApiFactory<Context extends Record<string, unknown>, Input extends ZodRawShape, Output extends ZodRawShape, RestOutput = Output> = (ctx: Context, featureFlags: McpFeatureFlags) => ApiDefinition<Input, Output, RestOutput> | Promise<ApiDefinition<Input, Output, RestOutput>>;
 export type RouterFactoryResult = [Router, () => void | Promise<void>];
 export type PromptConfig<InputArgs extends ZodRawShape> = {
     title?: string;
@@ -76,7 +76,7 @@ export interface StaticResourceDefinition {
     read: ReadResourceCallback;
 }
 export type ResourceDefinition = TemplatedResourceDefinition | StaticResourceDefinition;
-export type ResourceFactory<Context extends Record<string, unknown>> = (ctx: Context, featureFlags: McpFeatureFlags) => ResourceDefinition;
+export type ResourceFactory<Context extends Record<string, unknown>> = (ctx: Context, featureFlags: McpFeatureFlags) => ResourceDefinition | Promise<ResourceDefinition>;
 export interface ParsedQs {
     [key: string]: undefined | string | ParsedQs | (string | ParsedQs)[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tigerdata/mcp-boilerplate",
-  "version": "0.9.2",
+  "version": "1.0.0",
   "description": "MCP boilerplate code for Node.js",
   "license": "Apache-2.0",
   "author": "TigerData",
@@ -24,6 +24,10 @@
     "./instrumentation": {
       "import": "./dist/instrumentation.js",
       "types": "./dist/instrumentation.d.ts"
+    },
+    "./skills": {
+      "import": "./dist/skills/index.js",
+      "types": "./dist/skills/index.d.ts"
     }
   },
   "files": [
@@ -36,7 +40,7 @@
     "lint": "./bun x @biomejs/biome check"
   },
   "dependencies": {
-    "@mcp-use/inspector": "^0.13.2",
+    "@mcp-use/inspector": "^0.14.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.67.3",
@@ -46,17 +50,21 @@
     "@opentelemetry/sdk-node": "^0.208.0",
     "@opentelemetry/sdk-trace-node": "^2.2.0",
     "@opentelemetry/semantic-conventions": "^1.38.0",
+    "@toon-format/toon": "^2.1.0",
     "express": "^5.2.1",
+    "gray-matter": "^4.0.3",
     "raw-body": "^3.0.2",
+    "yaml": "^2.8.2",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.10",
+    "@biomejs/biome": "^2.3.11",
+    "@octokit/rest": "^22.0.1",
     "@types/bun": "^1.3.5",
     "@types/express": "^5.0.6",
     "@types/node": "^22.19.3",
-    "@typescript-eslint/typescript-estree": "^8.50.0",
-    "ai": "^5.0.115",
+    "@typescript-eslint/typescript-estree": "^8.52.0",
+    "ai": "^5.0.118",
     "eslint": "^9.39.2",
     "typescript": "^5.9.3"
   },