skills-mcp-server

BM25 순위 검색, 구조화된 메타데이터 및 컨텍스트 효율적인 응답을 통해 1300개 이상의 AI 스킬 카탈로그를 제공하는 고성능 MCP(Model Context Protocol) 서버입니다.

수천 개의 스킬이 컨텍스트 윈도우를 낭비하는 문제를 해결하기 위해 구축되었습니다. 이 서버는 스킬을 인덱싱하고 순위를 매겨 필요한 정보만 제공합니다.

┌────────────────────────────────────────────────────────────┐
│  IDE / AI Client                                           │
│  (Claude, Cursor, Gemini, Copilot, Windsurf, ...)         │
│                                                            │
│  "find me a skill for React dashboards"                    │
└──────────────────────┬─────────────────────────────────────┘
                       │ MCP Protocol
                       ▼
┌────────────────────────────────────────────────────────────┐
│  skills-mcp-server                                         │
│                                                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                │
│  │ Indexer   │  │ BM25     │  │ 6 MCP    │                │
│  │ 1300+    │──│ Search   │──│ Tools    │                │
│  │ skills   │  │ Engine   │  │          │                │
│  └──────────┘  └──────────┘  └──────────┘                │
│                                                            │
│  Transports: stdio | HTTP/SSE | AWS Lambda                 │
└────────────────────────────────────────────────────────────┘

주요 기능

BM25 순위 검색 — 단순 키워드 매칭이 아닙니다. 필드 가중치를 적용한 실제 관련성 점수 산정 (이름 3배, 설명 2배, 태그 2배, 본문 1배)
컨텍스트 효율성 — 스킬 메타데이터(~500자), 요약(~2K자) 또는 전체 콘텐츠(최대 25K자) 중 선택하여 읽을 수 있습니다. 컨텍스트 사용량을 직접 제어하세요.
구조화된 메타데이터 — YAML 프론트매터를 파싱하여 이름, 설명, 태그, 카테고리, 위험도, 작성자, 도구 등 타입이 지정된 필드로 제공합니다.
전체 페이지네이션 — 모든 목록/검색 도구가 offset 및 limit을 지원합니다.
3가지 전송 모드 — 로컬 IDE용 stdio, 원격 액세스용 HTTP/SSE, 서버리스용 AWS Lambda를 지원합니다.
빠른 시작 — 1300개 이상의 스킬을 약 1.5초 만에 인덱싱합니다. 메모리 사용량은 약 3MB입니다(원시 데이터 65MB 대비).
6가지 특화 도구 — 탐색, 목록 보기, 검색, 읽기, 검사, 새로고침

빠른 시작

사전 요구 사항

Node.js 18+
SKILL.md 파일이 포함된 skills/ 디렉토리 (스킬 형식 참조)

설치 및 빌드

git clone https://github.com/LucasRomanzin/skills-mcp-server.git
cd skills-mcp-server
npm install
npm run build

로컬 실행 (stdio)

node dist/index.js

HTTP 서버로 실행 (SSE)

node dist/http.js
# Server starts on http://localhost:3000
# MCP endpoint: http://localhost:3000/mcp
# Health check: http://localhost:3000/health

MCP 도구

`skills_browse_categories`

스킬 카테고리와 개수를 나열합니다. 가장 먼저 사용하세요.

Input:  { response_format?: "markdown" | "json" }
Output: Table with 9 categories and skill counts

`skills_search`

이름, 설명, 태그 및 콘텐츠 전반에 걸친 BM25 순위 기반 전체 텍스트 검색을 수행합니다.

Input:  { query: string, category?: string, risk?: string, offset?: 0, limit?: 10 }
Output: Ranked results with name, description, category, tags, score

`skills_list_by_category`

페이지네이션을 사용하여 특정 카테고리 내의 스킬을 나열합니다.

Input:  { category: string, offset?: 0, limit?: 20 }
Output: Paginated skill list with metadata

`skills_read`

컨텍스트 제어 기능을 사용하여 스킬 콘텐츠를 읽습니다.

Input:  { slug: string, section?: "metadata" | "summary" | "full", file?: string }

section="metadata"  →  ~500 chars   (frontmatter fields + file list)
section="summary"   →  ~2500 chars  (metadata + first 2000 chars of body)
section="full"      →  up to 25000 chars (complete content, truncated if larger)

`skills_inspect`

여러 스킬에 대한 구조화된 메타데이터와 태그 중복을 통한 관련 스킬을 가져옵니다.

Input:  { slugs: string[] (1-10), response_format?: "json" }
Output: Metadata + related_skills for each slug

`skills_refresh_index`

디스크에서 스킬을 추가/삭제/수정한 후 메모리 내 인덱스를 재구축합니다.

Input:  {}
Output: Previous count, new count, duration

IDE 설정

Claude Desktop / Claude Code

{
  "mcpServers": {
    "skills": {
      "command": "node",
      "args": ["/path/to/skills-mcp-server/dist/index.js"],
      "env": {
        "SKILLS_DIR": "/path/to/skills-mcp-server/skills"
      }
    }
  }
}

원격 (HTTP/SSE) — Cursor, VS Code, 모든 MCP 클라이언트

{
  "mcpServers": {
    "skills": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

AWS Lambda (배포 후)

{
  "mcpServers": {
    "skills": {
      "url": "https://<function-url-id>.lambda-url.<region>.on.aws/mcp"
    }
  }
}

모든 모드 및 IDE에 대한 단계별 설정 가이드는 **docs/SETUP.md**를 참조하세요.

배포 모드

모드	명령어	사용 사례	SSE 스트리밍
stdio	`node dist/index.js`	로컬 IDE (Claude, Cursor, Gemini CLI)	해당 없음
HTTP	`node dist/http.js`	개발 서버, EC2, VPS, Docker	예
Lambda	SAM deploy	서버리스, 자동 확장, 사용량 기반 과금	예 (응답 스트리밍)

스킬 형식

각 스킬은 skills/ 하위의 디렉토리이며, 최소한 YAML 프론트매터가 포함된 SKILL.md 파일을 포함해야 합니다:

skills/
├── CATALOG.md              # Category-to-skill mapping (auto-generated)
├── my-skill/
│   ├── SKILL.md            # Required: frontmatter + content
│   ├── references/         # Optional: additional .md files
│   └── scripts/            # Optional: helper scripts

SKILL.md 구조

---
name: my-skill
description: What this skill does in one sentence.
tags:
  - react
  - dashboard
  - frontend
risk: safe
source: community
author: your-name
tools:
  - claude-code
  - cursor
---

# My Skill

## Overview
...

## When to Use This Skill
...

프론트매터 필드

필드	타입	필수	설명
`name`	string	예	스킬 식별자
`description`	string	예	한 줄 설명
`tags`	string[]	아니오	검색 가능한 키워드
`risk`	enum	아니오	`safe`, `critical`, `offensive`, `unknown`, `none`
`source`	string	아니오	출처 (`community`, `official`)
`author`	string	아니오	작성자 이름
`tools`	string[]	아니오	호환되는 AI 도구

아키텍처

src/
├── index.ts              # stdio entry point
├── http.ts               # Express HTTP/SSE entry point
├── lambda.ts             # AWS Lambda handler
├── server.ts             # McpServer factory (shared)
├── constants.ts          # CHARACTER_LIMIT, pagination defaults
├── types.ts              # TypeScript interfaces
├── indexer.ts            # Frontmatter parser + skill index builder
├── catalog.ts            # CATALOG.md parser → category mapping
├── search.ts             # BM25 scoring engine
├── tools/
│   ├── browse.ts         # skills_browse_categories
│   ├── list.ts           # skills_list_by_category
│   ├── search.ts         # skills_search
│   ├── read.ts           # skills_read
│   ├── inspect.ts        # skills_inspect
│   └── refresh.ts        # skills_refresh_index
└── utils/
    ├── frontmatter.ts    # gray-matter wrapper + tag normalization
    ├── format.ts         # Markdown/JSON response formatters
    ├── truncate.ts       # CHARACTER_LIMIT enforcement
    └── paginate.ts       # Generic pagination

검색 엔진

BM25 구현은 각 스킬을 가중치가 적용된 문서로 인덱싱합니다:

필드	가중치	예시
`name`	3배	"react-patterns" 3회 반복
`description`	2배	"Modern React patterns..." 2회 반복
`tags`	2배	"react frontend hooks" 2회 반복
`category`	1배	"development"
`summary`	1배	본문 첫 500자

점수 산정은 k1=1.5, b=0.75인 BM25를 사용합니다. 결과는 관련성 점수 내림차순으로 정렬됩니다.

성능: 1300개 이상의 스킬에 대한 검색이 10ms 이내에 완료됩니다.

환경 변수

변수	기본값	설명
`SKILLS_DIR`	`~/skills-mcp/skills`	스킬 디렉토리 경로
`PORT`	`3000`	HTTP 서버 포트 (http.ts 전용)

기술 스택

TypeScript — 엄격 모드, ESM
MCP SDK v1.29+ — StreamableHTTPServerTransport, WebStandardStreamableHTTPServerTransport
gray-matter — YAML 프론트매터 파싱
Zod — 입력 유효성 검사 스키마
BM25 — 커스텀 구현(약 80줄), 외부 의존성 없음

라이선스

MIT

skills-mcp-server

skills-mcp-server

주요 기능

빠른 시작

사전 요구 사항

설치 및 빌드

로컬 실행 (stdio)

HTTP 서버로 실행 (SSE)

MCP 도구

`skills_browse_categories`

`skills_search`

`skills_list_by_category`

`skills_read`

`skills_inspect`

`skills_refresh_index`

IDE 설정

Claude Desktop / Claude Code

원격 (HTTP/SSE) — Cursor, VS Code, 모든 MCP 클라이언트

AWS Lambda (배포 후)

배포 모드

스킬 형식

SKILL.md 구조

프론트매터 필드

아키텍처

검색 엔진

환경 변수

기술 스택

라이선스

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API