@tigerdata/mcp-boilerplate 1.3.0 → 1.3.2

package/dist/skills/tool.js

@@ -1,5 +1,6 @@
+import { log } from '../logger.js';
 import { zViewSkillInputSchema, zViewSkillOutputSchema, } from './types.js';
-import { listSkills, parseSkillsFlags, skillsDescription, viewSkillContent, } from './utils.js';
+import { getAvailableSkillNames, InvalidPathError, listSkills, PathNotFoundError, parseSkillsFlags, SkillNotFoundError, SkillsApiError, skillsDescription, viewSkillContent, } from './utils.js';
 export const createViewSkillToolFactory = (options = {}) => async (ctx, mcpFlags) => {
     const { octokit } = ctx;
     const flags = parseSkillsFlags(mcpFlags.query);
@@ -20,7 +21,6 @@ export const createViewSkillToolFactory = (options = {}) => async (ctx, mcpFlags
             annotations: {
                 readOnlyHint: true,
                 idempotentHint: true,
-                openWorldHint: true,
             },
         },
         fn: async ({ skill_name: name, path, }) => {
@@ -29,14 +29,52 @@ export const createViewSkillToolFactory = (options = {}) => async (ctx, mcpFlags
                     content: await listSkills({ octokit, flags }),
                 };
             }
-            return {
-                content: await viewSkillContent({
-                    octokit,
-                    flags,
-                    name,
-                    path,
-                }),
-            };
+            try {
+                return {
+                    content: await viewSkillContent({
+                        octokit,
+                        flags,
+                        name,
+                        path,
+                    }),
+                };
+            }
+            catch (err) {
+                if (!(err instanceof SkillsApiError)) {
+                    throw err;
+                }
+                if (err instanceof SkillNotFoundError) {
+                    log.warn(`Skill not found: ${err.skillName}`, {
+                        error: err.constructor.name,
+                        skill: err.skillName,
+                    });
+                    const available = await getAvailableSkillNames({ octokit, flags });
+                    return {
+                        content: `Skill not found: ${err.skillName}. Available skills: ${available}. Use one of these names.`,
+                    };
+                }
+                if (err instanceof PathNotFoundError) {
+                    log.warn(`Path not found: ${err.path} in skill ${err.skill}`, {
+                        error: err.constructor.name,
+                        skill: err.skill,
+                        path: err.path,
+                    });
+                    return {
+                        content: `Path not found: ${err.path}. Contents of skill "${err.skill}":\n${err.listing}\n\nUse path "SKILL.md" to read the main skill document.`,
+                    };
+                }
+                if (err instanceof InvalidPathError) {
+                    log.warn(`Invalid path: ${err.path}`, {
+                        error: err.constructor.name,
+                        path: err.path,
+                    });
+                    const available = await getAvailableSkillNames({ octokit, flags });
+                    return {
+                        content: `${err.message} Available skills: ${available}. Use name "." to list skills; use path "." to list a skill's contents.`,
+                    };
+                }
+                throw err;
+            }
         },
     };
 };

package/dist/skills/tool.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/skills/tool.spec.js

@@ -0,0 +1,86 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it, spyOn, } from 'bun:test';
+import Path from 'node:path';
+import { log } from '../logger.js';
+import { createViewSkillToolFactory } from './tool.js';
+process.env.SKILLS_FILE = Path.resolve(import.meta.dir, '__fixtures__', 'skills.yaml');
+describe('createViewSkillToolFactory', () => {
+    let warnSpy;
+    let fn;
+    beforeAll(async () => {
+        const factory = createViewSkillToolFactory();
+        const tool = await factory({ octokit: null }, { query: {} });
+        fn = tool.fn;
+        warnSpy = spyOn(log, 'warn');
+    });
+    beforeEach(() => {
+        warnSpy.mockClear();
+    });
+    afterAll(() => {
+        warnSpy.mockRestore();
+    });
+    it('lists skills when skill_name is "."', async () => {
+        const result = await fn({ skill_name: '.', path: '' });
+        expect(result.content).toContain('<available_skills>');
+        expect(result.content).toContain('first-skill');
+        expect(result.content).toContain('second-skill');
+    });
+    it('lists skills when skill_name is empty', async () => {
+        const result = await fn({ skill_name: '', path: '' });
+        expect(result.content).toContain('<available_skills>');
+        expect(result.content).toContain('first-skill');
+        expect(result.content).toContain('second-skill');
+    });
+    it('returns skill content for valid name and path', async () => {
+        const result = await fn({ skill_name: 'first-skill', path: 'SKILL.md' });
+        expect(result.content).toBe('First skill content\n');
+    });
+    it('returns recovery string with available skills for nonexistent skill', async () => {
+        const result = await fn({ skill_name: 'nonexistent', path: 'SKILL.md' });
+        expect(result.content).toContain('Skill not found: nonexistent');
+        expect(result.content).toContain('first-skill');
+        expect(result.content).toContain('second-skill');
+        expect(warnSpy).toHaveBeenCalledWith('Skill not found: nonexistent', expect.objectContaining({
+            error: 'SkillNotFoundError',
+            skill: 'nonexistent',
+        }));
+    });
+    it('returns recovery string with directory listing for nonexistent path', async () => {
+        const result = await fn({
+            skill_name: 'first-skill',
+            path: 'does-not-exist',
+        });
+        expect(result.content).toContain('Path not found: does-not-exist');
+        expect(result.content).toContain('first-skill');
+        expect(result.content).toContain('SKILL.md');
+        expect(warnSpy).toHaveBeenCalledWith('Path not found: does-not-exist in skill first-skill', expect.objectContaining({
+            error: 'PathNotFoundError',
+            skill: 'first-skill',
+            path: 'does-not-exist',
+        }));
+    });
+    it('returns recovery string for directory traversal path', async () => {
+        const result = await fn({
+            skill_name: 'first-skill',
+            path: '../../etc/passwd',
+        });
+        expect(result.content).toContain('Invalid path: ../../etc/passwd.');
+        expect(result.content).toContain('first-skill');
+        expect(result.content).toContain('second-skill');
+        expect(warnSpy).toHaveBeenCalledWith('Invalid path: ../../etc/passwd', expect.objectContaining({
+            error: 'InvalidPathError',
+            path: '../../etc/passwd',
+        }));
+    });
+    it('returns recovery string for null byte path', async () => {
+        const result = await fn({
+            skill_name: 'first-skill',
+            path: 'SKILL.md\x00.txt',
+        });
+        expect(result.content).toContain('Invalid path: SKILL.md\x00.txt.');
+        expect(result.content).toContain('first-skill');
+        expect(warnSpy).toHaveBeenCalledWith('Invalid path: SKILL.md\x00.txt', expect.objectContaining({
+            error: 'InvalidPathError',
+            path: 'SKILL.md\x00.txt',
+        }));
+    });
+});

package/dist/skills/utils.d.ts

@@ -17,6 +17,28 @@ export declare const resolveSkill: ({ name, octokit, flags, force, }: {
     force?: boolean;
 }) => Promise<Skill | null>;
 export declare const skillVisible: (name: string, flags: SkillsFlags) => boolean;
+/** Base class for skills API errors; catch in tool.ts to format recovery messages. */
+export declare class SkillsApiError extends Error {
+}
+export declare class SkillNotFoundError extends SkillsApiError {
+    readonly skillName: string;
+    constructor(skillName: string);
+}
+export declare class PathNotFoundError extends SkillsApiError {
+    readonly skill: string;
+    readonly path: string;
+    readonly listing: string;
+    constructor(skill: string, path: string, listing: string);
+}
+export declare class InvalidPathError extends SkillsApiError {
+    readonly path: string;
+    constructor(path: string);
+}
+/** Comma-separated visible skill names for error/recovery messages. */
+export declare const getAvailableSkillNames: ({ octokit, flags, }: {
+    octokit?: Octokit | null;
+    flags?: SkillsFlags;
+}) => Promise<string>;
 export declare const listSkills: ({ octokit, flags, force, }?: {
     octokit?: Octokit | null;
     flags?: SkillsFlags;

package/dist/skills/utils.js

@@ -251,6 +251,48 @@ export const skillVisible = (name, flags) => {
     }
     return true;
 };
+/** Base class for skills API errors; catch in tool.ts to format recovery messages. */
+export class SkillsApiError extends Error {
+}
+export class SkillNotFoundError extends SkillsApiError {
+    skillName;
+    constructor(skillName) {
+        super(`Skill not found: ${skillName}.`);
+        this.skillName = skillName;
+    }
+}
+export class PathNotFoundError extends SkillsApiError {
+    skill;
+    path;
+    listing;
+    constructor(skill, path, listing) {
+        super(`Path not found: ${path}.`);
+        this.skill = skill;
+        this.path = path;
+        this.listing = listing;
+    }
+}
+export class InvalidPathError extends SkillsApiError {
+    path;
+    constructor(path) {
+        super(`Invalid path: ${path}.`);
+        this.path = path;
+    }
+}
+/** Comma-separated visible skill names for error/recovery messages. */
+export const getAvailableSkillNames = async ({ octokit, flags = {}, }) => {
+    try {
+        const skills = await loadSkills({ octokit, force: false });
+        const names = [...skills.values()]
+            .filter((s) => skillVisible(s.name, flags))
+            .map((s) => s.name)
+            .sort();
+        return names.length > 0 ? names.join(', ') : '(none)';
+    }
+    catch (err) {
+        throw new Error(`getAvailableSkillNames failed: ${err.message}`);
+    }
+};
 export const listSkills = async ({ octokit, flags = {}, force = false, } = {}) => {
     const skills = await loadSkills({ octokit, force });
     return `<available_skills>
@@ -265,7 +307,7 @@ ${encode([...skills.values()]
 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}`);
+        throw new SkillNotFoundError(name);
     }
     const targetPath = passedPath || 'SKILL.md';
     const cacheKey = `${name}/${normalizeSkillPath(targetPath)}`;
@@ -286,7 +328,7 @@ const normalizeSkillPath = (path) => {
         .replace(/^(\.?\/)+/, '');
     if (normalizedPath.split('/').some((s) => s === '..') ||
         normalizedPath.includes('\0')) {
-        throw new Error(`Invalid path: ${path}`);
+        throw new InvalidPathError(path);
     }
     return normalizedPath;
 };
@@ -297,12 +339,20 @@ const getSkillContent = async ({ skill, path: targetPath, octokit, }) => {
             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}`);
+                throw new InvalidPathError(targetPath);
             }
-            const s = await stat(target).catch(() => {
-                throw new Error(`Path not found: ${targetPath}`);
-            });
-            if (s.isDirectory()) {
+            let stats;
+            try {
+                stats = await stat(target);
+            }
+            catch {
+                const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+                const listing = entries
+                    .map((entry) => `${entry.isDirectory() ? '📁' : '📄'} ${entry.name}`)
+                    .join('\n');
+                throw new PathNotFoundError(skill.name, targetPath, listing || '(empty)');
+            }
+            if (stats.isDirectory()) {
                 const entries = await readdir(target, {
                     withFileTypes: true,
                 });
@@ -313,7 +363,7 @@ const getSkillContent = async ({ skill, path: targetPath, octokit, }) => {
                     .join('\n');
                 return `Directory listing for ${skill.name}/${normalizedPath}:\n${listing}`;
             }
-            else if (s.isFile()) {
+            else if (stats.isFile()) {
                 return await readFile(target, 'utf-8');
             }
             else {
@@ -363,11 +413,9 @@ This tool provides access to domain-specific skills - structured knowledge and p
 
 ## 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.
+1. **Discover**: If you have not been provided the list of skills, fetch them by invoking this tool with \`name: "."\`. Use only skill names that appear in that list.
+2. **Read**: Access a skill by reading its SKILL.md file: \`name: "skill-name", path: "SKILL.md"\`. Use a skill name from the list (step 1); do not guess names from context or topic words.
+3. **Explore**: Navigate within the skill directory to find additional resources, examples, or templates. You can list the contents of the directory by using \`path: "."\` (relative to the skill root); use only a path that appears in that listing—do not guess or infer path names from skill descriptions or topic words (e.g. "indexing strategies" in text is not a path). SKILL.md and other documents may contain relative links to guide you.
 4. **Apply**: Follow the procedures and reference the knowledge in the skill to complete your task
 
 ## Skill Structure

package/dist/skills/utils.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/skills/utils.spec.js

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'bun:test';
+import Path from 'node:path';
+import { getAvailableSkillNames, InvalidPathError, listSkills, PathNotFoundError, SkillNotFoundError, viewSkillContent, } from './utils.js';
+process.env.SKILLS_FILE = Path.resolve(import.meta.dir, '__fixtures__', 'skills.yaml');
+describe('Skills API', () => {
+    describe('getAvailableSkillNames', () => {
+        it('returns a comma-separated list of visible skill names in alphabetical order when skills are loaded', async () => {
+            const names = await getAvailableSkillNames({});
+            expect(names).toBe('first-skill, second-skill');
+        });
+        it('returns "(none)" when flags filter out every skill (e.g. enabledSkills does not match any)', async () => {
+            const names = await getAvailableSkillNames({
+                flags: {
+                    enabledSkills: new Set(['does-not-exist']),
+                    disabledSkills: null,
+                },
+            });
+            expect(names).toBe('(none)');
+        });
+        it('throws an error with message prefixed by "getAvailableSkillNames failed:" when something in the function fails', async () => {
+            await expect(getAvailableSkillNames({
+                flags: {
+                    enabledSkills: {
+                        has: () => {
+                            throw new Error('enabledSkills filter threw');
+                        },
+                    },
+                    disabledSkills: null,
+                },
+            })).rejects.toThrow('getAvailableSkillNames failed: enabledSkills filter threw');
+        });
+    });
+    describe('listSkills and viewSkillContent (skills-api-test-plan)', () => {
+        it('list all skills: returns a string containing available_skills and all loaded skill names', async () => {
+            const result = await listSkills({});
+            expect(result).toContain('<available_skills>');
+            expect(result).toContain('first-skill');
+            expect(result).toContain('second-skill');
+            const inner = result
+                .split('<available_skills>')[1]
+                .split('</available_skills>')[0];
+            const lines = inner.trim().split('\n');
+            expect(lines).toHaveLength(3);
+        });
+        it('read valid skill: returns the content of the skill SKILL.md when name and path are valid', async () => {
+            const result = await viewSkillContent({
+                name: 'first-skill',
+                path: 'SKILL.md',
+            });
+            expect(result).toBe('First skill content\n');
+        });
+        it('skill not found: viewSkillContent throws SkillNotFoundError', async () => {
+            try {
+                await viewSkillContent({ name: 'nonexistent-skill', path: 'SKILL.md' });
+                throw new Error('Expected SkillNotFoundError to be thrown');
+            }
+            catch (err) {
+                expect(err).toBeInstanceOf(SkillNotFoundError);
+                expect(err.skillName).toBe('nonexistent-skill');
+            }
+        });
+        it('skill not found with another name: throws SkillNotFoundError', async () => {
+            try {
+                await viewSkillContent({
+                    name: 'another-missing-skill',
+                    path: 'SKILL.md',
+                });
+                throw new Error('Expected SkillNotFoundError to be thrown');
+            }
+            catch (err) {
+                expect(err).toBeInstanceOf(SkillNotFoundError);
+                expect(err.skillName).toBe('another-missing-skill');
+            }
+        });
+        it('path not found inside valid skill: viewSkillContent throws PathNotFoundError', async () => {
+            try {
+                await viewSkillContent({
+                    name: 'first-skill',
+                    path: 'indexing-strategies',
+                });
+                throw new Error('Expected PathNotFoundError to be thrown');
+            }
+            catch (err) {
+                expect(err).toBeInstanceOf(PathNotFoundError);
+                expect(err.skill).toBe('first-skill');
+                expect(err.path).toBe('indexing-strategies');
+                expect(err.listing).toContain('SKILL.md');
+            }
+        });
+        it('invalid path directory traversal: viewSkillContent throws InvalidPathError', async () => {
+            try {
+                await viewSkillContent({
+                    name: 'first-skill',
+                    path: '../../etc/passwd',
+                });
+                throw new Error('Expected InvalidPathError to be thrown');
+            }
+            catch (err) {
+                expect(err).toBeInstanceOf(InvalidPathError);
+                expect(err.path).toBe('../../etc/passwd');
+            }
+        });
+        it('invalid path with null byte: viewSkillContent throws InvalidPathError', async () => {
+            await expect(viewSkillContent({
+                name: 'first-skill',
+                path: 'SKILL.md\x00.txt',
+            })).rejects.toThrow(InvalidPathError);
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tigerdata/mcp-boilerplate",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "MCP boilerplate code for Node.js",
   "license": "Apache-2.0",
   "author": "TigerData",
@@ -37,7 +37,8 @@
     "build": "tsc",
     "prepublishOnly": "tsc",
     "watch": "tsc --watch",
-    "lint": "./bun x @biomejs/biome check"
+    "lint": "./bun x @biomejs/biome check",
+    "test": "./bun test ./src"
   },
   "dependencies": {
     "@mcp-use/inspector": "^0.24.5",