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)	N/A
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	はい	1行の説明
`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`	3x	"react-patterns" を3回繰り返す
`description`	2x	"Modern React patterns..." を2回繰り返す
`tags`	2x	"react frontend hooks" を2回繰り返す
`category`	1x	"development"
`summary`	1x	本文の最初の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