Add progressive disclosure tools (skillkit_catalog, skillkit_load, skillkit_resource) to MCP server

Three new tools for token-efficient local skill access:
- skillkit_catalog (L1): lightweight catalog of installed skills (~50 tokens/skill)
- skillkit_load (L2): full SKILL.md content for a single skill
- skillkit_resource (L3): specific reference file with path traversal protection

Bumps server version to 1.21.0. Adds 14 new tests (18 total).
This commit is contained in:
Rohit Ghumare
2026-04-11 20:24:20 +01:00
parent bb97e9b747
commit 8ec5b9d8f2
4 changed files with 345 additions and 3 deletions
+155 -1
View File
@@ -1,9 +1,13 @@
import { describe, it, expect } from 'vitest';
import { describe, it, expect, vi, beforeEach } from 'vitest';
import {
handleSearchSkills,
handleGetSkill,
handleRecommendSkills,
handleListCategories,
handleSkillkitCatalog,
handleSkillkitLoad,
handleSkillkitResource,
getLocalSkillDirs,
} from '../tools.js';
import type { SkillEntry } from '../tools.js';
@@ -82,3 +86,153 @@ describe('handleListCategories', () => {
expect(react?.count).toBe(1);
});
});
vi.mock('@skillkit/core', async (importOriginal) => {
const actual = await importOriginal<typeof import('@skillkit/core')>();
return {
...actual,
findAllSkills: vi.fn(),
findSkill: vi.fn(),
readSkillContent: vi.fn(),
};
});
vi.mock('node:fs', async (importOriginal) => {
const actual = await importOriginal<typeof import('node:fs')>();
return {
...actual,
existsSync: vi.fn(actual.existsSync),
readFileSync: vi.fn(actual.readFileSync),
};
});
import { findAllSkills, findSkill, readSkillContent } from '@skillkit/core';
import { existsSync, readFileSync } from 'node:fs';
const mockFindAllSkills = vi.mocked(findAllSkills);
const mockFindSkill = vi.mocked(findSkill);
const mockReadSkillContent = vi.mocked(readSkillContent);
const mockExistsSync = vi.mocked(existsSync);
const mockReadFileSync = vi.mocked(readFileSync);
describe('handleSkillkitCatalog', () => {
beforeEach(() => {
vi.clearAllMocks();
});
it('returns minimal catalog entries', () => {
mockFindAllSkills.mockReturnValue([
{ name: 'my-skill', description: 'A test skill', path: '/home/user/.claude/skills/my-skill', location: 'global', enabled: true },
{ name: 'other-skill', description: 'Another skill', path: '/project/skills/other-skill', location: 'project', enabled: true },
]);
const result = handleSkillkitCatalog({});
const data = JSON.parse(result.content[0].text);
expect(data.total).toBe(2);
expect(data.skills[0]).toEqual({ name: 'my-skill', description: 'A test skill', source: 'global' });
expect(data.skills[1]).toEqual({ name: 'other-skill', description: 'Another skill', source: 'project' });
});
it('returns empty array when no skills found', () => {
mockFindAllSkills.mockReturnValue([]);
const result = handleSkillkitCatalog({});
const data = JSON.parse(result.content[0].text);
expect(data.total).toBe(0);
expect(data.skills).toEqual([]);
});
});
describe('handleSkillkitLoad', () => {
beforeEach(() => {
vi.clearAllMocks();
});
it('returns full skill content', () => {
mockFindSkill.mockReturnValue({
name: 'my-skill',
description: 'A test skill',
path: '/home/user/.claude/skills/my-skill',
location: 'global',
enabled: true,
});
mockReadSkillContent.mockReturnValue('# My Skill\n\nFull content here');
const result = handleSkillkitLoad({ name: 'my-skill' });
expect(result.content[0].text).toBe('# My Skill\n\nFull content here');
expect((result as Record<string, unknown>).isError).toBeUndefined();
});
it('returns error for missing skill', () => {
mockFindSkill.mockReturnValue(null);
const result = handleSkillkitLoad({ name: 'nonexistent' });
expect((result as Record<string, unknown>).isError).toBe(true);
expect(result.content[0].text).toContain('Skill not found');
});
it('returns error when content unreadable', () => {
mockFindSkill.mockReturnValue({
name: 'broken-skill',
description: 'Broken',
path: '/home/user/.claude/skills/broken-skill',
location: 'global',
enabled: true,
});
mockReadSkillContent.mockReturnValue(null);
const result = handleSkillkitLoad({ name: 'broken-skill' });
expect((result as Record<string, unknown>).isError).toBe(true);
expect(result.content[0].text).toContain('Could not read');
});
});
describe('handleSkillkitResource', () => {
beforeEach(() => {
vi.clearAllMocks();
});
it('returns file content', () => {
mockFindSkill.mockReturnValue({
name: 'my-skill',
description: 'A test skill',
path: '/home/user/.claude/skills/my-skill',
location: 'global',
enabled: true,
});
mockExistsSync.mockReturnValue(true);
mockReadFileSync.mockReturnValue('reference content' as never);
const result = handleSkillkitResource({ name: 'my-skill', file: 'references/api.md' });
expect(result.content[0].text).toBe('reference content');
expect((result as Record<string, unknown>).isError).toBeUndefined();
});
it('returns error for missing skill', () => {
mockFindSkill.mockReturnValue(null);
const result = handleSkillkitResource({ name: 'nonexistent', file: 'references/api.md' });
expect((result as Record<string, unknown>).isError).toBe(true);
expect(result.content[0].text).toContain('Skill not found');
});
it('blocks path traversal', () => {
mockFindSkill.mockReturnValue({
name: 'my-skill',
description: 'A test skill',
path: '/home/user/.claude/skills/my-skill',
location: 'global',
enabled: true,
});
const result = handleSkillkitResource({ name: 'my-skill', file: '../../etc/passwd' });
expect((result as Record<string, unknown>).isError).toBe(true);
expect(result.content[0].text).toContain('Path traversal denied');
});
it('returns error for missing file', () => {
mockFindSkill.mockReturnValue({
name: 'my-skill',
description: 'A test skill',
path: '/home/user/.claude/skills/my-skill',
location: 'global',
enabled: true,
});
mockExistsSync.mockReturnValue(false);
const result = handleSkillkitResource({ name: 'my-skill', file: 'references/missing.md' });
expect((result as Record<string, unknown>).isError).toBe(true);
expect(result.content[0].text).toContain('File not found');
});
});
+43 -1
View File
@@ -13,6 +13,9 @@ import {
handleGetSkill,
handleRecommendSkills,
handleListCategories,
handleSkillkitCatalog,
handleSkillkitLoad,
handleSkillkitResource,
} from './tools.js';
import type { SkillEntry } from './tools.js';
import { getTrendingResource, getCategoriesResource } from './resources.js';
@@ -55,7 +58,7 @@ async function loadSkills(): Promise<SkillEntry[]> {
const server = new Server(
{
name: 'skillkit-discovery',
version: '1.17.0',
version: '1.21.0',
},
{
capabilities: {
@@ -125,6 +128,39 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
properties: {},
},
},
{
name: 'skillkit_catalog',
description: 'List all installed skills with name and description. Use this first to see what skills are available. Each entry costs ~50 tokens.',
inputSchema: {
type: 'object',
properties: {
agent: { type: 'string', description: 'Filter by agent type (e.g. claude-code, cursor)' },
},
},
},
{
name: 'skillkit_load',
description: 'Load the full content of a specific installed skill. Call this only when you need the detailed instructions for a skill found via skillkit_catalog.',
inputSchema: {
type: 'object',
properties: {
name: { type: 'string', description: 'Skill name from the catalog' },
},
required: ['name'],
},
},
{
name: 'skillkit_resource',
description: 'Load a specific reference file from within a skill directory. Use when a skill references external files.',
inputSchema: {
type: 'object',
properties: {
name: { type: 'string', description: 'Skill name' },
file: { type: 'string', description: 'Relative file path within the skill (e.g. references/api.md)' },
},
required: ['name', 'file'],
},
},
],
};
});
@@ -142,6 +178,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
return handleRecommendSkills(skills, args);
case 'list_categories':
return handleListCategories(skills);
case 'skillkit_catalog':
return handleSkillkitCatalog(args);
case 'skillkit_load':
return handleSkillkitLoad(args);
case 'skillkit_resource':
return handleSkillkitResource(args);
default:
return {
content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+131 -1
View File
@@ -1,8 +1,21 @@
import { RelevanceRanker } from '@skillkit/core';
import {
RelevanceRanker,
findAllSkills,
findSkill,
readSkillContent,
isPathInside,
SKILL_DISCOVERY_PATHS,
} from '@skillkit/core';
import { homedir } from 'node:os';
import { join, resolve } from 'node:path';
import { existsSync, readFileSync } from 'node:fs';
import {
SearchSkillsInputSchema,
GetSkillInputSchema,
RecommendSkillsInputSchema,
SkillkitCatalogInputSchema,
SkillkitLoadInputSchema,
SkillkitResourceInputSchema,
} from './types.js';
export interface SkillEntry {
@@ -167,3 +180,120 @@ export function handleListCategories(skills: SkillEntry[]) {
],
};
}
export function getLocalSkillDirs(agentFilter?: string): string[] {
const dirs: string[] = [];
const home = homedir();
const roots = [home, process.cwd()];
for (const root of roots) {
for (const rel of SKILL_DISCOVERY_PATHS) {
if (agentFilter) {
const dirAgent = rel.replace(/^\./, '').split('/')[0];
if (dirAgent !== agentFilter && dirAgent !== 'agents' && dirAgent !== 'skills') continue;
}
const full = join(root, rel);
if (existsSync(full) && !dirs.includes(full)) {
dirs.push(full);
}
}
}
return dirs;
}
export function handleSkillkitCatalog(args: unknown) {
const input = SkillkitCatalogInputSchema.parse(args);
const dirs = getLocalSkillDirs(input.agent);
const skills = findAllSkills(dirs);
const catalog = skills.map((s) => ({
name: s.name,
description: s.description,
source: s.location,
}));
return {
content: [
{
type: 'text' as const,
text: JSON.stringify({ skills: catalog, total: catalog.length }, null, 2),
},
],
};
}
export function handleSkillkitLoad(args: unknown) {
const input = SkillkitLoadInputSchema.parse(args);
const dirs = getLocalSkillDirs();
const skill = findSkill(input.name, dirs);
if (!skill) {
return {
content: [{ type: 'text' as const, text: `Skill not found: ${input.name}` }],
isError: true,
};
}
const content = readSkillContent(skill.path);
if (!content) {
return {
content: [{ type: 'text' as const, text: `Could not read skill content: ${input.name}` }],
isError: true,
};
}
return {
content: [
{
type: 'text' as const,
text: content,
},
],
};
}
export function handleSkillkitResource(args: unknown) {
const input = SkillkitResourceInputSchema.parse(args);
const dirs = getLocalSkillDirs();
const skill = findSkill(input.name, dirs);
if (!skill) {
return {
content: [{ type: 'text' as const, text: `Skill not found: ${input.name}` }],
isError: true,
};
}
const filePath = resolve(join(skill.path, input.file));
if (!isPathInside(filePath, skill.path)) {
return {
content: [{ type: 'text' as const, text: `Path traversal denied: ${input.file}` }],
isError: true,
};
}
if (!existsSync(filePath)) {
return {
content: [{ type: 'text' as const, text: `File not found: ${input.file}` }],
isError: true,
};
}
try {
const content = readFileSync(filePath, 'utf-8');
return {
content: [
{
type: 'text' as const,
text: content,
},
],
};
} catch {
return {
content: [{ type: 'text' as const, text: `Could not read file: ${input.file}` }],
isError: true,
};
}
}
+16
View File
@@ -31,6 +31,22 @@ export const RecommendSkillsInputSchema = z.object({
export const ListCategoriesInputSchema = z.object({});
export const SkillkitCatalogInputSchema = z.object({
agent: z.string().optional().describe('Filter by agent type (e.g. claude-code, cursor)'),
});
export const SkillkitLoadInputSchema = z.object({
name: z.string().describe('Skill name from the catalog'),
});
export const SkillkitResourceInputSchema = z.object({
name: z.string().describe('Skill name'),
file: z.string().describe('Relative file path within the skill (e.g. references/api.md)'),
});
export type SearchSkillsInput = z.infer<typeof SearchSkillsInputSchema>;
export type GetSkillInput = z.infer<typeof GetSkillInputSchema>;
export type RecommendSkillsInput = z.infer<typeof RecommendSkillsInputSchema>;
export type SkillkitCatalogInput = z.infer<typeof SkillkitCatalogInputSchema>;
export type SkillkitLoadInput = z.infer<typeof SkillkitLoadInputSchema>;
export type SkillkitResourceInput = z.infer<typeof SkillkitResourceInputSchema>;