skill2mcp

skill2mcp — это CLI/библиотека на TypeScript, которая преобразует документы SKILL.md в определения инструментов, готовые для MCP, и может генерировать минимальный развертываемый пакет сервера MCP из одного файла или целой директории навыков.

Созданный сервер использует официальный SDK MCP для TypeScript (@modelcontextprotocol/sdk) и поддерживает транспорты stdio, http или both.

Зачем нужен этот проект

Документы SKILL обычно представляют собой полуструктурированный Markdown (frontmatter + текст + таблицы). Инструменты MCP требуют строгих контрактов (name, description, inputSchema).

skill2mcp преодолевает этот разрыв с помощью многоуровневого конвейера:

1. Парсинг Markdown в стабильное промежуточное представление (IR)

2. Преобразование IR в определения инструментов MCP

3. Генерация развертываемого пакета сервера MCP с заглушками обработчиков

Related MCP server: Skillz

Текущий статус

MVP реализован и работает:

• Детерминированный парсер (strict, tolerant)

• Каскадный семантический режим (semantic) для заполнения отсутствующих метаданных

• Преобразование инструментов (SchemaBuilder, ToolMapper, ToolValidator)

• Вывод inspect с JSON инструментов в стиле MCP

• Вывод build с развертываемым пакетом сервера MCP

• Созданный сервер поддерживает stdio + http

• build --watch для итеративной перегенерации

Установка

Требования

• Node.js 20+

• npm 10+

Локальная установка

npm install

Сборка CLI

npm run build

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

1. Парсинг одного SKILL

npm run parse -- ./fixtures/skills/valid-skill.md --mode strict

2. Проверка сгенерированных определений инструментов

npm run inspect -- ./fixtures/skills --mode tolerant

3. Генерация развертываемого пакета сервера MCP

npm run gen -- ./fixtures/skills --out ./generated/mcp-server --transport both --mode tolerant

4. Запуск созданного сервера

cd ./generated/mcp-server
npm install
npm run build
npm run start:stdio
# or
npm run start:http

HTTP-эндпоинт:

POST /mcp

Справочник CLI

parse

Преобразует SKILL Markdown в IR JSON.

skill2mcp parse <input> [--mode strict|tolerant|semantic]

Аргументы:

• <input>: путь к файлу .md или директории

Опции:

• --mode: режим парсера (tolerant по умолчанию)

• --format: в настоящее время json

Вывод:

• results[] с распарсенным SkillDocument

• diagnostics[] для каждого исходного файла

inspect

Преобразует распарсенный IR в определения инструментов, похожие на MCP.

skill2mcp inspect <input> [--mode strict|tolerant|semantic]

Вывод:

• tools[]: сгенерированные определения инструментов (name, description, inputSchema)

• results[]: инструмент + диагностика для каждого источника

build

Генерирует развертываемый пакет сервера MCP из одного или нескольких навыков.

skill2mcp build <input> --out <dir> [--transport stdio|http|both] [--mode strict|tolerant|semantic] [--watch]

Аргументы:

• <input>: путь к файлу .md или директории

Обязательные опции:

• --out: выходная директория для сгенерированного пакета

Опциональные опции:

• --transport: транспорт сервера по умолчанию (both по умолчанию)

• --mode: режим парсинга (tolerant по умолчанию)

• --watch: перегенерация пакета при изменениях в исходниках

Вывод:

• сгенерированные файлы пакета (package.json, tools.json, src/server.ts, обработчики)

• сводка диагностики в JSON

Режимы парсинга

strict

• Завершается ошибкой при отсутствии обязательных метаданных/схемы

• Лучший выбор для контроля качества в CI

tolerant

• Продолжает работу с предупреждениями при отсутствии полей

• Лучший выбор для пакетной обработки навыков разного качества

semantic

• Начинается с парсинга в режиме tolerant

• Пытается извлечь семантику через OpenRouter (если настроен)

• Применяет детерминированный вывод для неразрешенных полей

• Сохраняет трассировку диагностики (коды SEMANTIC_*)

Конфигурация OpenRouter для semantic

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

• OPENROUTER_API_KEY: включает удаленное семантическое извлечение

• OPENROUTER_MODEL (опционально): по умолчанию anthropic/claude-3.5-sonnet

• SKILL2MCP_CACHE_DIR (опционально): переопределение директории кэша

• OPENROUTER_HTTP_REFERER (опционально): передается как заголовок OpenRouter

• OPENROUTER_X_TITLE (опционально): передается как заголовок OpenRouter

Поведение кэша:

• Семантические ответы кэшируются по хешу контента в .skill2mcp-cache/semantic-openrouter-cache.json

• Если кэш присутствует, семантический режим использует его, избегая лишних удаленных вызовов

Канонический формат SKILL.md (рекомендуемый)

---
name: docx-generator
version: 1.0.0
description: Generate Word docs from structured markdown
tags: [documents, office]
---

## Parameters
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| content | string | yes |  | Markdown content |
| title | string | yes |  | Document title |

## Examples
**Input:** `{ content: "# Hello", title: "Report" }`
**Output:** report.docx generated at /outputs/

## Triggers
- "generate document"
- "create report"

Структура сгенерированного пакета

generated/mcp-server/
  package.json
  tsconfig.json
  README.md
  tools.json
  src/
    server.ts
    generated-tools.ts
    handlers/
      index.ts
      <tool_name>.ts

Разработка

Скрипты

npm run build       # compile TypeScript
npm run test        # run test suite
npm run parse       # parse command entry
npm run inspect     # inspect command entry
npm run gen         # build command entry

Набор тестов

Текущее автоматизированное покрытие включает:

• поведение парсера (strict, tolerant, semantic)

• построитель схем и маппинг инструментов

• контракт вывода команды inspect

• генерацию артефактов сборки end-to-end

Инженерные соглашения

• Соблюдайте правила совместной работы в репозитории AGENTS.md

• Продуктовые/бизнес-директивы регулируются ROADMAP.md

• Сообщения коммитов должны использовать префикс [AI], если они сгенерированы ИИ

Артефакты релиза

Этот репозиторий включает:

• Двойную лицензию: MIT OR Apache-2.0

• CHANGELOG.md

• CONTRIBUTING.md

• RELEASE_CHECKLIST.md

Модель сотрудничества

• Управление и правила принятия решений: GOVERNANCE.md

• Кодекс поведения: CODE_OF_CONDUCT.md

• Отчеты о безопасности: SECURITY.md

• Каналы поддержки: SUPPORT.md

Известные ограничения

• Парсинг параметров в настоящее время предполагает формат таблицы Markdown в разделе ## Parameters

• Семантический режим отдает приоритет отсутствующим метаданным и может обогащать отсутствующие параметры, если доступно извлечение

• Режим watch отслеживает текущее дерево; если позже будут добавлены глубоко вложенные папки, перезапустите watch для полного покрытия

Соответствие дорожной карте

Активная реализация следует поэтапной доставке, описанной в ROADMAP.md.

Политика интеграции GenAI (если включена) отдает приоритет OpenRouter как стратегии провайдера по умолчанию, как определено в директивах дорожной карты.

Лицензия

Лицензировано на ваш выбор:

• Лицензия MIT (LICENSE-MIT)

• Лицензия Apache 2.0 (LICENSE-APACHE)