mirror of
https://github.com/rohitg00/skillkit.git
synced 2026-11-18 18:04:26 +00:00
feat: runtime skill discovery — REST API, MCP server, cache, ranking, Python client (#42)
* feat: runtime skill discovery — REST API, MCP server, cache, ranking, Python client (#42) Add runtime skill discovery capabilities enabling agents to autonomously search and retrieve skills on demand, inspired by skyll.app's approach of making skills queryable by intent rather than requiring pre-installation. Core infrastructure: - Pluggable cache backend with LRU + TTL (MemoryCache) - Multi-signal relevance ranker (content 40pts, query 30pts, popularity 15pts, refs 15pts) - Enhanced SKILL.md parser with frontmatter extraction and reference discovery - Runtime skill injector fetching SKILL.md from GitHub with caching REST API server (@skillkit/api): - Hono-based HTTP server on port 3737 - GET/POST /search with ranked results and filters - GET /skills/:source/:id, /trending, /categories, /health, /cache/stats - Sliding-window rate limiting (60 req/min/IP) MCP server (@skillkit/mcp): - 4 tools: search_skills, get_skill, recommend_skills, list_categories - 2 resources: skills://trending, skills://categories - Compatible with Claude Desktop, Cursor, any MCP client CLI serve command: - `skillkit serve` starts the API server - Options: --port, --host, --cors, --cache-ttl Community registry: - registry/SKILLS.md with 26 curated skills across 12 categories - CommunityRegistry class integrated into FederatedSearch Python client (skillkit-client): - Async httpx + pydantic client for the REST API - search, get_skill, trending, categories, cache_stats, health All 856+ tests pass across 24 workspace tasks. * fix: resolve TypeScript errors in API package Add explicit return type to rate limiter middleware and remove stale CategoryCount type annotation in categories route. * fix: address CodeRabbit review findings and version-check CI - Fix version-check: bump docs packages to 1.11.0 - Parse first IP from X-Forwarded-For header in rate limiter - Add try/catch for malformed JSON in POST /search - Use exact source match in skill routes (owner/repo/id pattern) - Fix NaN fallback for invalid limit params in trending/search - Filter empty strings from query words in relevance ranker - Use Map lookups instead of O(n^2) find in MCP resources/tools - URL-encode path params in Python client - Fix -h flag conflict with Clipanion help in serve command - Fix typo: remoti-dev -> remotion-dev in registry SKILLS.md * fix: address Devin review — composite key lookups and Python URL path - Use source+name composite key Map lookups in search GET/POST routes - Use source+name composite key Map lookup in trending route - Fix Python client get_skill to use /skills/:owner/:repo/:id URL pattern - Update Python test to match new 3-segment skill URL
This commit is contained in:
@@ -53,6 +53,7 @@
|
||||
"node": ">=18.0.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"@skillkit/api": "workspace:*",
|
||||
"@skillkit/core": "workspace:*",
|
||||
"@skillkit/agents": "workspace:*",
|
||||
"@skillkit/cli": "workspace:*",
|
||||
|
||||
@@ -102,6 +102,7 @@ import {
|
||||
SkillMdValidateCommand,
|
||||
SkillMdInitCommand,
|
||||
SkillMdCheckCommand,
|
||||
ServeCommand,
|
||||
} from '@skillkit/cli';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
@@ -229,4 +230,6 @@ cli.register(SkillMdValidateCommand);
|
||||
cli.register(SkillMdInitCommand);
|
||||
cli.register(SkillMdCheckCommand);
|
||||
|
||||
cli.register(ServeCommand);
|
||||
|
||||
cli.runExit(process.argv.slice(2));
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
[build-system]
|
||||
requires = ["hatchling"]
|
||||
build-backend = "hatchling.build"
|
||||
|
||||
[project]
|
||||
name = "skillkit-client"
|
||||
version = "0.1.0"
|
||||
description = "Python client for the SkillKit REST API"
|
||||
readme = "README.md"
|
||||
license = "Apache-2.0"
|
||||
requires-python = ">=3.9"
|
||||
authors = [
|
||||
{ name = "Rohit Ghumare", email = "ghumare64@gmail.com" },
|
||||
]
|
||||
keywords = ["skillkit", "ai", "agents", "skills", "discovery"]
|
||||
classifiers = [
|
||||
"Development Status :: 3 - Alpha",
|
||||
"Intended Audience :: Developers",
|
||||
"License :: OSI Approved :: Apache Software License",
|
||||
"Programming Language :: Python :: 3",
|
||||
"Programming Language :: Python :: 3.9",
|
||||
"Programming Language :: Python :: 3.10",
|
||||
"Programming Language :: Python :: 3.11",
|
||||
"Programming Language :: Python :: 3.12",
|
||||
"Topic :: Software Development :: Libraries",
|
||||
]
|
||||
dependencies = [
|
||||
"httpx>=0.27",
|
||||
"pydantic>=2.0",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = [
|
||||
"pytest>=7.0",
|
||||
"pytest-asyncio>=0.23",
|
||||
"respx>=0.21",
|
||||
]
|
||||
|
||||
[project.urls]
|
||||
Homepage = "https://github.com/rohitg00/skillkit"
|
||||
Documentation = "https://agenstskills.com"
|
||||
Repository = "https://github.com/rohitg00/skillkit"
|
||||
@@ -0,0 +1,12 @@
|
||||
from skillkit.client import SkillKitClient
|
||||
from skillkit.models import Skill, SearchResponse, HealthResponse, CacheStats, Category
|
||||
|
||||
__all__ = [
|
||||
"SkillKitClient",
|
||||
"Skill",
|
||||
"SearchResponse",
|
||||
"HealthResponse",
|
||||
"CacheStats",
|
||||
"Category",
|
||||
]
|
||||
__version__ = "0.1.0"
|
||||
@@ -0,0 +1,140 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Optional
|
||||
from urllib.parse import quote
|
||||
|
||||
import httpx
|
||||
|
||||
from skillkit.models import (
|
||||
CacheStats,
|
||||
CategoriesResponse,
|
||||
Category,
|
||||
HealthResponse,
|
||||
SearchResponse,
|
||||
Skill,
|
||||
TrendingResponse,
|
||||
)
|
||||
|
||||
|
||||
class SkillKitClient:
|
||||
def __init__(self, base_url: str = "http://localhost:3737", timeout: float = 30.0):
|
||||
self.base_url = base_url.rstrip("/")
|
||||
self.timeout = timeout
|
||||
self._client: Optional[httpx.AsyncClient] = None
|
||||
|
||||
async def __aenter__(self) -> "SkillKitClient":
|
||||
self._client = httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout)
|
||||
return self
|
||||
|
||||
async def __aexit__(self, *args: object) -> None:
|
||||
if self._client:
|
||||
await self._client.aclose()
|
||||
self._client = None
|
||||
|
||||
def _get_client(self) -> httpx.AsyncClient:
|
||||
if self._client is None:
|
||||
self._client = httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout)
|
||||
return self._client
|
||||
|
||||
async def health(self) -> HealthResponse:
|
||||
client = self._get_client()
|
||||
response = await client.get("/health")
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return HealthResponse(
|
||||
status=data["status"],
|
||||
version=data["version"],
|
||||
skill_count=data.get("skillCount", 0),
|
||||
uptime=data.get("uptime", 0),
|
||||
)
|
||||
|
||||
async def search(
|
||||
self,
|
||||
query: str,
|
||||
limit: int = 20,
|
||||
include_content: bool = False,
|
||||
) -> SearchResponse:
|
||||
client = self._get_client()
|
||||
params = {"q": query, "limit": str(limit)}
|
||||
if include_content:
|
||||
params["include_content"] = "true"
|
||||
response = await client.get("/search", params=params)
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return SearchResponse(
|
||||
skills=[Skill(**s) for s in data["skills"]],
|
||||
total=data["total"],
|
||||
query=data["query"],
|
||||
limit=data["limit"],
|
||||
)
|
||||
|
||||
async def search_with_filters(
|
||||
self,
|
||||
query: str,
|
||||
limit: int = 20,
|
||||
include_content: bool = False,
|
||||
tags: Optional[list[str]] = None,
|
||||
category: Optional[str] = None,
|
||||
source: Optional[str] = None,
|
||||
) -> SearchResponse:
|
||||
client = self._get_client()
|
||||
body: dict = {"query": query, "limit": limit, "include_content": include_content}
|
||||
filters: dict = {}
|
||||
if tags:
|
||||
filters["tags"] = tags
|
||||
if category:
|
||||
filters["category"] = category
|
||||
if source:
|
||||
filters["source"] = source
|
||||
if filters:
|
||||
body["filters"] = filters
|
||||
response = await client.post("/search", json=body)
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return SearchResponse(
|
||||
skills=[Skill(**s) for s in data["skills"]],
|
||||
total=data["total"],
|
||||
query=data["query"],
|
||||
limit=data["limit"],
|
||||
)
|
||||
|
||||
async def get_skill(self, source: str, skill_id: str) -> Skill:
|
||||
client = self._get_client()
|
||||
parts = source.split("/", 1)
|
||||
owner = quote(parts[0], safe="")
|
||||
repo = quote(parts[1], safe="") if len(parts) > 1 else owner
|
||||
response = await client.get(f"/skills/{owner}/{repo}/{quote(skill_id, safe='')}")
|
||||
response.raise_for_status()
|
||||
return Skill(**response.json())
|
||||
|
||||
async def trending(self, limit: int = 20) -> list[Skill]:
|
||||
client = self._get_client()
|
||||
response = await client.get("/trending", params={"limit": str(limit)})
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return [Skill(**s) for s in data["skills"]]
|
||||
|
||||
async def categories(self) -> list[Category]:
|
||||
client = self._get_client()
|
||||
response = await client.get("/categories")
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return [Category(**c) for c in data["categories"]]
|
||||
|
||||
async def cache_stats(self) -> CacheStats:
|
||||
client = self._get_client()
|
||||
response = await client.get("/cache/stats")
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return CacheStats(
|
||||
hits=data["hits"],
|
||||
misses=data["misses"],
|
||||
size=data["size"],
|
||||
max_size=data.get("maxSize", 0),
|
||||
hit_rate=data.get("hitRate", 0.0),
|
||||
)
|
||||
|
||||
async def close(self) -> None:
|
||||
if self._client:
|
||||
await self._client.aclose()
|
||||
self._client = None
|
||||
@@ -0,0 +1,51 @@
|
||||
from typing import Optional
|
||||
from pydantic import BaseModel
|
||||
|
||||
|
||||
class Skill(BaseModel):
|
||||
name: str
|
||||
description: Optional[str] = None
|
||||
source: str
|
||||
repo: Optional[str] = None
|
||||
tags: Optional[list[str]] = None
|
||||
category: Optional[str] = None
|
||||
content: Optional[str] = None
|
||||
stars: Optional[int] = None
|
||||
installs: Optional[int] = None
|
||||
|
||||
|
||||
class SearchResponse(BaseModel):
|
||||
skills: list[Skill]
|
||||
total: int
|
||||
query: str
|
||||
limit: int
|
||||
|
||||
|
||||
class HealthResponse(BaseModel):
|
||||
status: str
|
||||
version: str
|
||||
skill_count: int = 0
|
||||
uptime: int = 0
|
||||
|
||||
|
||||
class CacheStats(BaseModel):
|
||||
hits: int
|
||||
misses: int
|
||||
size: int
|
||||
max_size: int = 0
|
||||
hit_rate: float = 0.0
|
||||
|
||||
|
||||
class Category(BaseModel):
|
||||
name: str
|
||||
count: int
|
||||
|
||||
|
||||
class CategoriesResponse(BaseModel):
|
||||
categories: list[Category]
|
||||
total: int
|
||||
|
||||
|
||||
class TrendingResponse(BaseModel):
|
||||
skills: list[Skill]
|
||||
limit: int
|
||||
@@ -0,0 +1,99 @@
|
||||
import pytest
|
||||
import httpx
|
||||
import respx
|
||||
|
||||
from skillkit import SkillKitClient
|
||||
|
||||
|
||||
BASE_URL = "http://localhost:3737"
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def mock_api():
|
||||
with respx.mock(base_url=BASE_URL) as respx_mock:
|
||||
yield respx_mock
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_health(mock_api):
|
||||
mock_api.get("/health").respond(
|
||||
json={"status": "ok", "version": "1.11.0", "skillCount": 100, "uptime": 60}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
health = await client.health()
|
||||
assert health.status == "ok"
|
||||
assert health.version == "1.11.0"
|
||||
assert health.skill_count == 100
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_search(mock_api):
|
||||
mock_api.get("/search").respond(
|
||||
json={
|
||||
"skills": [{"name": "react-perf", "source": "owner/repo"}],
|
||||
"total": 1,
|
||||
"query": "react",
|
||||
"limit": 20,
|
||||
}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
result = await client.search("react")
|
||||
assert result.total == 1
|
||||
assert result.skills[0].name == "react-perf"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_search_with_filters(mock_api):
|
||||
mock_api.post("/search").respond(
|
||||
json={
|
||||
"skills": [{"name": "nextjs-auth", "source": "other/repo"}],
|
||||
"total": 1,
|
||||
"query": "auth",
|
||||
"limit": 20,
|
||||
}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
result = await client.search_with_filters("auth", tags=["nextjs"])
|
||||
assert result.total == 1
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_get_skill(mock_api):
|
||||
mock_api.get("/skills/owner/repo/react-perf").respond(
|
||||
json={"name": "react-perf", "description": "React performance", "source": "owner/repo"}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
skill = await client.get_skill("owner/repo", "react-perf")
|
||||
assert skill.name == "react-perf"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_trending(mock_api):
|
||||
mock_api.get("/trending").respond(
|
||||
json={"skills": [{"name": "a", "source": "x/y"}], "limit": 20}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
trending = await client.trending()
|
||||
assert len(trending) == 1
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_categories(mock_api):
|
||||
mock_api.get("/categories").respond(
|
||||
json={"categories": [{"name": "react", "count": 5}], "total": 1}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
cats = await client.categories()
|
||||
assert len(cats) == 1
|
||||
assert cats[0].name == "react"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_cache_stats(mock_api):
|
||||
mock_api.get("/cache/stats").respond(
|
||||
json={"hits": 10, "misses": 5, "size": 8, "maxSize": 500, "hitRate": 0.667}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
stats = await client.cache_stats()
|
||||
assert stats.hits == 10
|
||||
assert stats.size == 8
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "skillkit-docs",
|
||||
"version": "1.10.0",
|
||||
"version": "1.11.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "next build",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "skillkit",
|
||||
"private": true,
|
||||
"version": "1.10.0",
|
||||
"version": "1.11.0",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
{
|
||||
"name": "@skillkit/api",
|
||||
"version": "1.11.0",
|
||||
"description": "REST API server for SkillKit skill discovery",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts",
|
||||
"bin": {
|
||||
"skillkit-api": "./dist/index.js"
|
||||
},
|
||||
"exports": {
|
||||
".": {
|
||||
"import": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts"
|
||||
}
|
||||
},
|
||||
"files": [
|
||||
"dist"
|
||||
],
|
||||
"scripts": {
|
||||
"build": "tsup",
|
||||
"dev": "tsup --watch",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"test": "vitest run",
|
||||
"start": "node dist/index.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"hono": "^4.0.0",
|
||||
"@hono/node-server": "^1.0.0",
|
||||
"@skillkit/core": "workspace:*",
|
||||
"zod": "^3.24.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.10.5",
|
||||
"tsup": "^8.3.5",
|
||||
"typescript": "^5.7.2",
|
||||
"vitest": "^2.1.8"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18.0.0"
|
||||
},
|
||||
"license": "Apache-2.0",
|
||||
"keywords": [
|
||||
"skillkit",
|
||||
"api",
|
||||
"rest",
|
||||
"skills",
|
||||
"discovery",
|
||||
"ai",
|
||||
"agents"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
describe('Health Routes', () => {
|
||||
const { app } = createApp({ skills: [{ name: 'test', source: 'a/b' }], rateLimitMax: 1000 });
|
||||
|
||||
it('GET /health returns status ok', async () => {
|
||||
const res = await app.request('/health');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.status).toBe('ok');
|
||||
expect(body.skillCount).toBe(1);
|
||||
expect(typeof body.uptime).toBe('number');
|
||||
expect(body.version).toBeDefined();
|
||||
});
|
||||
|
||||
it('GET /cache/stats returns cache statistics', async () => {
|
||||
const res = await app.request('/cache/stats');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(typeof body.hits).toBe('number');
|
||||
expect(typeof body.misses).toBe('number');
|
||||
expect(typeof body.size).toBe('number');
|
||||
expect(typeof body.maxSize).toBe('number');
|
||||
expect(typeof body.hitRate).toBe('number');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,56 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
const testSkills = [
|
||||
{ name: 'react-perf', description: 'React performance tips', source: 'owner/repo', tags: ['react', 'performance'] },
|
||||
{ name: 'testing-guide', description: 'Unit testing guide', source: 'owner/repo2', tags: ['testing'] },
|
||||
{ name: 'nextjs-auth', description: 'Next.js authentication', source: 'other/repo', tags: ['nextjs', 'auth'], category: 'framework' },
|
||||
];
|
||||
|
||||
describe('Search Routes', () => {
|
||||
const { app } = createApp({ skills: testSkills, rateLimitMax: 1000 });
|
||||
|
||||
it('GET /search returns results for query', async () => {
|
||||
const res = await app.request('/search?q=react');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.query).toBe('react');
|
||||
expect(body.skills.length).toBeGreaterThan(0);
|
||||
expect(body.total).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('GET /search returns 400 without query', async () => {
|
||||
const res = await app.request('/search');
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
|
||||
it('GET /search respects limit parameter', async () => {
|
||||
const res = await app.request('/search?q=test&limit=1');
|
||||
const body = await res.json();
|
||||
expect(body.skills.length).toBeLessThanOrEqual(1);
|
||||
expect(body.limit).toBe(1);
|
||||
});
|
||||
|
||||
it('POST /search with filters', async () => {
|
||||
const res = await app.request('/search', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
query: 'auth',
|
||||
filters: { tags: ['nextjs'] },
|
||||
}),
|
||||
});
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.skills.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('POST /search returns 400 without query', async () => {
|
||||
const res = await app.request('/search', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({}),
|
||||
});
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,53 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
const testSkills = [
|
||||
{ name: 'my-skill', description: 'A test skill', source: 'owner/repo' },
|
||||
];
|
||||
|
||||
describe('Skill Routes', () => {
|
||||
const { app } = createApp({ skills: testSkills, rateLimitMax: 1000 });
|
||||
|
||||
it('GET /skills/:source/:id returns a skill', async () => {
|
||||
const res = await app.request('/skills/owner/repo/my-skill');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.name).toBe('my-skill');
|
||||
expect(body.source).toBe('owner/repo');
|
||||
});
|
||||
|
||||
it('GET /skills/:owner/:repo/:id returns 404 for missing skill', async () => {
|
||||
const res = await app.request('/skills/owner/repo/nonexistent');
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
});
|
||||
|
||||
describe('Trending Routes', () => {
|
||||
const { app } = createApp({ skills: testSkills, rateLimitMax: 1000 });
|
||||
|
||||
it('GET /trending returns skills', async () => {
|
||||
const res = await app.request('/trending');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.skills).toBeInstanceOf(Array);
|
||||
expect(body.limit).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Category Routes', () => {
|
||||
const skills = [
|
||||
{ name: 'a', source: 'x/y', tags: ['react', 'ui'] },
|
||||
{ name: 'b', source: 'x/z', tags: ['react'], category: 'framework' },
|
||||
];
|
||||
const { app } = createApp({ skills, rateLimitMax: 1000 });
|
||||
|
||||
it('GET /categories returns tag counts', async () => {
|
||||
const res = await app.request('/categories');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.categories).toBeInstanceOf(Array);
|
||||
expect(body.total).toBeGreaterThan(0);
|
||||
const react = body.categories.find((c: { name: string }) => c.name === 'react');
|
||||
expect(react?.count).toBe(2);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,11 @@
|
||||
export { createApp, startServer } from './server.js';
|
||||
export type { ServerOptions } from './server.js';
|
||||
export type {
|
||||
ApiSkill,
|
||||
SearchResponse,
|
||||
HealthResponse,
|
||||
CacheStatsResponse,
|
||||
TrendingResponse,
|
||||
CategoriesResponse,
|
||||
CategoryCount,
|
||||
} from './types.js';
|
||||
@@ -0,0 +1,43 @@
|
||||
import type { Context, Next } from 'hono';
|
||||
|
||||
interface RateLimitEntry {
|
||||
count: number;
|
||||
resetAt: number;
|
||||
}
|
||||
|
||||
export function rateLimiter(maxRequests = 60, windowMs = 60_000) {
|
||||
const windows = new Map<string, RateLimitEntry>();
|
||||
|
||||
setInterval(() => {
|
||||
const now = Date.now();
|
||||
for (const [key, entry] of windows) {
|
||||
if (now > entry.resetAt) {
|
||||
windows.delete(key);
|
||||
}
|
||||
}
|
||||
}, windowMs).unref();
|
||||
|
||||
return async (c: Context, next: Next): Promise<Response | void> => {
|
||||
const forwardedFor = c.req.header('x-forwarded-for');
|
||||
const ip = (forwardedFor?.split(',')[0]?.trim()) || c.req.header('x-real-ip') || 'unknown';
|
||||
const now = Date.now();
|
||||
|
||||
let entry = windows.get(ip);
|
||||
if (!entry || now > entry.resetAt) {
|
||||
entry = { count: 0, resetAt: now + windowMs };
|
||||
windows.set(ip, entry);
|
||||
}
|
||||
|
||||
entry.count++;
|
||||
|
||||
c.header('X-RateLimit-Limit', String(maxRequests));
|
||||
c.header('X-RateLimit-Remaining', String(Math.max(0, maxRequests - entry.count)));
|
||||
c.header('X-RateLimit-Reset', String(Math.ceil(entry.resetAt / 1000)));
|
||||
|
||||
if (entry.count > maxRequests) {
|
||||
return c.json({ error: 'Too many requests', retryAfter: Math.ceil((entry.resetAt - now) / 1000) }, 429);
|
||||
}
|
||||
|
||||
await next();
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { ApiSkill, CategoriesResponse } from '../types.js';
|
||||
|
||||
export function categoryRoutes(skills: ApiSkill[]) {
|
||||
const app = new Hono();
|
||||
|
||||
app.get('/categories', (c) => {
|
||||
const tagCounts = new Map<string, number>();
|
||||
|
||||
for (const skill of skills) {
|
||||
if (skill.tags) {
|
||||
for (const tag of skill.tags) {
|
||||
tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
|
||||
}
|
||||
}
|
||||
if (skill.category) {
|
||||
const key = `category:${skill.category}`;
|
||||
tagCounts.set(key, (tagCounts.get(key) || 0) + 1);
|
||||
}
|
||||
}
|
||||
|
||||
const categories = Array.from(tagCounts.entries())
|
||||
.map(([name, count]) => ({ name, count }))
|
||||
.sort((a, b) => b.count - a.count);
|
||||
|
||||
const response: CategoriesResponse = {
|
||||
categories,
|
||||
total: categories.length,
|
||||
};
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { HealthResponse, CacheStatsResponse } from '../types.js';
|
||||
import type { CacheBackend } from '@skillkit/core';
|
||||
|
||||
const startTime = Date.now();
|
||||
|
||||
export function healthRoutes(skillCount: number, cache: CacheBackend) {
|
||||
const app = new Hono();
|
||||
|
||||
app.get('/health', (c) => {
|
||||
const response: HealthResponse = {
|
||||
status: 'ok',
|
||||
version: '1.11.0',
|
||||
skillCount,
|
||||
uptime: Math.floor((Date.now() - startTime) / 1000),
|
||||
};
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
app.get('/cache/stats', (c) => {
|
||||
const stats = cache.stats();
|
||||
const response: CacheStatsResponse = {
|
||||
hits: stats.hits,
|
||||
misses: stats.misses,
|
||||
size: stats.size,
|
||||
maxSize: stats.maxSize,
|
||||
hitRate: stats.hitRate,
|
||||
};
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { ApiSkill, SearchResponse } from '../types.js';
|
||||
import { RelevanceRanker } from '@skillkit/core';
|
||||
import type { MemoryCache } from '@skillkit/core';
|
||||
|
||||
export function searchRoutes(skills: ApiSkill[], cache: MemoryCache<SearchResponse>) {
|
||||
const app = new Hono();
|
||||
const ranker = new RelevanceRanker();
|
||||
|
||||
app.get('/search', (c) => {
|
||||
const query = c.req.query('q') || '';
|
||||
const parsedLimit = parseInt(c.req.query('limit') || '20', 10);
|
||||
const limit = Math.min(Number.isNaN(parsedLimit) ? 20 : parsedLimit, 100);
|
||||
const includeContent = c.req.query('include_content') === 'true';
|
||||
|
||||
if (!query) {
|
||||
return c.json({ error: 'Query parameter "q" is required' }, 400);
|
||||
}
|
||||
|
||||
const cacheKey = `search:${query}:${limit}:${includeContent}`;
|
||||
const cached = cache.get(cacheKey);
|
||||
if (cached) return c.json(cached);
|
||||
|
||||
const skillMap = new Map(skills.map((s) => [`${s.source}:${s.name}`, s]));
|
||||
|
||||
const ranked = ranker.rank(
|
||||
skills.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: s.content,
|
||||
stars: s.stars,
|
||||
installs: s.installs,
|
||||
source: s.source,
|
||||
})),
|
||||
query,
|
||||
);
|
||||
|
||||
const results: ApiSkill[] = ranked.slice(0, limit).map((r) => {
|
||||
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
|
||||
const original = skillMap.get(key) ?? skills.find((s) => s.name === r.skill.name)!;
|
||||
if (!includeContent) {
|
||||
const { content: _, ...rest } = original;
|
||||
return rest;
|
||||
}
|
||||
return original;
|
||||
});
|
||||
|
||||
const response: SearchResponse = {
|
||||
skills: results,
|
||||
total: ranked.length,
|
||||
query,
|
||||
limit,
|
||||
};
|
||||
|
||||
cache.set(cacheKey, response);
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
app.post('/search', async (c) => {
|
||||
let body: {
|
||||
query: string;
|
||||
limit?: number;
|
||||
include_content?: boolean;
|
||||
filters?: { tags?: string[]; category?: string; source?: string };
|
||||
};
|
||||
try {
|
||||
body = await c.req.json();
|
||||
} catch {
|
||||
return c.json({ error: 'Invalid JSON body' }, 400);
|
||||
}
|
||||
|
||||
if (!body.query) {
|
||||
return c.json({ error: 'Field "query" is required' }, 400);
|
||||
}
|
||||
|
||||
const limit = Math.min(body.limit ?? 20, 100);
|
||||
let filtered = skills;
|
||||
|
||||
if (body.filters) {
|
||||
if (body.filters.tags?.length) {
|
||||
filtered = filtered.filter((s) =>
|
||||
body.filters!.tags!.some((t) => s.tags?.includes(t)),
|
||||
);
|
||||
}
|
||||
if (body.filters.category) {
|
||||
filtered = filtered.filter((s) => s.category === body.filters!.category);
|
||||
}
|
||||
if (body.filters.source) {
|
||||
filtered = filtered.filter((s) => s.source.includes(body.filters!.source!));
|
||||
}
|
||||
}
|
||||
|
||||
const filteredMap = new Map(filtered.map((s) => [`${s.source}:${s.name}`, s]));
|
||||
|
||||
const ranked = ranker.rank(
|
||||
filtered.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: s.content,
|
||||
stars: s.stars,
|
||||
installs: s.installs,
|
||||
source: s.source,
|
||||
})),
|
||||
body.query,
|
||||
);
|
||||
|
||||
const results: ApiSkill[] = ranked.slice(0, limit).map((r) => {
|
||||
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
|
||||
const original = filteredMap.get(key) ?? filtered.find((s) => s.name === r.skill.name)!;
|
||||
if (!body.include_content) {
|
||||
const { content: _, ...rest } = original;
|
||||
return rest;
|
||||
}
|
||||
return original;
|
||||
});
|
||||
|
||||
const response: SearchResponse = {
|
||||
skills: results,
|
||||
total: ranked.length,
|
||||
query: body.query,
|
||||
limit,
|
||||
};
|
||||
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { ApiSkill } from '../types.js';
|
||||
|
||||
export function skillRoutes(skills: ApiSkill[]) {
|
||||
const app = new Hono();
|
||||
|
||||
app.get('/skills/:owner/:repo/:id', (c) => {
|
||||
const source = `${c.req.param('owner')}/${c.req.param('repo')}`;
|
||||
const id = c.req.param('id');
|
||||
|
||||
const skill = skills.find(
|
||||
(s) => s.source === source && s.name === id,
|
||||
);
|
||||
|
||||
if (!skill) {
|
||||
return c.json({ error: `Skill not found: ${source}/${id}` }, 404);
|
||||
}
|
||||
|
||||
return c.json(skill);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { ApiSkill, TrendingResponse } from '../types.js';
|
||||
import { RelevanceRanker } from '@skillkit/core';
|
||||
|
||||
export function trendingRoutes(skills: ApiSkill[]) {
|
||||
const app = new Hono();
|
||||
const ranker = new RelevanceRanker();
|
||||
|
||||
app.get('/trending', (c) => {
|
||||
const parsedLimit = parseInt(c.req.query('limit') || '20', 10);
|
||||
const limit = Math.min(Number.isNaN(parsedLimit) ? 20 : parsedLimit, 100);
|
||||
|
||||
const skillMap = new Map(skills.map((s) => [`${s.source}:${s.name}`, s]));
|
||||
|
||||
const ranked = ranker.rank(
|
||||
skills.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: s.content,
|
||||
stars: s.stars,
|
||||
installs: s.installs,
|
||||
references: [],
|
||||
source: s.source,
|
||||
})),
|
||||
);
|
||||
|
||||
const results = ranked.slice(0, limit).map((r) => {
|
||||
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
|
||||
const original = skillMap.get(key) ?? skills.find((s) => s.name === r.skill.name)!;
|
||||
const { content: _, ...rest } = original;
|
||||
return rest;
|
||||
});
|
||||
|
||||
const response: TrendingResponse = { skills: results, limit };
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
import { Hono } from 'hono';
|
||||
import { cors } from 'hono/cors';
|
||||
import { MemoryCache } from '@skillkit/core';
|
||||
import { rateLimiter } from './middleware/rate-limit.js';
|
||||
import { healthRoutes } from './routes/health.js';
|
||||
import { searchRoutes } from './routes/search.js';
|
||||
import { skillRoutes } from './routes/skills.js';
|
||||
import { trendingRoutes } from './routes/trending.js';
|
||||
import { categoryRoutes } from './routes/categories.js';
|
||||
import type { ApiSkill, SearchResponse } from './types.js';
|
||||
|
||||
export interface ServerOptions {
|
||||
port?: number;
|
||||
host?: string;
|
||||
corsOrigin?: string;
|
||||
cacheTtlMs?: number;
|
||||
skills?: ApiSkill[];
|
||||
rateLimitMax?: number;
|
||||
}
|
||||
|
||||
export function createApp(options: ServerOptions = {}) {
|
||||
const skills = options.skills || [];
|
||||
const cache = new MemoryCache<SearchResponse>({
|
||||
maxSize: 500,
|
||||
ttlMs: options.cacheTtlMs ?? 86_400_000,
|
||||
});
|
||||
|
||||
const app = new Hono();
|
||||
|
||||
app.use('*', cors({ origin: options.corsOrigin || '*' }));
|
||||
app.use('*', rateLimiter(options.rateLimitMax ?? 60));
|
||||
|
||||
app.route('/', healthRoutes(skills.length, cache));
|
||||
app.route('/', searchRoutes(skills, cache));
|
||||
app.route('/', skillRoutes(skills));
|
||||
app.route('/', trendingRoutes(skills));
|
||||
app.route('/', categoryRoutes(skills));
|
||||
|
||||
return { app, cache };
|
||||
}
|
||||
|
||||
export async function startServer(options: ServerOptions = {}) {
|
||||
const port = options.port ?? 3737;
|
||||
const host = options.host ?? '0.0.0.0';
|
||||
const { app, cache } = createApp(options);
|
||||
|
||||
const { serve } = await import('@hono/node-server');
|
||||
|
||||
const server = serve({ fetch: app.fetch, port, hostname: host }, () => {
|
||||
console.log(`SkillKit API server running at http://${host}:${port}`);
|
||||
console.log(`Skills loaded: ${options.skills?.length ?? 0}`);
|
||||
});
|
||||
|
||||
return { server, app, cache };
|
||||
}
|
||||
@@ -0,0 +1,48 @@
|
||||
export interface ApiSkill {
|
||||
name: string;
|
||||
description?: string;
|
||||
source: string;
|
||||
repo?: string;
|
||||
tags?: string[];
|
||||
category?: string;
|
||||
content?: string;
|
||||
stars?: number;
|
||||
installs?: number;
|
||||
}
|
||||
|
||||
export interface SearchResponse {
|
||||
skills: ApiSkill[];
|
||||
total: number;
|
||||
query: string;
|
||||
limit: number;
|
||||
}
|
||||
|
||||
export interface HealthResponse {
|
||||
status: 'ok';
|
||||
version: string;
|
||||
skillCount: number;
|
||||
uptime: number;
|
||||
}
|
||||
|
||||
export interface CacheStatsResponse {
|
||||
hits: number;
|
||||
misses: number;
|
||||
size: number;
|
||||
maxSize: number;
|
||||
hitRate: number;
|
||||
}
|
||||
|
||||
export interface TrendingResponse {
|
||||
skills: ApiSkill[];
|
||||
limit: number;
|
||||
}
|
||||
|
||||
export interface CategoryCount {
|
||||
name: string;
|
||||
count: number;
|
||||
}
|
||||
|
||||
export interface CategoriesResponse {
|
||||
categories: CategoryCount[];
|
||||
total: number;
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"composite": false
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist", "**/*.test.ts"]
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
import { defineConfig } from 'tsup';
|
||||
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
format: ['esm'],
|
||||
target: 'node18',
|
||||
outDir: 'dist',
|
||||
clean: true,
|
||||
dts: true,
|
||||
sourcemap: true,
|
||||
splitting: false,
|
||||
skipNodeModulesBundle: true,
|
||||
platform: 'node',
|
||||
banner: {
|
||||
js: '#!/usr/bin/env node',
|
||||
},
|
||||
});
|
||||
@@ -22,6 +22,7 @@
|
||||
},
|
||||
"dependencies": {
|
||||
"@clack/prompts": "^0.11.0",
|
||||
"@skillkit/api": "workspace:*",
|
||||
"@skillkit/core": "workspace:*",
|
||||
"@skillkit/agents": "workspace:*",
|
||||
"@skillkit/resources": "workspace:*",
|
||||
|
||||
@@ -114,3 +114,6 @@ export { QuickCommand } from './quick.js';
|
||||
|
||||
// SKILL.md ecosystem
|
||||
export { SkillMdValidateCommand, SkillMdInitCommand, SkillMdCheckCommand } from './skillmd.js';
|
||||
|
||||
// API server
|
||||
export { ServeCommand } from './serve.js';
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
import { Command, Option } from 'clipanion';
|
||||
import {
|
||||
colors,
|
||||
header,
|
||||
step,
|
||||
} from '../onboarding/index.js';
|
||||
|
||||
import skillsData from '../../../../marketplace/skills.json' with { type: 'json' };
|
||||
|
||||
export class ServeCommand extends Command {
|
||||
static override paths = [['serve'], ['server']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Start the SkillKit REST API server for skill discovery',
|
||||
details: `
|
||||
Launches a local HTTP server that exposes the SkillKit skill catalog
|
||||
via a REST API. Useful for integrating with other tools, building
|
||||
custom UIs, or enabling agent-native skill discovery.
|
||||
`,
|
||||
examples: [
|
||||
['Start server on default port', '$0 serve'],
|
||||
['Start on custom port', '$0 serve --port 8080'],
|
||||
['Start with custom CORS', '$0 serve --cors "http://localhost:3000"'],
|
||||
],
|
||||
});
|
||||
|
||||
port = Option.String('--port,-p', '3737', {
|
||||
description: 'Port to listen on',
|
||||
});
|
||||
|
||||
host = Option.String('--host,-H', '0.0.0.0', {
|
||||
description: 'Host to bind to',
|
||||
});
|
||||
|
||||
corsOrigin = Option.String('--cors', '*', {
|
||||
description: 'CORS allowed origin',
|
||||
});
|
||||
|
||||
cacheTtl = Option.String('--cache-ttl', '86400000', {
|
||||
description: 'Cache TTL in milliseconds',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
header('SkillKit API Server');
|
||||
|
||||
const skills = (skillsData.skills || []).map((skill: Record<string, unknown>) => ({
|
||||
name: skill.name as string,
|
||||
description: skill.description as string | undefined,
|
||||
source: (skill.source as string) || '',
|
||||
repo: skill.repo as string | undefined,
|
||||
tags: skill.tags as string[] | undefined,
|
||||
category: skill.category as string | undefined,
|
||||
}));
|
||||
|
||||
step(`Loading ${skills.length} skills from marketplace`);
|
||||
|
||||
const portNum = parseInt(this.port, 10) || 3737;
|
||||
const cacheTtlMs = parseInt(this.cacheTtl, 10) || 86_400_000;
|
||||
|
||||
try {
|
||||
const { startServer } = await import('@skillkit/api');
|
||||
|
||||
await startServer({
|
||||
port: portNum,
|
||||
host: this.host,
|
||||
corsOrigin: this.corsOrigin,
|
||||
cacheTtlMs,
|
||||
skills,
|
||||
});
|
||||
|
||||
step(`Server running at ${colors.cyan(`http://${this.host}:${portNum}`)}`);
|
||||
console.log('');
|
||||
console.log(colors.muted('Endpoints:'));
|
||||
console.log(colors.muted(` GET /health - Server health check`));
|
||||
console.log(colors.muted(` GET /search?q=... - Search skills`));
|
||||
console.log(colors.muted(` POST /search - Search with filters`));
|
||||
console.log(colors.muted(` GET /skills/:o/:r/:id - Get specific skill`));
|
||||
console.log(colors.muted(` GET /trending - Top skills`));
|
||||
console.log(colors.muted(` GET /categories - Skill categories`));
|
||||
console.log(colors.muted(` GET /cache/stats - Cache statistics`));
|
||||
console.log('');
|
||||
console.log(colors.muted('Press Ctrl+C to stop'));
|
||||
|
||||
await new Promise(() => {});
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : String(err);
|
||||
console.error(colors.error(`Failed to start server: ${message}`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
import { describe, it, expect, beforeEach, vi } from 'vitest';
|
||||
import { MemoryCache } from '../memory.js';
|
||||
|
||||
describe('MemoryCache', () => {
|
||||
let cache: MemoryCache<string>;
|
||||
|
||||
beforeEach(() => {
|
||||
cache = new MemoryCache<string>({ maxSize: 3, ttlMs: 1000 });
|
||||
});
|
||||
|
||||
it('stores and retrieves values', () => {
|
||||
cache.set('a', 'value-a');
|
||||
expect(cache.get('a')).toBe('value-a');
|
||||
});
|
||||
|
||||
it('returns undefined for missing keys', () => {
|
||||
expect(cache.get('missing')).toBeUndefined();
|
||||
});
|
||||
|
||||
it('deletes entries', () => {
|
||||
cache.set('a', 'value-a');
|
||||
expect(cache.delete('a')).toBe(true);
|
||||
expect(cache.get('a')).toBeUndefined();
|
||||
});
|
||||
|
||||
it('checks existence with has()', () => {
|
||||
cache.set('a', 'value-a');
|
||||
expect(cache.has('a')).toBe(true);
|
||||
expect(cache.has('b')).toBe(false);
|
||||
});
|
||||
|
||||
it('clears all entries', () => {
|
||||
cache.set('a', '1');
|
||||
cache.set('b', '2');
|
||||
cache.clear();
|
||||
expect(cache.has('a')).toBe(false);
|
||||
expect(cache.stats().size).toBe(0);
|
||||
});
|
||||
|
||||
it('evicts LRU when at capacity', () => {
|
||||
vi.useFakeTimers();
|
||||
try {
|
||||
cache.set('a', '1');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.set('b', '2');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.set('c', '3');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.get('a');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.get('b');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.set('d', '4');
|
||||
expect(cache.has('c')).toBe(false);
|
||||
expect(cache.has('a')).toBe(true);
|
||||
expect(cache.has('d')).toBe(true);
|
||||
} finally {
|
||||
vi.useRealTimers();
|
||||
}
|
||||
});
|
||||
|
||||
it('expires entries after TTL', () => {
|
||||
vi.useFakeTimers();
|
||||
try {
|
||||
cache.set('a', 'value');
|
||||
expect(cache.get('a')).toBe('value');
|
||||
vi.advanceTimersByTime(1001);
|
||||
expect(cache.get('a')).toBeUndefined();
|
||||
} finally {
|
||||
vi.useRealTimers();
|
||||
}
|
||||
});
|
||||
|
||||
it('tracks hit/miss stats', () => {
|
||||
cache.set('a', '1');
|
||||
cache.get('a');
|
||||
cache.get('missing');
|
||||
const stats = cache.stats();
|
||||
expect(stats.hits).toBe(1);
|
||||
expect(stats.misses).toBe(1);
|
||||
expect(stats.hitRate).toBe(0.5);
|
||||
expect(stats.size).toBe(1);
|
||||
expect(stats.maxSize).toBe(3);
|
||||
});
|
||||
|
||||
it('uses default options', () => {
|
||||
const defaultCache = new MemoryCache<string>();
|
||||
const stats = defaultCache.stats();
|
||||
expect(stats.maxSize).toBe(1000);
|
||||
});
|
||||
});
|
||||
Vendored
+2
@@ -0,0 +1,2 @@
|
||||
export * from './types.js';
|
||||
export * from './memory.js';
|
||||
Vendored
+101
@@ -0,0 +1,101 @@
|
||||
import type { CacheBackend, CacheOptions, CacheStats } from './types.js';
|
||||
|
||||
interface CacheEntry<V> {
|
||||
value: V;
|
||||
expiresAt: number;
|
||||
lastAccessed: number;
|
||||
}
|
||||
|
||||
const DEFAULT_MAX_SIZE = 1000;
|
||||
const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
|
||||
|
||||
export class MemoryCache<V = unknown> implements CacheBackend<V> {
|
||||
private store = new Map<string, CacheEntry<V>>();
|
||||
private maxSize: number;
|
||||
private ttlMs: number;
|
||||
private hitCount = 0;
|
||||
private missCount = 0;
|
||||
|
||||
constructor(options?: CacheOptions) {
|
||||
this.maxSize = options?.maxSize ?? DEFAULT_MAX_SIZE;
|
||||
this.ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
|
||||
}
|
||||
|
||||
get(key: string): V | undefined {
|
||||
const entry = this.store.get(key);
|
||||
if (!entry) {
|
||||
this.missCount++;
|
||||
return undefined;
|
||||
}
|
||||
|
||||
if (Date.now() > entry.expiresAt) {
|
||||
this.store.delete(key);
|
||||
this.missCount++;
|
||||
return undefined;
|
||||
}
|
||||
|
||||
entry.lastAccessed = Date.now();
|
||||
this.hitCount++;
|
||||
return entry.value;
|
||||
}
|
||||
|
||||
set(key: string, value: V): void {
|
||||
if (this.store.size >= this.maxSize && !this.store.has(key)) {
|
||||
this.evictLRU();
|
||||
}
|
||||
|
||||
const now = Date.now();
|
||||
this.store.set(key, {
|
||||
value,
|
||||
expiresAt: now + this.ttlMs,
|
||||
lastAccessed: now,
|
||||
});
|
||||
}
|
||||
|
||||
delete(key: string): boolean {
|
||||
return this.store.delete(key);
|
||||
}
|
||||
|
||||
has(key: string): boolean {
|
||||
const entry = this.store.get(key);
|
||||
if (!entry) return false;
|
||||
if (Date.now() > entry.expiresAt) {
|
||||
this.store.delete(key);
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
clear(): void {
|
||||
this.store.clear();
|
||||
this.hitCount = 0;
|
||||
this.missCount = 0;
|
||||
}
|
||||
|
||||
stats(): CacheStats {
|
||||
const total = this.hitCount + this.missCount;
|
||||
return {
|
||||
hits: this.hitCount,
|
||||
misses: this.missCount,
|
||||
size: this.store.size,
|
||||
maxSize: this.maxSize,
|
||||
hitRate: total > 0 ? this.hitCount / total : 0,
|
||||
};
|
||||
}
|
||||
|
||||
private evictLRU(): void {
|
||||
let oldestKey: string | null = null;
|
||||
let oldestTime = Infinity;
|
||||
|
||||
for (const [key, entry] of this.store) {
|
||||
if (entry.lastAccessed < oldestTime) {
|
||||
oldestTime = entry.lastAccessed;
|
||||
oldestKey = key;
|
||||
}
|
||||
}
|
||||
|
||||
if (oldestKey) {
|
||||
this.store.delete(oldestKey);
|
||||
}
|
||||
}
|
||||
}
|
||||
Vendored
+21
@@ -0,0 +1,21 @@
|
||||
export interface CacheStats {
|
||||
hits: number;
|
||||
misses: number;
|
||||
size: number;
|
||||
maxSize: number;
|
||||
hitRate: number;
|
||||
}
|
||||
|
||||
export interface CacheOptions {
|
||||
maxSize?: number;
|
||||
ttlMs?: number;
|
||||
}
|
||||
|
||||
export interface CacheBackend<V = unknown> {
|
||||
get(key: string): V | undefined;
|
||||
set(key: string, value: V): void;
|
||||
delete(key: string): boolean;
|
||||
has(key: string): boolean;
|
||||
clear(): void;
|
||||
stats(): CacheStats;
|
||||
}
|
||||
@@ -107,3 +107,16 @@ export * from './search/index.js';
|
||||
|
||||
// Federated Registry (External Skill Sources)
|
||||
export * from './registry/index.js';
|
||||
|
||||
// Pluggable Cache Backend
|
||||
export * from './cache/index.js';
|
||||
|
||||
// Multi-Signal Relevance Ranking
|
||||
export * from './ranking/index.js';
|
||||
|
||||
// Enhanced SKILL.md Parser (References & Frontmatter)
|
||||
export { discoverReferences, stripFrontmatter, parseSkillMd } from './parser/index.js';
|
||||
export type { SkillReference, ParsedSkillContent } from './parser/index.js';
|
||||
|
||||
// Runtime Skill Injection
|
||||
export * from './runtime/index.js';
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { stripFrontmatter, parseSkillMd, discoverReferences } from '../references.js';
|
||||
|
||||
vi.mock('node:fs', () => ({
|
||||
existsSync: vi.fn(),
|
||||
readdirSync: vi.fn(),
|
||||
statSync: vi.fn(),
|
||||
readFileSync: vi.fn(),
|
||||
}));
|
||||
|
||||
import { existsSync, readdirSync, statSync } from 'node:fs';
|
||||
|
||||
const mockExistsSync = vi.mocked(existsSync);
|
||||
const mockReaddirSync = vi.mocked(readdirSync);
|
||||
const mockStatSync = vi.mocked(statSync);
|
||||
|
||||
describe('stripFrontmatter', () => {
|
||||
it('extracts frontmatter and body', () => {
|
||||
const raw = `---
|
||||
name: my-skill
|
||||
version: 1.0
|
||||
---
|
||||
# My Skill
|
||||
|
||||
Content here.`;
|
||||
const result = stripFrontmatter(raw);
|
||||
expect(result.frontmatter.name).toBe('my-skill');
|
||||
expect(result.frontmatter.version).toBe('1.0');
|
||||
expect(result.body).toContain('# My Skill');
|
||||
expect(result.body).toContain('Content here.');
|
||||
});
|
||||
|
||||
it('returns empty frontmatter when no delimiters', () => {
|
||||
const raw = '# Just content\n\nNo frontmatter.';
|
||||
const result = stripFrontmatter(raw);
|
||||
expect(result.frontmatter).toEqual({});
|
||||
expect(result.body).toBe(raw);
|
||||
});
|
||||
|
||||
it('handles empty frontmatter block', () => {
|
||||
const raw = '---\n---\nBody text';
|
||||
const result = stripFrontmatter(raw);
|
||||
expect(result.frontmatter).toEqual({});
|
||||
expect(result.body).toBe('Body text');
|
||||
});
|
||||
});
|
||||
|
||||
describe('parseSkillMd', () => {
|
||||
it('parses raw content without skill dir', () => {
|
||||
const raw = `---
|
||||
name: test
|
||||
---
|
||||
Body content`;
|
||||
const result = parseSkillMd(raw);
|
||||
expect(result.frontmatter.name).toBe('test');
|
||||
expect(result.body).toBe('Body content');
|
||||
expect(result.references).toEqual([]);
|
||||
expect(result.raw).toBe(raw);
|
||||
});
|
||||
});
|
||||
|
||||
describe('discoverReferences', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it('finds files in reference directories', () => {
|
||||
mockExistsSync.mockImplementation((p) => {
|
||||
return String(p).endsWith('/examples');
|
||||
});
|
||||
mockStatSync.mockImplementation((p) => {
|
||||
const path = String(p);
|
||||
if (path.endsWith('/examples')) {
|
||||
return { isDirectory: () => true, isFile: () => false } as any;
|
||||
}
|
||||
return { isDirectory: () => false, isFile: () => true } as any;
|
||||
});
|
||||
mockReaddirSync.mockReturnValue(['demo.ts', 'readme.md'] as any);
|
||||
|
||||
const refs = discoverReferences('/fake/skill');
|
||||
expect(refs).toHaveLength(2);
|
||||
expect(refs[0]).toEqual({
|
||||
path: 'examples/demo.ts',
|
||||
type: 'example',
|
||||
name: 'demo.ts',
|
||||
});
|
||||
});
|
||||
|
||||
it('returns empty array when no reference dirs exist', () => {
|
||||
mockExistsSync.mockReturnValue(false);
|
||||
const refs = discoverReferences('/fake/skill');
|
||||
expect(refs).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1 @@
|
||||
export * from './references.js';
|
||||
@@ -0,0 +1,105 @@
|
||||
import { readdirSync, statSync, existsSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
|
||||
export interface SkillReference {
|
||||
path: string;
|
||||
type: 'example' | 'doc' | 'resource' | 'asset';
|
||||
name: string;
|
||||
}
|
||||
|
||||
export interface ParsedSkillContent {
|
||||
frontmatter: Record<string, unknown>;
|
||||
body: string;
|
||||
references: SkillReference[];
|
||||
raw: string;
|
||||
}
|
||||
|
||||
const REFERENCE_DIRS = ['references', 'resources', 'docs', 'examples', 'assets', 'scripts'];
|
||||
|
||||
const DIR_TYPE_MAP: Record<string, SkillReference['type']> = {
|
||||
references: 'resource',
|
||||
resources: 'resource',
|
||||
docs: 'doc',
|
||||
examples: 'example',
|
||||
assets: 'asset',
|
||||
scripts: 'resource',
|
||||
};
|
||||
|
||||
export function discoverReferences(skillDir: string): SkillReference[] {
|
||||
const refs: SkillReference[] = [];
|
||||
|
||||
for (const dir of REFERENCE_DIRS) {
|
||||
const fullPath = join(skillDir, dir);
|
||||
if (!existsSync(fullPath)) continue;
|
||||
|
||||
try {
|
||||
const stat = statSync(fullPath);
|
||||
if (!stat.isDirectory()) continue;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
const type = DIR_TYPE_MAP[dir] || 'resource';
|
||||
try {
|
||||
const entries = readdirSync(fullPath);
|
||||
for (const entry of entries) {
|
||||
const entryPath = join(fullPath, entry);
|
||||
try {
|
||||
const entryStat = statSync(entryPath);
|
||||
if (entryStat.isFile()) {
|
||||
refs.push({
|
||||
path: join(dir, entry),
|
||||
type,
|
||||
name: entry,
|
||||
});
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
return refs;
|
||||
}
|
||||
|
||||
export function stripFrontmatter(raw: string): { frontmatter: Record<string, unknown>; body: string } {
|
||||
const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
|
||||
if (!match) {
|
||||
const emptyMatch = raw.match(/^---\r?\n---\r?\n?([\s\S]*)$/);
|
||||
if (emptyMatch) {
|
||||
return { frontmatter: {}, body: emptyMatch[1] };
|
||||
}
|
||||
return { frontmatter: {}, body: raw };
|
||||
}
|
||||
|
||||
const fmBlock = match[1];
|
||||
const body = match[2];
|
||||
|
||||
const frontmatter: Record<string, unknown> = {};
|
||||
for (const line of fmBlock.split('\n')) {
|
||||
const colonIdx = line.indexOf(':');
|
||||
if (colonIdx === -1) continue;
|
||||
const key = line.slice(0, colonIdx).trim();
|
||||
const value = line.slice(colonIdx + 1).trim();
|
||||
if (key) {
|
||||
frontmatter[key] = value;
|
||||
}
|
||||
}
|
||||
|
||||
return { frontmatter, body };
|
||||
}
|
||||
|
||||
export function parseSkillMd(raw: string, skillDir?: string): ParsedSkillContent {
|
||||
const { frontmatter, body } = stripFrontmatter(raw);
|
||||
const references = skillDir ? discoverReferences(skillDir) : [];
|
||||
|
||||
return {
|
||||
frontmatter,
|
||||
body,
|
||||
references,
|
||||
raw,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,85 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { RelevanceRanker } from '../relevance.js';
|
||||
import type { RankableSkill } from '../relevance.js';
|
||||
|
||||
describe('RelevanceRanker', () => {
|
||||
const ranker = new RelevanceRanker();
|
||||
|
||||
const skills: RankableSkill[] = [
|
||||
{
|
||||
name: 'react-performance',
|
||||
description: 'Optimize React app performance',
|
||||
content: 'Full guide on React performance optimization',
|
||||
stars: 150,
|
||||
references: ['examples/demo.ts'],
|
||||
},
|
||||
{
|
||||
name: 'testing-basics',
|
||||
description: 'Unit testing fundamentals',
|
||||
stars: 10,
|
||||
},
|
||||
{
|
||||
name: 'empty-skill',
|
||||
},
|
||||
];
|
||||
|
||||
it('ranks skills by relevance score', () => {
|
||||
const results = ranker.rank(skills);
|
||||
expect(results).toHaveLength(3);
|
||||
expect(results[0].skill.name).toBe('react-performance');
|
||||
expect(results[0].score).toBeGreaterThan(results[1].score);
|
||||
});
|
||||
|
||||
it('gives max content score for description + content', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const full = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
expect(full.breakdown.contentAvailability).toBe(40);
|
||||
});
|
||||
|
||||
it('gives partial content score for description only', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const partial = results.find((r) => r.skill.name === 'testing-basics')!;
|
||||
expect(partial.breakdown.contentAvailability).toBe(20);
|
||||
});
|
||||
|
||||
it('gives zero content score for empty skill', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const empty = results.find((r) => r.skill.name === 'empty-skill')!;
|
||||
expect(empty.breakdown.contentAvailability).toBe(0);
|
||||
});
|
||||
|
||||
it('boosts exact name match on query', () => {
|
||||
const results = ranker.rank(skills, 'react-performance');
|
||||
const match = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
expect(match.breakdown.queryMatch).toBe(30);
|
||||
});
|
||||
|
||||
it('gives partial query match for substring', () => {
|
||||
const results = ranker.rank(skills, 'react');
|
||||
const match = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
expect(match.breakdown.queryMatch).toBeGreaterThan(0);
|
||||
expect(match.breakdown.queryMatch).toBeLessThan(30);
|
||||
});
|
||||
|
||||
it('scores popularity via log scale', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const popular = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
const less = results.find((r) => r.skill.name === 'testing-basics')!;
|
||||
expect(popular.breakdown.popularity).toBeGreaterThan(less.breakdown.popularity);
|
||||
});
|
||||
|
||||
it('scores references', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const withRefs = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
const noRefs = results.find((r) => r.skill.name === 'testing-basics')!;
|
||||
expect(withRefs.breakdown.referenceScore).toBeGreaterThan(0);
|
||||
expect(noRefs.breakdown.referenceScore).toBe(0);
|
||||
});
|
||||
|
||||
it('returns zero query match when no query provided', () => {
|
||||
const results = ranker.rank(skills);
|
||||
for (const r of results) {
|
||||
expect(r.breakdown.queryMatch).toBe(0);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1 @@
|
||||
export * from './relevance.js';
|
||||
@@ -0,0 +1,92 @@
|
||||
export interface RankableSkill {
|
||||
name: string;
|
||||
description?: string;
|
||||
content?: string;
|
||||
stars?: number;
|
||||
installs?: number;
|
||||
references?: string[];
|
||||
}
|
||||
|
||||
export interface RankedSkill<T extends RankableSkill = RankableSkill> {
|
||||
skill: T;
|
||||
score: number;
|
||||
breakdown: ScoreBreakdown;
|
||||
}
|
||||
|
||||
export interface ScoreBreakdown {
|
||||
contentAvailability: number;
|
||||
queryMatch: number;
|
||||
popularity: number;
|
||||
referenceScore: number;
|
||||
}
|
||||
|
||||
const WEIGHTS = {
|
||||
contentAvailability: 40,
|
||||
queryMatch: 30,
|
||||
popularity: 15,
|
||||
references: 15,
|
||||
} as const;
|
||||
|
||||
export class RelevanceRanker {
|
||||
rank<T extends RankableSkill>(skills: T[], query?: string): RankedSkill<T>[] {
|
||||
const results = skills.map((skill) => {
|
||||
const breakdown = this.score(skill, query);
|
||||
const score =
|
||||
breakdown.contentAvailability +
|
||||
breakdown.queryMatch +
|
||||
breakdown.popularity +
|
||||
breakdown.referenceScore;
|
||||
return { skill, score, breakdown };
|
||||
});
|
||||
|
||||
results.sort((a, b) => b.score - a.score);
|
||||
return results;
|
||||
}
|
||||
|
||||
private score(skill: RankableSkill, query?: string): ScoreBreakdown {
|
||||
return {
|
||||
contentAvailability: this.scoreContent(skill),
|
||||
queryMatch: query ? this.scoreQuery(skill, query) : 0,
|
||||
popularity: this.scorePopularity(skill),
|
||||
referenceScore: this.scoreReferences(skill),
|
||||
};
|
||||
}
|
||||
|
||||
private scoreContent(skill: RankableSkill): number {
|
||||
let score = 0;
|
||||
if (skill.description && skill.description.length > 0) score += 20;
|
||||
if (skill.content && skill.content.length > 0) score += 20;
|
||||
return score;
|
||||
}
|
||||
|
||||
private scoreQuery(skill: RankableSkill, query: string): number {
|
||||
const q = query.toLowerCase();
|
||||
const name = skill.name.toLowerCase();
|
||||
|
||||
if (name === q) return WEIGHTS.queryMatch;
|
||||
|
||||
if (name.includes(q) || q.includes(name)) {
|
||||
return WEIGHTS.queryMatch * 0.7;
|
||||
}
|
||||
|
||||
const desc = (skill.description || '').toLowerCase();
|
||||
const content = (skill.content || '').toLowerCase();
|
||||
const searchable = `${name} ${desc} ${content}`;
|
||||
const words = q.split(/\s+/).filter(Boolean);
|
||||
const matched = words.filter((w) => searchable.includes(w)).length;
|
||||
|
||||
if (words.length === 0) return 0;
|
||||
return Math.round(WEIGHTS.queryMatch * (matched / words.length) * 0.6);
|
||||
}
|
||||
|
||||
private scorePopularity(skill: RankableSkill): number {
|
||||
const count = (skill.stars ?? 0) + (skill.installs ?? 0);
|
||||
if (count <= 0) return 0;
|
||||
return Math.min(WEIGHTS.popularity, Math.round(Math.log10(count + 1) * 5));
|
||||
}
|
||||
|
||||
private scoreReferences(skill: RankableSkill): number {
|
||||
if (!skill.references || skill.references.length === 0) return 0;
|
||||
return Math.min(WEIGHTS.references, skill.references.length * 5);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,87 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { CommunityRegistry } from '../community.js';
|
||||
|
||||
vi.mock('node:fs', () => ({
|
||||
existsSync: vi.fn(),
|
||||
readFileSync: vi.fn(),
|
||||
}));
|
||||
|
||||
import { existsSync, readFileSync } from 'node:fs';
|
||||
|
||||
const mockExistsSync = vi.mocked(existsSync);
|
||||
const mockReadFileSync = vi.mocked(readFileSync);
|
||||
|
||||
const SAMPLE_SKILLS_MD = `# SkillKit Community Skills Registry
|
||||
|
||||
## Code Quality
|
||||
|
||||
- [code-simplifier](https://github.com/anthropics/skills) - Simplifies and refines code
|
||||
- [code-review](https://github.com/anthropics/skills) - Automated code review
|
||||
|
||||
## Testing
|
||||
|
||||
- [testing-guide](https://github.com/anthropics/skills) - Unit testing fundamentals
|
||||
- [e2e-testing](https://github.com/anthropics/skills) - End-to-end testing with Playwright
|
||||
`;
|
||||
|
||||
describe('CommunityRegistry', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mockExistsSync.mockReturnValue(true);
|
||||
mockReadFileSync.mockReturnValue(SAMPLE_SKILLS_MD);
|
||||
});
|
||||
|
||||
it('parses SKILLS.md entries', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('code');
|
||||
expect(results.length).toBeGreaterThan(0);
|
||||
expect(results[0].registry).toBe('community');
|
||||
expect(results[0].name).toBe('code-simplifier');
|
||||
});
|
||||
|
||||
it('searches by description', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('Playwright');
|
||||
expect(results.length).toBe(1);
|
||||
expect(results[0].name).toBe('e2e-testing');
|
||||
});
|
||||
|
||||
it('searches by category', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('Testing');
|
||||
expect(results.length).toBe(2);
|
||||
});
|
||||
|
||||
it('respects limit', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('code', { limit: 1 });
|
||||
expect(results.length).toBe(1);
|
||||
});
|
||||
|
||||
it('returns empty when no match', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('nonexistent-xyz');
|
||||
expect(results.length).toBe(0);
|
||||
});
|
||||
|
||||
it('getAll returns all entries', () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const all = registry.getAll();
|
||||
expect(all.length).toBe(4);
|
||||
});
|
||||
|
||||
it('getCategories returns unique categories', () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const cats = registry.getCategories();
|
||||
expect(cats).toContain('Code Quality');
|
||||
expect(cats).toContain('Testing');
|
||||
expect(cats.length).toBe(2);
|
||||
});
|
||||
|
||||
it('handles missing file gracefully', async () => {
|
||||
mockExistsSync.mockReturnValue(false);
|
||||
const registry = new CommunityRegistry('/missing/SKILLS.md');
|
||||
const results = await registry.search('anything');
|
||||
expect(results).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,97 @@
|
||||
import { readFileSync, existsSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import type { ExternalRegistry, ExternalSkill } from './index.js';
|
||||
|
||||
interface ParsedEntry {
|
||||
name: string;
|
||||
url: string;
|
||||
description: string;
|
||||
category: string;
|
||||
}
|
||||
|
||||
export class CommunityRegistry implements ExternalRegistry {
|
||||
name = 'community';
|
||||
private entries: ParsedEntry[] = [];
|
||||
private loaded = false;
|
||||
|
||||
constructor(private skillsMdPath?: string) {}
|
||||
|
||||
private load(): void {
|
||||
if (this.loaded) return;
|
||||
this.loaded = true;
|
||||
|
||||
const paths = this.skillsMdPath
|
||||
? [this.skillsMdPath]
|
||||
: [
|
||||
join(process.cwd(), 'registry', 'SKILLS.md'),
|
||||
join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..', 'registry', 'SKILLS.md'),
|
||||
];
|
||||
|
||||
for (const path of paths) {
|
||||
if (!existsSync(path)) continue;
|
||||
try {
|
||||
const content = readFileSync(path, 'utf-8');
|
||||
this.entries = this.parse(content);
|
||||
return;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private parse(content: string): ParsedEntry[] {
|
||||
const results: ParsedEntry[] = [];
|
||||
let currentCategory = '';
|
||||
|
||||
for (const line of content.split('\n')) {
|
||||
const headerMatch = line.match(/^##\s+(.+)/);
|
||||
if (headerMatch) {
|
||||
currentCategory = headerMatch[1].trim();
|
||||
continue;
|
||||
}
|
||||
|
||||
const entryMatch = line.match(/^-\s+\[([^\]]+)\]\(([^)]+)\)\s*-\s*(.+)/);
|
||||
if (entryMatch) {
|
||||
results.push({
|
||||
name: entryMatch[1].trim(),
|
||||
url: entryMatch[2].trim(),
|
||||
description: entryMatch[3].trim(),
|
||||
category: currentCategory,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
async search(query: string, options?: { limit?: number }): Promise<ExternalSkill[]> {
|
||||
this.load();
|
||||
const limit = options?.limit ?? 20;
|
||||
const q = query.toLowerCase();
|
||||
|
||||
const matched = this.entries.filter(
|
||||
(e) =>
|
||||
e.name.toLowerCase().includes(q) ||
|
||||
e.description.toLowerCase().includes(q) ||
|
||||
e.category.toLowerCase().includes(q),
|
||||
);
|
||||
|
||||
return matched.slice(0, limit).map((e) => ({
|
||||
name: e.name,
|
||||
description: e.description,
|
||||
source: e.url,
|
||||
registry: this.name,
|
||||
}));
|
||||
}
|
||||
|
||||
getAll(): ParsedEntry[] {
|
||||
this.load();
|
||||
return [...this.entries];
|
||||
}
|
||||
|
||||
getCategories(): string[] {
|
||||
this.load();
|
||||
return [...new Set(this.entries.map((e) => e.category))];
|
||||
}
|
||||
}
|
||||
@@ -115,6 +115,8 @@ export class GitHubSkillRegistry implements ExternalRegistry {
|
||||
}
|
||||
}
|
||||
|
||||
export { CommunityRegistry } from './community.js';
|
||||
|
||||
export class FederatedSearch {
|
||||
private registries: ExternalRegistry[] = [];
|
||||
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
|
||||
import { SkillInjector } from '../injector.js';
|
||||
|
||||
const mockFetch = vi.fn();
|
||||
global.fetch = mockFetch;
|
||||
|
||||
describe('SkillInjector', () => {
|
||||
let injector: SkillInjector;
|
||||
|
||||
beforeEach(() => {
|
||||
injector = new SkillInjector(60_000);
|
||||
mockFetch.mockReset();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
injector.clearCache();
|
||||
});
|
||||
|
||||
const skillMd = `---
|
||||
name: test-skill
|
||||
version: 1.0
|
||||
---
|
||||
# Test Skill
|
||||
|
||||
This is the body content.`;
|
||||
|
||||
it('fetches and parses a SKILL.md from GitHub', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
const result = await injector.fetch('owner/repo', 'test-skill');
|
||||
expect(result.source).toEqual({ owner: 'owner', repo: 'repo' });
|
||||
expect(result.skillId).toBe('test-skill');
|
||||
expect(result.parsed.frontmatter.name).toBe('test-skill');
|
||||
expect(result.parsed.body).toContain('# Test Skill');
|
||||
expect(result.fetchedAt).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('returns cached result on subsequent calls', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
await injector.fetch('owner/repo', 'test-skill');
|
||||
const second = await injector.fetch('owner/repo', 'test-skill');
|
||||
expect(mockFetch).toHaveBeenCalledTimes(1);
|
||||
expect(second.parsed.body).toContain('# Test Skill');
|
||||
});
|
||||
|
||||
it('inject() returns body without frontmatter', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
const body = await injector.inject('owner/repo', 'test-skill');
|
||||
expect(body).toContain('# Test Skill');
|
||||
expect(body).not.toContain('---');
|
||||
expect(body).not.toContain('name: test-skill');
|
||||
});
|
||||
|
||||
it('throws on invalid source format', async () => {
|
||||
await expect(injector.fetch('invalid', 'skill')).rejects.toThrow('Invalid source format');
|
||||
});
|
||||
|
||||
it('throws when SKILL.md not found after trying all paths', async () => {
|
||||
mockFetch.mockResolvedValue({ ok: false, status: 404 });
|
||||
|
||||
await expect(injector.fetch('owner/repo', 'missing')).rejects.toThrow('SKILL.md not found');
|
||||
});
|
||||
|
||||
it('tries multiple paths before failing', async () => {
|
||||
mockFetch
|
||||
.mockResolvedValueOnce({ ok: false, status: 404 })
|
||||
.mockResolvedValueOnce({ ok: false, status: 404 })
|
||||
.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
const result = await injector.fetch('owner/repo', 'skill');
|
||||
expect(mockFetch).toHaveBeenCalledTimes(3);
|
||||
expect(result.parsed.body).toContain('# Test Skill');
|
||||
});
|
||||
|
||||
it('reports cache stats', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
await injector.fetch('owner/repo', 'skill');
|
||||
await injector.fetch('owner/repo', 'skill');
|
||||
|
||||
const stats = injector.cacheStats();
|
||||
expect(stats.size).toBe(1);
|
||||
expect(stats.hits).toBe(1);
|
||||
expect(stats.misses).toBe(1);
|
||||
});
|
||||
|
||||
it('parses full GitHub URLs as source', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
const result = await injector.fetch('https://github.com/owner/repo', 'skill');
|
||||
expect(result.source).toEqual({ owner: 'owner', repo: 'repo' });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1 @@
|
||||
export * from './injector.js';
|
||||
@@ -0,0 +1,99 @@
|
||||
import { MemoryCache } from '../cache/memory.js';
|
||||
import { parseSkillMd } from '../parser/references.js';
|
||||
import type { ParsedSkillContent } from '../parser/references.js';
|
||||
|
||||
export interface RuntimeSkillSource {
|
||||
owner: string;
|
||||
repo: string;
|
||||
}
|
||||
|
||||
export interface FetchedSkill {
|
||||
source: RuntimeSkillSource;
|
||||
skillId: string;
|
||||
parsed: ParsedSkillContent;
|
||||
fetchedAt: number;
|
||||
}
|
||||
|
||||
function parseSource(source: string): RuntimeSkillSource {
|
||||
const parts = source.replace(/^https?:\/\/github\.com\//, '').split('/');
|
||||
if (parts.length < 2) {
|
||||
throw new Error(`Invalid source format: "${source}". Expected "owner/repo".`);
|
||||
}
|
||||
return { owner: parts[0], repo: parts[1] };
|
||||
}
|
||||
|
||||
export class SkillInjector {
|
||||
private cache: MemoryCache<FetchedSkill>;
|
||||
|
||||
constructor(cacheTtlMs?: number) {
|
||||
this.cache = new MemoryCache<FetchedSkill>({
|
||||
maxSize: 200,
|
||||
ttlMs: cacheTtlMs ?? 24 * 60 * 60 * 1000,
|
||||
});
|
||||
}
|
||||
|
||||
async fetch(source: string, skillId: string): Promise<FetchedSkill> {
|
||||
const cacheKey = `${source}:${skillId}`;
|
||||
const cached = this.cache.get(cacheKey);
|
||||
if (cached) return cached;
|
||||
|
||||
const { owner, repo } = parseSource(source);
|
||||
const raw = await this.fetchRawSkillMd(owner, repo, skillId);
|
||||
const parsed = parseSkillMd(raw);
|
||||
|
||||
const result: FetchedSkill = {
|
||||
source: { owner, repo },
|
||||
skillId,
|
||||
parsed,
|
||||
fetchedAt: Date.now(),
|
||||
};
|
||||
|
||||
this.cache.set(cacheKey, result);
|
||||
return result;
|
||||
}
|
||||
|
||||
async inject(source: string, skillId: string): Promise<string> {
|
||||
const fetched = await this.fetch(source, skillId);
|
||||
return fetched.parsed.body;
|
||||
}
|
||||
|
||||
private async fetchRawSkillMd(owner: string, repo: string, skillId: string): Promise<string> {
|
||||
const paths = [
|
||||
`${skillId}/SKILL.md`,
|
||||
`skills/${skillId}/SKILL.md`,
|
||||
`SKILL.md`,
|
||||
];
|
||||
|
||||
const headers: Record<string, string> = {
|
||||
Accept: 'application/vnd.github.v3.raw',
|
||||
'User-Agent': 'skillkit-runtime',
|
||||
};
|
||||
|
||||
const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
|
||||
if (token) {
|
||||
headers.Authorization = `Bearer ${token}`;
|
||||
}
|
||||
|
||||
for (const path of paths) {
|
||||
const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}`;
|
||||
try {
|
||||
const response = await fetch(url, { headers });
|
||||
if (response.ok) {
|
||||
return await response.text();
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`SKILL.md not found in ${owner}/${repo} for skill "${skillId}"`);
|
||||
}
|
||||
|
||||
clearCache(): void {
|
||||
this.cache.clear();
|
||||
}
|
||||
|
||||
cacheStats() {
|
||||
return this.cache.stats();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
{
|
||||
"name": "@skillkit/mcp",
|
||||
"version": "1.11.0",
|
||||
"description": "MCP server for SkillKit skill discovery — agent-native skill search",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts",
|
||||
"bin": {
|
||||
"skillkit-mcp": "./dist/index.js"
|
||||
},
|
||||
"exports": {
|
||||
".": {
|
||||
"import": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts"
|
||||
}
|
||||
},
|
||||
"files": [
|
||||
"dist"
|
||||
],
|
||||
"scripts": {
|
||||
"build": "tsup",
|
||||
"dev": "tsup --watch",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"test": "vitest run",
|
||||
"start": "node dist/index.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"@modelcontextprotocol/sdk": "^1.0.0",
|
||||
"@skillkit/core": "workspace:*",
|
||||
"zod": "^3.24.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.10.5",
|
||||
"tsup": "^8.3.5",
|
||||
"typescript": "^5.7.2",
|
||||
"vitest": "^2.1.8"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18.0.0"
|
||||
},
|
||||
"license": "Apache-2.0",
|
||||
"keywords": [
|
||||
"mcp",
|
||||
"model-context-protocol",
|
||||
"skillkit",
|
||||
"skills",
|
||||
"discovery",
|
||||
"ai",
|
||||
"agents",
|
||||
"claude"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
handleSearchSkills,
|
||||
handleGetSkill,
|
||||
handleRecommendSkills,
|
||||
handleListCategories,
|
||||
} from '../tools.js';
|
||||
import type { SkillEntry } from '../tools.js';
|
||||
|
||||
const testSkills: SkillEntry[] = [
|
||||
{ name: 'react-perf', description: 'React performance tips', source: 'owner/repo', tags: ['react', 'performance'] },
|
||||
{ name: 'testing-guide', description: 'Unit testing guide', source: 'owner/repo2', tags: ['testing'] },
|
||||
{ name: 'nextjs-auth', description: 'Next.js authentication', source: 'other/repo', tags: ['nextjs', 'auth'], category: 'framework' },
|
||||
];
|
||||
|
||||
describe('handleSearchSkills', () => {
|
||||
it('returns ranked results for query', () => {
|
||||
const result = handleSearchSkills(testSkills, { query: 'react', limit: 10 });
|
||||
const data = JSON.parse(result.content[0].text);
|
||||
expect(data.skills.length).toBeGreaterThan(0);
|
||||
expect(data.query).toBe('react');
|
||||
expect(data.total).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('applies tag filters', () => {
|
||||
const result = handleSearchSkills(testSkills, {
|
||||
query: 'guide',
|
||||
limit: 10,
|
||||
filters: { tags: ['testing'] },
|
||||
});
|
||||
const data = JSON.parse(result.content[0].text);
|
||||
expect(data.skills.length).toBeGreaterThanOrEqual(1);
|
||||
});
|
||||
|
||||
it('respects limit', () => {
|
||||
const result = handleSearchSkills(testSkills, { query: 'test', limit: 1 });
|
||||
const data = JSON.parse(result.content[0].text);
|
||||
expect(data.skills.length).toBeLessThanOrEqual(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('handleGetSkill', () => {
|
||||
it('returns a specific skill', () => {
|
||||
const result = handleGetSkill(testSkills, { source: 'owner/repo', skill_id: 'react-perf' });
|
||||
expect(result.isError).toBeUndefined();
|
||||
const data = JSON.parse(result.content[0].text);
|
||||
expect(data.name).toBe('react-perf');
|
||||
});
|
||||
|
||||
it('returns error for missing skill', () => {
|
||||
const result = handleGetSkill(testSkills, { source: 'owner/repo', skill_id: 'nonexistent' });
|
||||
expect(result.isError).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('handleRecommendSkills', () => {
|
||||
it('recommends based on languages', () => {
|
||||
const result = handleRecommendSkills(testSkills, { languages: ['react'], limit: 5 });
|
||||
const data = JSON.parse(result.content[0].text);
|
||||
expect(data.recommendations.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('recommends based on task description', () => {
|
||||
const result = handleRecommendSkills(testSkills, { task: 'testing react components', limit: 5 });
|
||||
const data = JSON.parse(result.content[0].text);
|
||||
expect(data.recommendations.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('errors with no input', () => {
|
||||
const result = handleRecommendSkills(testSkills, { limit: 5 });
|
||||
expect(result.isError).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('handleListCategories', () => {
|
||||
it('returns tag counts', () => {
|
||||
const result = handleListCategories(testSkills);
|
||||
const data = JSON.parse(result.content[0].text);
|
||||
expect(data.categories.length).toBeGreaterThan(0);
|
||||
expect(data.total).toBeGreaterThan(0);
|
||||
const react = data.categories.find((c: { name: string }) => c.name === 'react');
|
||||
expect(react?.count).toBe(1);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,223 @@
|
||||
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
||||
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import {
|
||||
CallToolRequestSchema,
|
||||
ListToolsRequestSchema,
|
||||
ListResourcesRequestSchema,
|
||||
ReadResourceRequestSchema,
|
||||
} from '@modelcontextprotocol/sdk/types.js';
|
||||
import {
|
||||
handleSearchSkills,
|
||||
handleGetSkill,
|
||||
handleRecommendSkills,
|
||||
handleListCategories,
|
||||
} from './tools.js';
|
||||
import type { SkillEntry } from './tools.js';
|
||||
import { getTrendingResource, getCategoriesResource } from './resources.js';
|
||||
|
||||
let skills: SkillEntry[] = [];
|
||||
|
||||
async function loadSkills(): Promise<SkillEntry[]> {
|
||||
const { readFileSync } = await import('node:fs');
|
||||
const { join, dirname } = await import('node:path');
|
||||
|
||||
const possiblePaths = [
|
||||
join(process.cwd(), 'marketplace', 'skills.json'),
|
||||
join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'marketplace', 'skills.json'),
|
||||
join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'marketplace', 'skills.json'),
|
||||
];
|
||||
|
||||
for (const path of possiblePaths) {
|
||||
try {
|
||||
const data = JSON.parse(readFileSync(path, 'utf-8'));
|
||||
if (data.skills && Array.isArray(data.skills)) {
|
||||
return data.skills.map((s: Record<string, unknown>) => ({
|
||||
name: s.name as string,
|
||||
description: s.description as string | undefined,
|
||||
source: (s.source as string) || '',
|
||||
repo: s.repo as string | undefined,
|
||||
tags: s.tags as string[] | undefined,
|
||||
category: s.category as string | undefined,
|
||||
}));
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
return [];
|
||||
}
|
||||
|
||||
const server = new Server(
|
||||
{
|
||||
name: 'skillkit-discovery',
|
||||
version: '1.11.0',
|
||||
},
|
||||
{
|
||||
capabilities: {
|
||||
tools: {},
|
||||
resources: {},
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
server.setRequestHandler(ListToolsRequestSchema, async () => {
|
||||
return {
|
||||
tools: [
|
||||
{
|
||||
name: 'search_skills',
|
||||
description: 'Search for AI agent skills by keyword, tag, or description. Returns ranked results from the SkillKit marketplace.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
query: { type: 'string', description: 'Search query' },
|
||||
limit: { type: 'number', minimum: 1, maximum: 50, default: 10, description: 'Max results' },
|
||||
include_content: { type: 'boolean', default: false, description: 'Include full content' },
|
||||
include_references: { type: 'boolean', default: false, description: 'Include references' },
|
||||
filters: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
tags: { type: 'array', items: { type: 'string' }, description: 'Filter by tags' },
|
||||
category: { type: 'string', description: 'Filter by category' },
|
||||
source: { type: 'string', description: 'Filter by source repo' },
|
||||
},
|
||||
},
|
||||
},
|
||||
required: ['query'],
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'get_skill',
|
||||
description: 'Get details of a specific skill by source and ID.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
source: { type: 'string', description: 'Skill source (e.g. owner/repo)' },
|
||||
skill_id: { type: 'string', description: 'Skill name' },
|
||||
include_references: { type: 'boolean', default: false, description: 'Include references' },
|
||||
},
|
||||
required: ['source', 'skill_id'],
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'recommend_skills',
|
||||
description: 'Get skill recommendations based on your tech stack and current task.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
languages: { type: 'array', items: { type: 'string' }, description: 'Programming languages' },
|
||||
frameworks: { type: 'array', items: { type: 'string' }, description: 'Frameworks' },
|
||||
libraries: { type: 'array', items: { type: 'string' }, description: 'Libraries' },
|
||||
task: { type: 'string', description: 'Current task description' },
|
||||
limit: { type: 'number', minimum: 1, maximum: 20, default: 5, description: 'Max results' },
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'list_categories',
|
||||
description: 'List all skill categories with their counts.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {},
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
});
|
||||
|
||||
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
||||
const { name, arguments: args } = request.params;
|
||||
|
||||
try {
|
||||
switch (name) {
|
||||
case 'search_skills':
|
||||
return handleSearchSkills(skills, args);
|
||||
case 'get_skill':
|
||||
return handleGetSkill(skills, args);
|
||||
case 'recommend_skills':
|
||||
return handleRecommendSkills(skills, args);
|
||||
case 'list_categories':
|
||||
return handleListCategories(skills);
|
||||
default:
|
||||
return {
|
||||
content: [{ type: 'text', text: `Unknown tool: ${name}` }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
} catch (error) {
|
||||
const message = error instanceof Error ? error.message : 'Unknown error';
|
||||
return {
|
||||
content: [{ type: 'text', text: `Error: ${message}` }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
});
|
||||
|
||||
server.setRequestHandler(ListResourcesRequestSchema, async () => {
|
||||
return {
|
||||
resources: [
|
||||
{
|
||||
uri: 'skills://trending',
|
||||
name: 'Trending Skills',
|
||||
description: 'Top trending skills by relevance score',
|
||||
mimeType: 'application/json',
|
||||
},
|
||||
{
|
||||
uri: 'skills://categories',
|
||||
name: 'Skill Categories',
|
||||
description: 'All skill categories with counts',
|
||||
mimeType: 'application/json',
|
||||
},
|
||||
],
|
||||
};
|
||||
});
|
||||
|
||||
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
|
||||
const { uri } = request.params;
|
||||
|
||||
if (uri === 'skills://trending') {
|
||||
return {
|
||||
contents: [
|
||||
{
|
||||
uri,
|
||||
mimeType: 'application/json',
|
||||
text: getTrendingResource(skills),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
if (uri === 'skills://categories') {
|
||||
return {
|
||||
contents: [
|
||||
{
|
||||
uri,
|
||||
mimeType: 'application/json',
|
||||
text: getCategoriesResource(skills),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
throw new Error(`Unknown resource: ${uri}`);
|
||||
});
|
||||
|
||||
async function main() {
|
||||
skills = await loadSkills();
|
||||
console.error(`SkillKit Discovery MCP Server starting (${skills.length} skills loaded)`);
|
||||
|
||||
const transport = new StdioServerTransport();
|
||||
await server.connect(transport);
|
||||
console.error('SkillKit Discovery MCP Server running on stdio');
|
||||
}
|
||||
|
||||
const isMain = process.argv[1] === fileURLToPath(import.meta.url);
|
||||
if (isMain) {
|
||||
main().catch((error) => {
|
||||
console.error('Fatal error:', error);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
|
||||
export { server };
|
||||
@@ -0,0 +1,48 @@
|
||||
import { RelevanceRanker } from '@skillkit/core';
|
||||
import type { SkillEntry } from './tools.js';
|
||||
|
||||
const ranker = new RelevanceRanker();
|
||||
|
||||
export function getTrendingResource(skills: SkillEntry[]) {
|
||||
const skillMap = new Map(skills.map((s) => [s.name, s]));
|
||||
|
||||
const ranked = ranker.rank(
|
||||
skills.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: s.content,
|
||||
})),
|
||||
);
|
||||
|
||||
const trending = ranked.slice(0, 20).map((r) => {
|
||||
const original = skillMap.get(r.skill.name);
|
||||
if (!original) return null;
|
||||
return {
|
||||
name: original.name,
|
||||
description: original.description,
|
||||
source: original.source,
|
||||
tags: original.tags,
|
||||
score: r.score,
|
||||
};
|
||||
}).filter(Boolean);
|
||||
|
||||
return JSON.stringify({ trending, count: trending.length }, null, 2);
|
||||
}
|
||||
|
||||
export function getCategoriesResource(skills: SkillEntry[]) {
|
||||
const tagCounts = new Map<string, number>();
|
||||
|
||||
for (const skill of skills) {
|
||||
if (skill.tags) {
|
||||
for (const tag of skill.tags) {
|
||||
tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const categories = Array.from(tagCounts.entries())
|
||||
.map(([name, count]) => ({ name, count }))
|
||||
.sort((a, b) => b.count - a.count);
|
||||
|
||||
return JSON.stringify({ categories, total: categories.length }, null, 2);
|
||||
}
|
||||
@@ -0,0 +1,169 @@
|
||||
import { RelevanceRanker } from '@skillkit/core';
|
||||
import {
|
||||
SearchSkillsInputSchema,
|
||||
GetSkillInputSchema,
|
||||
RecommendSkillsInputSchema,
|
||||
} from './types.js';
|
||||
|
||||
export interface SkillEntry {
|
||||
name: string;
|
||||
description?: string;
|
||||
source: string;
|
||||
repo?: string;
|
||||
tags?: string[];
|
||||
category?: string;
|
||||
content?: string;
|
||||
}
|
||||
|
||||
const ranker = new RelevanceRanker();
|
||||
|
||||
export function handleSearchSkills(skills: SkillEntry[], args: unknown) {
|
||||
const input = SearchSkillsInputSchema.parse(args);
|
||||
let filtered = skills;
|
||||
|
||||
if (input.filters) {
|
||||
if (input.filters.tags?.length) {
|
||||
filtered = filtered.filter((s) =>
|
||||
input.filters!.tags!.some((t) => s.tags?.includes(t)),
|
||||
);
|
||||
}
|
||||
if (input.filters.category) {
|
||||
filtered = filtered.filter((s) => s.category === input.filters!.category);
|
||||
}
|
||||
if (input.filters.source) {
|
||||
filtered = filtered.filter((s) => s.source.includes(input.filters!.source!));
|
||||
}
|
||||
}
|
||||
|
||||
const skillMap = new Map(filtered.map((s) => [`${s.source}:${s.name}`, s]));
|
||||
|
||||
const ranked = ranker.rank(
|
||||
filtered.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: s.content,
|
||||
source: s.source,
|
||||
})),
|
||||
input.query,
|
||||
);
|
||||
|
||||
const results = ranked.slice(0, input.limit).map((r) => {
|
||||
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
|
||||
const original = skillMap.get(key) ?? filtered.find((s) => s.name === r.skill.name)!;
|
||||
const result: Record<string, unknown> = {
|
||||
name: original.name,
|
||||
description: original.description,
|
||||
source: original.source,
|
||||
tags: original.tags,
|
||||
score: r.score,
|
||||
};
|
||||
if (input.include_content) result.content = original.content;
|
||||
return result;
|
||||
});
|
||||
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: 'text' as const,
|
||||
text: JSON.stringify({ skills: results, total: ranked.length, query: input.query }, null, 2),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
export function handleGetSkill(skills: SkillEntry[], args: unknown) {
|
||||
const input = GetSkillInputSchema.parse(args);
|
||||
|
||||
const skill = skills.find(
|
||||
(s) => s.source === input.source && s.name === input.skill_id,
|
||||
);
|
||||
|
||||
if (!skill) {
|
||||
return {
|
||||
content: [{ type: 'text' as const, text: `Skill not found: ${input.source}/${input.skill_id}` }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: 'text' as const,
|
||||
text: JSON.stringify(skill, null, 2),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
export function handleRecommendSkills(skills: SkillEntry[], args: unknown) {
|
||||
const input = RecommendSkillsInputSchema.parse(args);
|
||||
const queryParts: string[] = [];
|
||||
|
||||
if (input.languages?.length) queryParts.push(...input.languages);
|
||||
if (input.frameworks?.length) queryParts.push(...input.frameworks);
|
||||
if (input.libraries?.length) queryParts.push(...input.libraries);
|
||||
if (input.task) queryParts.push(input.task);
|
||||
|
||||
const query = queryParts.join(' ');
|
||||
if (!query) {
|
||||
return {
|
||||
content: [{ type: 'text' as const, text: 'Provide at least one of: languages, frameworks, libraries, or task' }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
const ranked = ranker.rank(
|
||||
skills.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: s.content,
|
||||
})),
|
||||
query,
|
||||
);
|
||||
|
||||
const recommendMap = new Map(skills.map((s) => [s.name, s]));
|
||||
const results = ranked.slice(0, input.limit).map((r) => {
|
||||
const original = recommendMap.get(r.skill.name)!;
|
||||
return {
|
||||
name: original.name,
|
||||
description: original.description,
|
||||
source: original.source,
|
||||
tags: original.tags,
|
||||
score: r.score,
|
||||
};
|
||||
});
|
||||
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: 'text' as const,
|
||||
text: JSON.stringify({ recommendations: results, query }, null, 2),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
export function handleListCategories(skills: SkillEntry[]) {
|
||||
const tagCounts = new Map<string, number>();
|
||||
|
||||
for (const skill of skills) {
|
||||
if (skill.tags) {
|
||||
for (const tag of skill.tags) {
|
||||
tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const categories = Array.from(tagCounts.entries())
|
||||
.map(([name, count]) => ({ name, count }))
|
||||
.sort((a, b) => b.count - a.count);
|
||||
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: 'text' as const,
|
||||
text: JSON.stringify({ categories, total: categories.length }, null, 2),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
import { z } from 'zod';
|
||||
|
||||
export const SearchSkillsInputSchema = z.object({
|
||||
query: z.string().describe('Search query for skills'),
|
||||
limit: z.number().min(1).max(50).default(10).describe('Maximum results'),
|
||||
include_content: z.boolean().default(false).describe('Include full skill content'),
|
||||
include_references: z.boolean().default(false).describe('Include reference file paths'),
|
||||
filters: z
|
||||
.object({
|
||||
tags: z.array(z.string()).optional(),
|
||||
category: z.string().optional(),
|
||||
source: z.string().optional(),
|
||||
})
|
||||
.optional()
|
||||
.describe('Optional filters'),
|
||||
});
|
||||
|
||||
export const GetSkillInputSchema = z.object({
|
||||
source: z.string().describe('Skill source (e.g. owner/repo)'),
|
||||
skill_id: z.string().describe('Skill name/identifier'),
|
||||
include_references: z.boolean().default(false).describe('Include reference file paths'),
|
||||
});
|
||||
|
||||
export const RecommendSkillsInputSchema = z.object({
|
||||
languages: z.array(z.string()).optional().describe('Programming languages'),
|
||||
frameworks: z.array(z.string()).optional().describe('Frameworks in use'),
|
||||
libraries: z.array(z.string()).optional().describe('Libraries in use'),
|
||||
task: z.string().optional().describe('Current task description'),
|
||||
limit: z.number().min(1).max(20).default(5).describe('Maximum results'),
|
||||
});
|
||||
|
||||
export const ListCategoriesInputSchema = z.object({});
|
||||
|
||||
export type SearchSkillsInput = z.infer<typeof SearchSkillsInputSchema>;
|
||||
export type GetSkillInput = z.infer<typeof GetSkillInputSchema>;
|
||||
export type RecommendSkillsInput = z.infer<typeof RecommendSkillsInputSchema>;
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"composite": false
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist", "**/*.test.ts"]
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
import { defineConfig } from 'tsup';
|
||||
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
format: ['esm'],
|
||||
dts: true,
|
||||
clean: true,
|
||||
sourcemap: true,
|
||||
target: 'node18',
|
||||
skipNodeModulesBundle: true,
|
||||
platform: 'node',
|
||||
banner: {
|
||||
js: '#!/usr/bin/env node',
|
||||
},
|
||||
});
|
||||
Generated
+59
@@ -32,6 +32,9 @@ importers:
|
||||
'@skillkit/agents':
|
||||
specifier: workspace:*
|
||||
version: link:../../packages/agents
|
||||
'@skillkit/api':
|
||||
specifier: workspace:*
|
||||
version: link:../../packages/api
|
||||
'@skillkit/cli':
|
||||
specifier: workspace:*
|
||||
version: link:../../packages/cli
|
||||
@@ -89,6 +92,34 @@ importers:
|
||||
specifier: ^2.1.8
|
||||
version: 2.1.9(@types/node@22.19.7)(lightningcss@1.30.2)
|
||||
|
||||
packages/api:
|
||||
dependencies:
|
||||
'@hono/node-server':
|
||||
specifier: ^1.0.0
|
||||
version: 1.19.9(hono@4.11.7)
|
||||
'@skillkit/core':
|
||||
specifier: workspace:*
|
||||
version: link:../core
|
||||
hono:
|
||||
specifier: ^4.0.0
|
||||
version: 4.11.7
|
||||
zod:
|
||||
specifier: ^3.24.0
|
||||
version: 3.25.76
|
||||
devDependencies:
|
||||
'@types/node':
|
||||
specifier: ^22.10.5
|
||||
version: 22.19.7
|
||||
tsup:
|
||||
specifier: ^8.3.5
|
||||
version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(typescript@5.9.3)(yaml@2.8.2)
|
||||
typescript:
|
||||
specifier: ^5.7.2
|
||||
version: 5.9.3
|
||||
vitest:
|
||||
specifier: ^2.1.8
|
||||
version: 2.1.9(@types/node@22.19.7)(lightningcss@1.30.2)
|
||||
|
||||
packages/cli:
|
||||
dependencies:
|
||||
'@clack/prompts':
|
||||
@@ -97,6 +128,9 @@ importers:
|
||||
'@skillkit/agents':
|
||||
specifier: workspace:*
|
||||
version: link:../agents
|
||||
'@skillkit/api':
|
||||
specifier: workspace:*
|
||||
version: link:../api
|
||||
'@skillkit/core':
|
||||
specifier: workspace:*
|
||||
version: link:../core
|
||||
@@ -188,6 +222,31 @@ importers:
|
||||
specifier: ^2.1.8
|
||||
version: 2.1.9(@types/node@22.19.7)(lightningcss@1.30.2)
|
||||
|
||||
packages/mcp:
|
||||
dependencies:
|
||||
'@modelcontextprotocol/sdk':
|
||||
specifier: ^1.0.0
|
||||
version: 1.25.3(hono@4.11.7)(zod@3.25.76)
|
||||
'@skillkit/core':
|
||||
specifier: workspace:*
|
||||
version: link:../core
|
||||
zod:
|
||||
specifier: ^3.24.0
|
||||
version: 3.25.76
|
||||
devDependencies:
|
||||
'@types/node':
|
||||
specifier: ^22.10.5
|
||||
version: 22.19.7
|
||||
tsup:
|
||||
specifier: ^8.3.5
|
||||
version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(typescript@5.9.3)(yaml@2.8.2)
|
||||
typescript:
|
||||
specifier: ^5.7.2
|
||||
version: 5.9.3
|
||||
vitest:
|
||||
specifier: ^2.1.8
|
||||
version: 2.1.9(@types/node@22.19.7)(lightningcss@1.30.2)
|
||||
|
||||
packages/mcp-memory:
|
||||
dependencies:
|
||||
'@modelcontextprotocol/sdk':
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
packages:
|
||||
- 'packages/*'
|
||||
- 'apps/*'
|
||||
- 'clients/*'
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# SkillKit Community Registry
|
||||
|
||||
This directory contains the community-curated skills registry for SkillKit.
|
||||
|
||||
## How to Contribute
|
||||
|
||||
1. Fork this repository
|
||||
2. Add your skill to `SKILLS.md` under the appropriate category
|
||||
3. Follow the format: `- [skill-name](repo-url) - Brief description`
|
||||
4. Submit a pull request
|
||||
|
||||
## Format
|
||||
|
||||
Each entry follows this format:
|
||||
|
||||
```markdown
|
||||
- [skill-name](https://github.com/owner/repo) - Brief description of what the skill does
|
||||
```
|
||||
|
||||
## Categories
|
||||
|
||||
Skills are organized into categories. If your skill doesn't fit an existing category, propose a new one in your PR.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Skill must have a valid `SKILL.md` file
|
||||
- Description must be clear and concise (under 100 characters)
|
||||
- Repository must be publicly accessible
|
||||
- Skill must follow SkillKit conventions
|
||||
@@ -0,0 +1,66 @@
|
||||
# SkillKit Community Skills Registry
|
||||
|
||||
A curated list of community-contributed skills for AI coding agents.
|
||||
|
||||
## Code Quality
|
||||
|
||||
- [code-simplifier](https://github.com/anthropics/skills) - Simplifies and refines code for clarity and maintainability
|
||||
- [code-review](https://github.com/anthropics/skills) - Automated code review with best practices
|
||||
|
||||
## React & Frontend
|
||||
|
||||
- [react-performance](https://github.com/anthropics/skills) - React app performance optimization
|
||||
- [nextjs-best-practices](https://github.com/vercel-labs/agent-skills) - Next.js patterns and conventions
|
||||
- [css-architecture](https://github.com/anthropics/skills) - Scalable CSS organization patterns
|
||||
|
||||
## Testing
|
||||
|
||||
- [testing-guide](https://github.com/anthropics/skills) - Comprehensive unit testing fundamentals
|
||||
- [e2e-testing](https://github.com/anthropics/skills) - End-to-end testing with Playwright
|
||||
- [tdd-workflow](https://github.com/anthropics/skills) - Test-driven development workflow
|
||||
|
||||
## DevOps & Infrastructure
|
||||
|
||||
- [docker-best-practices](https://github.com/anthropics/skills) - Container optimization patterns
|
||||
- [kubernetes-basics](https://github.com/anthropics/skills) - Kubernetes deployment fundamentals
|
||||
- [cicd-pipelines](https://github.com/anthropics/skills) - CI/CD pipeline configuration
|
||||
|
||||
## API Development
|
||||
|
||||
- [rest-api-design](https://github.com/anthropics/skills) - RESTful API design patterns
|
||||
- [graphql-patterns](https://github.com/anthropics/skills) - GraphQL schema and resolver patterns
|
||||
|
||||
## Database
|
||||
|
||||
- [sql-optimization](https://github.com/anthropics/skills) - SQL query optimization techniques
|
||||
- [migration-patterns](https://github.com/anthropics/skills) - Database migration best practices
|
||||
|
||||
## Security
|
||||
|
||||
- [security-audit](https://github.com/anthropics/skills) - Security vulnerability detection
|
||||
- [auth-patterns](https://github.com/anthropics/skills) - Authentication and authorization patterns
|
||||
|
||||
## Documentation
|
||||
|
||||
- [api-docs](https://github.com/anthropics/skills) - API documentation generation
|
||||
- [readme-guide](https://github.com/anthropics/skills) - README writing best practices
|
||||
|
||||
## AI & ML
|
||||
|
||||
- [prompt-engineering](https://github.com/anthropics/skills) - Prompt engineering patterns
|
||||
- [llm-integration](https://github.com/anthropics/skills) - LLM API integration patterns
|
||||
|
||||
## Mobile
|
||||
|
||||
- [react-native-perf](https://github.com/anthropics/skills) - React Native performance optimization
|
||||
- [mobile-accessibility](https://github.com/anthropics/skills) - Mobile accessibility patterns
|
||||
|
||||
## Data Processing
|
||||
|
||||
- [data-pipeline](https://github.com/anthropics/skills) - Data pipeline design patterns
|
||||
- [etl-patterns](https://github.com/anthropics/skills) - ETL workflow best practices
|
||||
|
||||
## Animation & Video
|
||||
|
||||
- [remotion-best-practices](https://github.com/remotion-dev/skills) - Video creation with Remotion
|
||||
- [motion-graphics](https://github.com/remotion-dev/skills) - Kinetic typography and logo animations
|
||||
Reference in New Issue
Block a user