mirror of
https://github.com/rohitg00/skillkit.git
synced 2026-11-18 18:04:26 +00:00
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:
@@ -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');
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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
@@ -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,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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>;
|
||||
|
||||
Reference in New Issue
Block a user