Merge pull request #106 from rohitg00/feat/infra-v1.21

feat: progressive disclosure execution layer for MCP server
This commit is contained in:
Rohit Ghumare
2026-04-12 00:29:07 +01:00
committed by GitHub
6 changed files with 420 additions and 3 deletions
+13
View File
@@ -183,11 +183,14 @@ type AgentType =
| 'antigravity'
| 'amp'
| 'clawdbot'
| 'openclaw'
| 'cline'
| 'codebuddy'
| 'codegpt'
| 'commandcode'
| 'continue'
| 'crush'
| 'devin'
| 'droid'
| 'factory'
| 'github-copilot'
@@ -199,6 +202,7 @@ type AgentType =
| 'neovate'
| 'openhands'
| 'pi'
| 'playcode-agent'
| 'qoder'
| 'qwen'
| 'roo'
@@ -206,6 +210,15 @@ type AgentType =
| 'vercel'
| 'windsurf'
| 'zencoder'
| 'aider'
| 'amazon-q'
| 'augment-code'
| 'bolt'
| 'lovable'
| 'replit-agent'
| 'sourcegraph-cody'
| 'tabby'
| 'tabnine'
| 'universal';
```
+12
View File
@@ -11,33 +11,45 @@ export const SKILL_DISCOVERY_PATHS = [
'agents',
'.agents/skills',
'.agent/skills',
'.aider/skills',
'.amazonq/skills',
'.amp/skills',
'.antigravity/skills',
'.augment/skills',
'.bolt/skills',
'.claude/skills',
'.cline/skills',
'.clawdbot/skills',
'.codebuddy/skills',
'.codegpt/skills',
'.codex/skills',
'.cody/skills',
'.commandcode/skills',
'.continue/skills',
'.copilot/skills',
'.crush/skills',
'.cursor/skills',
'.devin/skills',
'.factory/skills',
'.gemini/skills',
'.github/skills',
'.goose/skills',
'.kilocode/skills',
'.kiro/skills',
'.lovable/skills',
'.mcpjam/skills',
'.mux/skills',
'.neovate/skills',
'.opencode/skills',
'.openhands/skills',
'.pi/skills',
'.playcode/skills',
'.qoder/skills',
'.qwen/skills',
'.replit/skills',
'.roo/skills',
'.tabby/skills',
'.tabnine/skills',
'.trae/skills',
'.vercel/skills',
'.windsurf/skills',
+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}` }],
+181 -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, realpathSync } from 'node:fs';
import {
SearchSkillsInputSchema,
GetSkillInputSchema,
RecommendSkillsInputSchema,
SkillkitCatalogInputSchema,
SkillkitLoadInputSchema,
SkillkitResourceInputSchema,
} from './types.js';
export interface SkillEntry {
@@ -167,3 +180,170 @@ export function handleListCategories(skills: SkillEntry[]) {
],
};
}
const AGENT_DIR_MAP: Record<string, string[]> = {
'claude-code': ['.claude/skills'], 'cursor': ['.cursor/skills'], 'codex': ['.codex/skills'],
'gemini-cli': ['.gemini/skills'], 'opencode': ['.opencode/skills', '.config/opencode/skills'],
'antigravity': ['.antigravity/skills'], 'amp': ['.amp/skills'], 'clawdbot': ['.clawdbot/skills'],
'openclaw': ['skills'], 'github-copilot': ['.github/skills'], 'goose': ['.goose/skills'],
'kilo': ['.kilocode/skills'], 'kiro-cli': ['.kiro/skills'], 'roo': ['.roo/skills'],
'trae': ['.trae/skills'], 'windsurf': ['.windsurf/skills', '.codeium/windsurf/skills'],
'universal': ['skills'], 'droid': ['.factory/skills'], 'factory': ['.factory/skills'],
'cline': ['.cline/skills'], 'codebuddy': ['.codebuddy/skills'], 'codegpt': ['.codegpt/skills'],
'commandcode': ['.commandcode/skills'], 'continue': ['.continue/skills'],
'crush': ['.crush/skills'], 'devin': ['.devin/skills'], 'mcpjam': ['.mcpjam/skills'],
'mux': ['.mux/skills'], 'neovate': ['.neovate/skills'], 'openhands': ['.openhands/skills'],
'pi': ['.pi/skills'], 'playcode-agent': ['.playcode/skills'], 'qoder': ['.qoder/skills'],
'qwen': ['.qwen/skills'], 'vercel': ['.vercel/skills'], 'zencoder': ['.zencoder/skills'],
'aider': ['.aider/skills'], 'amazon-q': ['.amazonq/skills'], 'augment-code': ['.augment/skills'],
'bolt': ['.bolt/skills'], 'lovable': ['.lovable/skills'], 'replit-agent': ['.replit/skills'],
'sourcegraph-cody': ['.cody/skills'], 'tabby': ['.tabby/skills'], 'tabnine': ['.tabnine/skills'],
};
export function getLocalSkillDirs(agentFilter?: string): string[] {
const dirs: string[] = [];
const home = homedir();
const roots = [process.cwd(), home];
let allowedPaths: Set<string> | null = null;
if (agentFilter) {
const agentDirs = AGENT_DIR_MAP[agentFilter] ?? [];
allowedPaths = new Set(['skills', 'agents', '.agents/skills', '.agent/skills', ...agentDirs]);
}
for (const root of roots) {
for (const rel of SKILL_DISCOVERY_PATHS) {
if (allowedPaths && !allowedPaths.has(rel)) continue;
const full = join(root, rel);
if (existsSync(full) && !dirs.includes(full)) {
dirs.push(full);
}
}
}
if (agentFilter) {
const agentDirs = AGENT_DIR_MAP[agentFilter] ?? [];
for (const rel of agentDirs) {
if (!SKILL_DISCOVERY_PATHS.includes(rel)) {
const full = join(home, 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,
};
}
let realPath: string;
let realSkillDir: string;
try {
realPath = realpathSync(filePath);
realSkillDir = realpathSync(skill.path);
} catch {
realPath = filePath;
realSkillDir = resolve(skill.path);
}
if (!isPathInside(realPath, realSkillDir)) {
return {
content: [{ type: 'text' as const, text: `Path traversal denied: ${input.file}` }],
isError: true,
};
}
try {
const content = readFileSync(realPath, '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>;