remote-skill-mcp

Expone dinámicamente los archivos de habilidades (skill.md y sus subarchivos) de un servicio HTTP remoto como herramientas, recursos y prompts de MCP (Model Context Protocol), permitiendo que cualquier cliente MCP (Claude Desktop, Cursor, LobeHub, etc.) lea directamente los documentos de habilidades remotos a través de stdio.

📖 English documentation / Documentación en inglés: README.en.md

Implementación en tiempo de ejecución de FastMCP basada en el SDK MCP estándar (no una capa de protocolo JSON-RPC escrita a mano), totalmente conforme con la especificación MCP, conectable directamente por cualquier cliente MCP, y ya adaptada al mercado MCP de LobeHub (ver lhm.plugin.json).

Cómo funciona (carga diferida, ahorro de contexto)

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

Al iniciar (lifespan, carga diferida):

1. Obtiene skill.md desde REMOTE_SKILL_BASE_URL (catálogo ligero de capacidades que describe qué áreas de habilidades existen);

2. Analiza los enlaces markdown / imágenes / tokens de archivos sin formato / nombres de directorios y realiza una detección HEAD para cada referencia (sin descargar el contenido):

   • Si la referencia es un archivo → registra la ruta + mime/tamaño;

   • Si la referencia es un directorio → hace GET a su página de listado HTML y registra los archivos listados (sin descargar recursivamente el contenido de los archivos);

   • Los nombres de archivos sin formato con 404 se reintentan automáticamente en los directorios conocidos;

3. Genera dinámicamente las exposiciones MCP (la descripción solo contiene la lista de rutas, no el contenido, para evitar la expansión del contexto):

   • Herramienta get_skill_file(path) — obtiene el contenido del archivo bajo demanda por ruta;

   • Recurso skill://<ruta_relativa> — un recurso por cada archivo descubierto (se descarga solo al hacer read; texto en línea, binario a base64);

   • Prompt skill / list_skills — devuelve el texto completo de skill.md / el resumen del catálogo de capacidades.

Así, el agente solo ve "qué áreas de capacidades existen" en el día a día, y solo obtiene la documentación detallada cuando realmente necesita una habilidad concreta, evitando volcar todos los detalles de las habilidades en el contexto de una sola vez. Si skill.md no lista todos los archivos directamente y es necesario explorar directorios, se puede establecer MCP_DISCOVER_DEPTH>=1 para recursar N niveles (descargará el contenido de los niveles intermedios para analizar más referencias).

Related MCP server: skills-mcp-server

Características

• ✅ Implementado con el SDK MCP estándar (FastMCP), totalmente conforme con la especificación MCP, transporte stdio

• ✅ Carga diferida: al iniciar solo lee skill.md; de los subarchivos solo registra las rutas y descarga el contenido bajo demanda (ahorra contexto)

• ✅ Descubrimiento dinámico: detección HEAD de archivos + GET de páginas de listado de directorios, analizando enlaces/imágenes/archivos sin formato/nombres de directorios de skill.md

• ✅ Reintento 404: reintenta automáticamente las rutas fallidas en los directorios conocidos

• ✅ Inferencia MIME: cuando content-type es application/octet-stream, se recurre a la extensión (.md y similares se tratan como texto)

• ✅ Tres formas de exposición: herramienta / recurso / prompt (la descripción solo contiene la lista de rutas, no el contenido)

• ✅ Protección de archivos grandes: rechaza la lectura si supera MCP_MAX_FILE_BYTES

• ✅ Los registros solo van a stderr; stdout se usa únicamente para mensajes de protocolo

• ✅ Los errores de herramientas se devuelven con isError=True (conforme a la convención MCP, el cliente no lanza excepciones)

• ✅ Adaptado al mercado MCP de LobeHub: incluye el manifiesto lhm.plugin.json, metadatos pyproject.toml, licencia MIT

Capacidades MCP proporcionadas

Instalación

cd remote_skill_mcp
pip install -r requirements.txt

Dependencias: mcp (tipos de protocolo + transporte stdio + runtime FastMCP), httpx (cliente HTTP).

Configuración (variables de entorno)

Ejecución

Ejecución directa (depuración)

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

El servicio se bloquea esperando entrada stdio tras iniciarse.

Conexión a clientes 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 / otros clientes que admiten MCP por stdio de forma similar: basta con iniciar server.py como subproceso.

Publicación en el mercado MCP de LobeHub

Este repositorio ya incluye el manifiesto de mercado lhm.plugin.json (con identifier/name/version/author/homepage/icon/category/tags/description/tools/prompts/resources completos).

1. Asegúrate de que el repositorio esté subido a GitHub (origin = git@github.com:Congenital/remote_skill_mcp.git);

2. Instala la CLI del mercado (requiere Node.js ≥ 22) e inicia sesión:

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

3. Publica (lee el lhm.plugin.json de la raíz de este repositorio):

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

   Actualizaciones posteriores: npx -y @lobehub/market-cli plugin update (basta con cambiar version en lhm.plugin.json).

El mercado clasifica según actividad / estabilidad / comentarios de la comunidad, entre otros. Este manifiesto ya incluye autor, página de inicio, icono, categoría, etiquetas, herramientas/prompts/recursos, etc., para mejorar la puntuación de completitud.

Pruebas

python tests/e2e_test.py

Las pruebas de extremo a extremo inician el servidor mediante mcp.ClientSession y verifican todo el flujo: initialize / tools/list / tools/call (incluidos errores de rutas no válidas) / resources/list / resources/read / prompts/list / prompts/get (skill + list_skills).

Estructura de directorios

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      # 端到端测试

Requisitos del servicio remoto

• Un servicio HTTP que pueda listar/descargar archivos estáticamente (por ejemplo, python -m http.server);

• Un skill.md en el directorio raíz (o especificar la entrada con SKILL_FILE);

• Los subarchivos se referencian con rutas relativas (admite enlaces markdown, imágenes, nombres de archivos sin formato y la forma nombre_de_directorio:).

Licencia

MIT © Congenital