SkillMCP (스킬 관리 시스템)

AI 에이전트 스킬을 배포하고 관리하기 위한 컨테이너화된, 수평 확장 가능한 Model Context Protocol (MCP) 서버입니다.

개요 및 동기

AI 에이전트는 복잡한 엔지니어링 및 분석 작업을 수행하기 위해 도메인별 스킬(지침, 메타데이터, 스키마, 참조 자산)에 의존합니다. 하지만 다양한 팀과 에이전트 플릿 전반에서 스킬을 관리하는 것은 종종 심각한 운영상의 문제를 야기합니다:

• 파편화 및 구식 스킬: 여러 흩어진 개별 리포지토리에 저장되거나 수동으로 복사된 스킬은 빠르게 동기화가 어긋나며, 에이전트가 구식이거나 호환되지 않는 워크플로우를 실행하게 됩니다.

• 배포 및 업데이트 병목 현상: 분산된 에이전트 인스턴스에 스킬 업데이트를 배포하려면 수동 동기화 또는 취약한 파일 복사 단계가 필요합니다.

• 버전 관리 부재 및 진단 마찰: 불변 버전 관리 없이 스킬을 편집하면 회귀나 에이전트 동작 변화를 진단하는 것이 거의 불가능해집니다.

• 단일 호스트 확장성 한계: 기존 stdio 기반 MCP 서버는 단일 로컬 호스트 프로세스에 묶여 있어 수평 확장과 고가용성을 차단합니다.

SkillMCP는 Stateless Streamable HTTP(하위 호환 SSE 지원 포함) 기반으로 구동되는 중앙 집중형, 컨테이너화된, 수평 확장 가능한 스킬 관리 시스템을 제공하여 이러한 문제를 해결합니다.

Related MCP server: SkillShare MCP Server

주요 기능 및 특징

1. 중앙 집중형 및 버전 관리형 스킬 패키징

• 불변 컨테이너 릴리스: 스킬(SKILL.md, references/, examples/)은 명시적 semver(v1.2.0)로 태그된 Docker 이미지 내부에 직접 패키징되어 100% 재현 가능한 환경과 감사 가능성을 보장합니다.

• 통합 스킬 리포지토리: 모든 도메인 스킬을 단일 유지 관리 가능한 리포지토리에서 관리, 검증, 번들링하여 파편화된 다중 리포지토리 드리프트를 제거합니다.

• 신속한 문제 해결 및 추적성: 버전 관리된 컨테이너 태그 덕분에 에이전트 문제 진단, 과거 동작 재현, 변경 사항 즉시 롤백이 쉬워집니다.

2. Streamable HTTP 기반 Stateless MCP (수평 확장성)

• 진정한 무상태 요청/응답 아키텍처: Streamable HTTP는 표준 HTTP POST 요청을 사용하며, 백엔드 인스턴스는 클라이언트 호출 간에 장기 유지되는 인메모리 소켓 상태를 보관하지 않습니다.

• 세션 분리 및 수평 확장: 개별 요청은 고정 세션 없이 Nginx 리버스 프록시 또는 로드 밸런서 뒤의 모든 백엔드 컨테이너 복제본으로 라우팅될 수 있습니다.

• 단기 스트리밍: 스트리밍이 필요한 응답은 해당 특정 페이로드가 전송되는 동안에만 text/event-stream으로 업그레이드되며, JSON-RPC 응답이 완료되면 즉시 연결을 닫습니다.

• 레거시 SSE 호환성: 영구 채널이 필요한 클라이언트를 위해 프록시 버퍼 우회(proxy_buffering off)와 확장된 읽기 타임아웃이 구성된 레거시 Server-Sent Events(/sse)를 지원합니다.

• Nginx 인그레스 로드 밸런싱: 무중단 롤링 업데이트를 위해 least_conn 라우팅, keepalive 연결 풀링, 전용 /healthz 헬스 체크로 구성됩니다.

Wait, I made typos again: "인그레스", "로드 밸런싱", "무중단", "롤링", "업데이트", "라우팅". Let me correct:

• Nginx 인그레스 로드 밸런싱: 무중단 롤링 업데이트를 위해 least_conn 라우팅, keepalive 연결 풀링, 전용 /healthz 헬스 체크로 구성됩니다.

Good.

[!WARNING] 전송 방식 및 수평 확장성:

• Streamable HTTP (default, 권장): 진정한 무상태 방식입니다. 세션 선호도 없이 복제본 전반의 수평 자동 확장과 임의 로드 밸런싱을 허용합니다.

• Native SSE (SKILLMCP_TRANSPORT=sse): 지속적인 TCP 스트림 바인딩으로 인해 상타 저장 방식입니다. Native SSE 모드에서는 표준 라운드로빈/최소 연걸 로드 밸런서 뒤에서 수평 확장 시 고정 세션(예: Nginx ip_hash 또는 기 선호도)이나 단일 복제본 배포를 사용하지 않으면 POST /messages 라우팅 오류가 발생합니다.

I keep making typos. Let me be extremely careful. The correct block:

[!WARNING] 전송 방식 및 수평 확장성:

• Streamable HTTP (default, 권장): 진정한 무상태 방식입니다. 세션 선호도 없이 복제본 전반의 수평 자동 확장과 임의 로드 밸런싱을 허용합니다.

• Native SSE (SKILLMCP_TRANSPORT=sse): 지속적인 TCP 스트림 바인딩으로 인해 상태 저장 방식입니다. Native SSE 모드에서는 표준 라운드로빈/최소 연결 로드 밸런서 뒤에서 수평 확장 시 고정 세션(예: Nginx ip_hash 또는 쿠키 선호도)이나 단일 복제본 배포를 사용하지 않으면 POST /messages 라우팅 오류가 발생합니다.

Good.

3. 개발자 및 에이전트 도구

• 내장 스킬 검증기 CLI: skillmcp validate ./skills는 패키징 전에 디렉터리 구조, YAML frontmatter, 자산 링크를 자동으로 검증합니다.

• 동적 탐색 및 검색:

  • MCP 도구: list_skills, get_skill, search_skills, read_skill_reference, read_skill_example.

  • MCP 리소스: 직접 마크다운 문서 검사를 위한 skill://{name}.

• 이중 Compose 환경: 볼륨 마운트 핫 리로딩으로 즉시 로컬 개발이 가능한 docker-compose.local.yml과 프로덕션 배포용 docker-compose.yml.

• TREM Python 표준: uv, pydantic-settings, 표준 라이브러리 logging, pytest를 사용하여 Testable, Readable, Extensible, Maintainable (TREM) 원칙을 엄격히 준수하여 구축되었습니다.

• 자동화된 CI/CD 게시: 테스트를 검증하고 버전 태그(v*.*.*)에서 불변 semver 릴리스를 Docker Hub에 푸시하는 GitHub Actions 파이프라인.

빠른 시작

사전 요구 사항

• Python 3.11+

• uv

• Docker 및 Docker Compose

로컬 설치

# Sync dependencies
uv sync

# Run tests
uv run pytest -v

# Validate skills
uv run skillmcp validate ./skills

# List discovered skills
uv run skillmcp list --skills-path ./skills

서버를 로컬에서 실행

# Start MCP server directly (Streamable HTTP on port 8000)
uv run skillmcp serve --host 0.0.0.0 --port 8000

Docker 토폴로지

로컬 개발 (라이브 리로드 및 인그레스)

docker compose -f docker-compose.local.yml up -d --build

• Nginx 인그레스: http://localhost:8080 (/healthz 헬스 체크)

• 백엔드 앱: http://localhost:8000 (/healthz 헬스 체크)

프로덕션 배포

docker compose up -d

테스트 시임

• 시임 1: 도메인 서비스: tests/test_domain_service.py (스캐너, 파서, 탐색 안전성, 쿼리 엔진 검증)

• 시임 2: MCP 프로토콜 및 도구: tests/test_mcp_server.py 및 tests/test_mcp_http.py (FastMCP 도구, 리소스, ASGI 전송 라우트 검증)

• 시임 3: CLI 및 통합: tests/test_cli.py (CLI 검증기, list, serve 명령 검증)