skill2mcp

skill2mcp는 SKILL.md 문서를 MCP 준비가 완료된 도구 정의로 변환하고, 단일 파일이나 전체 스킬 디렉토리로부터 최소한의 배포 가능한 MCP 서버 패키지를 생성할 수 있는 TypeScript CLI/라이브러리입니다.

생성된 서버는 공식 MCP TypeScript SDK(@modelcontextprotocol/sdk)를 사용하며 stdio, http 또는 both 전송 방식을 지원합니다.

이 프로젝트의 목적

SKILL 문서는 일반적으로 반구조화된 마크다운(프런트매터 + 산문 + 표)입니다. MCP 도구는 엄격한 계약(name, description, inputSchema)을 요구합니다.

skill2mcp는 다음과 같은 계층적 파이프라인을 통해 그 간극을 메워줍니다:

1. 마크다운을 안정적인 중간 표현(IR)으로 파싱

2. IR을 MCP 도구 정의로 변환

3. 핸들러 스텁이 포함된 배포 가능한 MCP 서버 패키지 생성

Related MCP server: Skillz

현재 상태

MVP가 구현되어 작동 중입니다:

• 결정론적 파서(strict, tolerant)

• 누락된 메타데이터를 위한 계단식 의미론적 모드(semantic)

• 도구 변환(SchemaBuilder, ToolMapper, ToolValidator)

• MCP 스타일의 도구 JSON을 포함한 inspect 출력

• 배포 가능한 MCP 서버 패키지를 포함한 build 출력

• 생성된 서버는 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 마크다운을 IR JSON으로 변환합니다.

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

인자:

• <input>: .md 파일 또는 디렉토리 경로

옵션:

• --mode: 파서 모드(tolerant 기본값)

• --format: 현재 json

출력:

• 파싱된 SkillDocument를 포함한 results[]

• 소스 파일별 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_* 코드)

semantic을 위한 OpenRouter 설정

환경 변수:

• 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 명령어 출력 계약

• 엔드투엔드 빌드 아티팩트 생성

엔지니어링 관례

• AGENTS.md의 저장소 협업 규칙 준수

• 제품/비즈니스 지침은 ROADMAP.md에 따름

• 커밋 메시지는 AI가 생성한 경우 [AI] 접두사 사용 필수

릴리스 아티팩트

이 저장소는 다음을 포함합니다:

• 이중 라이선스 배포: MIT OR Apache-2.0

• CHANGELOG.md

• CONTRIBUTING.md

• RELEASE_CHECKLIST.md

협업 모델

• 거버넌스 및 결정 규칙: GOVERNANCE.md

• 행동 강령: CODE_OF_CONDUCT.md

• 보안 보고: SECURITY.md

• 지원 채널: SUPPORT.md

알려진 제한 사항

• 매개변수 파싱은 현재 ## Parameters의 마크다운 표 형식을 가정함

• 의미론적 모드는 누락된 메타데이터를 우선시하며, 추출이 가능한 경우 누락된 매개변수를 보강할 수 있음

• Watch 모드는 현재 트리를 추적함; 나중에 깊게 중첩된 폴더가 추가되면 전체 커버리지를 위해 watch를 재시작해야 함

로드맵 정렬

활성 구현은 ROADMAP.md의 단계별 전달을 따름.

GenAI 통합 정책(활성화 시)은 로드맵 지침에 정의된 대로 OpenRouter를 기본 공급자 전략으로 우선시함.

라이선스

다음 중 하나에 따라 라이선스가 부여됩니다:

• MIT 라이선스 (LICENSE-MIT)

• Apache 라이선스 2.0 (LICENSE-APACHE)

선택에 따릅니다.