skills-mcp-server

Высокопроизводительный MCP-сервер (Model Context Protocol), предоставляющий каталог из 1300+ ИИ-навыков с помощью поиска на основе BM25, структурированных метаданных и контекстно-эффективных ответов.

Создан для решения одной проблемы: тысячи навыков переполняют контекстное окно. Этот сервер индексирует их, ранжирует и предоставляет только то, что вам нужно.

┌────────────────────────────────────────────────────────────┐
│  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 — Это не просто сопоставление по ключевым словам. Реальная оценка релевантности с весовыми коэффициентами полей (имя 3x, описание 2x, теги 2x, тело 1x)
Контекстная эффективность — Читайте метаданные навыка (~500 символов), краткое содержание (~2 тыс. символов) или полное содержимое (ограничено 25 тыс. символов). Вы сами контролируете, сколько контекста использовать
Структурированные метаданные — YAML-фронтматтер, преобразованный в типизированные поля: имя, описание, теги, категория, риск, автор, инструменты
Пагинация везде — Каждый инструмент для списка/поиска поддерживает offset и limit
3 режима транспорта — stdio для локальных IDE, HTTP/SSE для удаленного доступа, AWS Lambda для serverless
Быстрый запуск — 1300+ навыков индексируются примерно за 1,5 секунды. Занимает ~3 МБ оперативной памяти (против 65 МБ в исходном виде)
6 специализированных инструментов — Просмотр, список, поиск, чтение, проверка, обновление

Быстрый старт

Предварительные требования

Node.js 18+
Директория skills/ с файлами SKILL.md (см. Формат навыков)

Установка и сборка

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"
    }
  }
}

См. docs/SETUP.md для получения полных пошаговых руководств по настройке для всех режимов и IDE.

Режимы развертывания

Режим	Команда	Вариант использования	SSE Streaming
stdio	`node dist/index.js`	Локальные IDE (Claude, Cursor, Gemini CLI)	Н/Д
HTTP	`node dist/http.js`	Сервер разработки, EC2, VPS, Docker	Да
Lambda	SAM deploy	Serverless, автомасштабирование, оплата за использование	Да (потоковая передача ответов)

Формат навыков

Каждый навык представляет собой директорию внутри skills/, содержащую как минимум файл SKILL.md с YAML-фронтматтером:

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[]	Нет	Совместимые ИИ-инструменты

Архитектура

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 символов тела

Оценка использует BM25 с k1=1.5, b=0.75. Результаты сортируются по убыванию оценки релевантности.

Производительность: поиск по 1300+ навыкам выполняется менее чем за 10 мс.

Переменные окружения

Переменная	По умолчанию	Описание
`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