remote-skill-mcp

원격 HTTP 서비스의 스킬 파일(skill.md 및 하위 파일)을 MCP(Model Context Protocol) 도구, 리소스 및 프롬프트로 동적으로 노출하여, 모든 MCP 클라이언트(Claude Desktop, Cursor, LobeHub 등)가 stdio를 통해 원격 스킬 문서를 직접 읽을 수 있게 합니다.

📖 English documentation / 영문 문서: README.en.md

표준 MCP SDK의 FastMCP 런타임 기반 구현(수제 JSON-RPC 프로토콜 레이어가 아님)으로, MCP 규격을 완전히 준수하며 모든 MCP 클라이언트에서 바로 연결할 수 있고, LobeHub MCP 마켓에도适配(적응)되어 있습니다(lhm.plugin.json 참조).

작동 원리(지연 로딩, 컨텍스트 절약)

┌─────────────┐   stdio (newline-delimited JSON-RPC)   ┌──────────────────┐
│  MCP 客户端  │ ◄────────────────────────────────────► │   server.py      │
│ (Claude等)  │      initialize / tools/* /            │  (本仓库)         │
└─────────────┘      resources/* / prompts/*          └────────┬─────────┘
                                                                 │ HTTP GET/HEAD
                                                                 ▼
                                                      ┌─────────────────────┐
                                                      │ 远程 SimpleHTTP 服务 │
                                                      │  /skill.md          │
                                                      │  /image/*.md 等子文件│
                                                      └─────────────────────┘

시작 시(lifespan, 지연 로딩):

1. REMOTE_SKILL_BASE_URL에서 skill.md를 가져옵니다(경량 능력 카탈로그, 어떤 스킬 방향이 있는지 설명);

2. 그 안의 markdown 링크 / 이미지 / bare 파일 토큰 / 디렉터리 이름을 파싱하고, 각 참조에 대해 HEAD 탐지를 수행합니다(본문은 다운로드하지 않음):

   • 참조가 파일인 경우 → 경로 + mime/size 기록;

   • 참조가 디렉터리인 경우 → GET으로 HTML 목록 페이지를 가져와 나열된 파일을 기록합니다(파일 본문은 재귀적으로 다운로드하지 않음);

   • 404가 발생한 bare 파일 이름은 알려진 디렉터리에서 자동으로 재시도합니다;

3. MCP 노출 항목을 동적으로 생성합니다(description에는 경로 목록만 포함되고 본문은 포함되지 않아 컨텍스트 팽창을 방지):

   • 도구 get_skill_file(path) — 경로별로 필요 시 파일 내용을 가져옵니다;

   • 리소스 skill://<상대 경로> — 발견된 각 파일마다 리소스 하나(read 시에만 다운로드, 텍스트는 인라인, 바이너리는 base64 변환);

   • 프롬프트 skill / list_skills — skill.md 전문 / 능력 카탈로그 요약을 반환합니다.

이렇게 하면 에이전트는 평소에 "어떤 능력 방향이 있는지"만 보고, 실제로 특정 스킬이 필요할 때만 상세 문서를 가져오므로, 모든 스킬 상세를 한 번에 컨텍스트에 넣는 것을 방지합니다. skill.md가 모든 파일을 직접 나열하지 않고 디렉터리 드릴다운이 필요한 경우, MCP_DISCOVER_DEPTH>=1로 N단계 재귀를 설정할 수 있습니다(더 많은 참조를 파싱하기 위해 중간 레이어 본문을 다운로드함).

Related MCP server: skills-mcp-server

특징

• ✅ 표준 MCP SDK(FastMCP) 기반 구현, MCP 규격 완전 준수, stdio 전송

• ✅ 지연 로딩: 시작 시 skill.md만 읽고, 하위 파일은 경로만 기록하며 본문은 필요 시 다운로드(컨텍스트 절약)

• ✅ 동적 발견: HEAD 탐지 파일 + GET 디렉터리 목록 페이지, skill.md의 링크/이미지/bare 파일/디렉터리 이름 파싱

• ✅ 404 재시도: 실패한 경로를 알려진 디렉터리에서 자동 재시도

• ✅ MIME 추론: content-type이 application/octet-stream인 경우 확장자로 폴백(.md 등은 여전히 텍스트로 처리)

• ✅ 세 가지 노출 방식: 도구 / 리소스 / 프롬프트(description에는 경로 목록만 포함, 본문 없음)

• ✅ 대용량 파일 보호: MCP_MAX_FILE_BYTES 초과 시 읽기 거부

• ✅ 로그는 stderr로만 출력, stdout은 프로토콜 메시지 전용

• ✅ 도구 오류는 isError=True로 반환(MCP 규약 준수, 클라이언트에서 예외 발생하지 않음)

• ✅ LobeHub MCP 마켓适配(적응): lhm.plugin.json 매니페스트, pyproject.toml 메타데이터, MIT 라이선스 포함

제공되는 MCP 기능

설치

cd remote_skill_mcp
pip install -r requirements.txt

의존성: mcp(프로토콜 타입 + stdio 전송 + FastMCP 런타임), httpx(HTTP 클라이언트).

구성(환경 변수)

실행

직접 실행(디버그)

export REMOTE_SKILL_BASE_URL=http://192.168.2.6:4000
python server.py

서비스 시작 후 stdio 입력을 대기하며 블로킹됩니다.

MCP 클라이언트 연결

Claude Desktop(claude_desktop_config.json):

{
  "mcpServers": {
    "remote-skill": {
      "command": "python",
      "args": ["/绝对路径/remote_skill_mcp/server.py"],
      "env": {
        "REMOTE_SKILL_BASE_URL": "http://192.168.2.6:4000"
      }
    }
  }
}

Cursor / 기타 stdio MCP를 지원하는 클라이언트도 동일하게 server.py를 하위 프로세스로 시작하면 됩니다.

LobeHub MCP 마켓에 게시

본 저장소에는 마켓 매니페스트 lhm.plugin.json(identifier/name/version/author/homepage/icon/category/tags/description/tools/prompts/resources 모두 포함)이 이미 포함되어 있습니다.

1. 저장소가 GitHub에 push되었는지 확인합니다(origin = git@github.com:Congenital/remote_skill_mcp.git);

2. 마켓 CLI 설치(Node.js ≥ 22 필요) 및 로그인:

   npx -y @lobehub/market-cli login
   npx -y @lobehub/market-cli github connect

3. 게시(본 저장소 루트의 lhm.plugin.json 읽기):

   npx -y @lobehub/market-cli plugin publish https://github.com/Congenital/remote_skill_mcp

   이후 버전 업데이트: npx -y @lobehub/market-cli plugin update(lhm.plugin.json의 version만 변경하면 됨).

마켓은 활성도 / 안정성 / 커뮤니티 피드백 등의 기준으로 순위가 매겨집니다. 본 매니페스트는 작성자, 홈페이지, 아이콘, 카테고리, 태그, 도구/프롬프트/리소스 등의 필드를 모두 채워 완성도 점수를 높였습니다.

테스트

python tests/e2e_test.py

엔드투엔드 테스트는 mcp.ClientSession으로 server를 시작하여 initialize / tools/list / tools/call(잘못된 경로 오류 포함) / resources/list / resources/read / prompts/list / prompts/get(skill + list_skills) 전체 흐름을 검증합니다.

디렉터리 구조

remote_skill_mcp/
├── server.py            # MCP 服务（FastMCP 运行时 + 发现 + 工具/资源/提示词）
├── lhm.plugin.json      # LobeHub MCP 市场清单
├── pyproject.toml       # 项目元数据（名称/版本/作者/许可/入口点）
├── LICENSE              # MIT 许可
├── requirements.txt
├── README.md            # 中文文档
├── README.en.md         # 英文文档
└── tests/
    └── e2e_test.py      # 端到端测试

원격 서비스 요구 사항

• 파일을 정적으로 나열/다운로드할 수 있는 HTTP 서비스(예: python -m http.server);

• 루트 디렉터리에 skill.md 존재(또는 SKILL_FILE로 진입 파일 지정);

• 하위 파일은 상대 경로로 참조(markdown 링크, 이미지, bare 파일 이름, 디렉터리명: 형식 지원).

라이선스

MIT © Congenital