remote-skill-mcp

Динамически предоставляет файлы навыков ( skill.md и его подфайлы) с удалённого HTTP-сервиса как инструменты, ресурсы и промпты MCP (Model Context Protocol), позволяя любому MCP-клиенту (Claude Desktop, Cursor, LobeHub и др.) напрямую читать удалённую документацию навыков через stdio.

📖 English documentation / Английская документация: README.en.md

Реализация на основе стандартного MCP SDK с рантаймом FastMCP (не рукописный слой JSON-RPC-протокола), полностью соответствует спецификации MCP, может быть напрямую подключена любым MCP-клиентом и адаптирована для LobeHub MCP Market (см. 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-ссылок / изображений / голых токенов файлов / имён каталогов, для каждой ссылки выполняется HEAD-проверка (без загрузки содержимого):

   • Ссылка — файл → записывается путь + mime/size;

   • Ссылка — каталог → GET его HTML-страницы списка, перечисленные файлы записываются (без рекурсивной загрузки содержимого файлов);

   • Голые имена файлов с 404 автоматически повторяются в известных каталогах;

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

• ✅ Повтор при 404: автоматический повтор неудачных путей в известных каталогах

• ✅ Определение MIME: при content-type = application/octet-stream выполняется откат по расширению (.md и т.п. всё равно обрабатываются как текст)

• ✅ Три способа предоставления: инструменты / ресурсы / промпты (description содержит только список путей, без содержимого)

• ✅ Защита от больших файлов: чтение отклоняется при превышении MCP_MAX_FILE_BYTES

• ✅ Логи идут только в stderr, stdout используется только для сообщений протокола

• ✅ Ошибки инструментов возвращаются с isError=True (соответствует соглашению MCP, клиент не выбрасывает исключения)

• ✅ Адаптировано для LobeHub MCP Market: включает манифест 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 Market

Репозиторий уже содержит манифест рынка lhm.plugin.json (полный набор identifier/name/version/author/homepage/icon/category/tags/description/tools/prompts/resources).

1. Убедитесь, что репозиторий запушен в GitHub (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 (достаточно изменить version в lhm.plugin.json).

Рынок ранжирует по таким параметрам, как активность / стабильность / отзывы сообщества. В манифесте уже заполнены поля автор, домашняя страница, иконка, категория, теги, инструменты/промпты/ресурсы для повышения оценки полноты.

Тестирование

python tests/e2e_test.py

Сквозной тест запускает сервер через mcp.ClientSession и проверяет полный цикл 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-ссылки, изображения, голые имена файлов, формат имя_каталога:).

Лицензия

MIT © Congenital