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 リンク / 画像 / ベアファイルトークン / ディレクトリ名 を解析し、各参照に対して HEAD プローブ を実行（本文はダウンロードしない）：

   • 参照がファイル → パス + mime/size を記録；

   • 参照がディレクトリ → その HTML リストページを GET し、列挙されたファイルを記録（ファイル本文は再帰的にダウンロードしない）；

   • 404 のベアファイル名は既知のディレクトリ内で自動リトライ；

3. MCP 公開物を動的生成（description にはパス一覧のみを含め、本文は含めない。コンテキストの膨張を防ぐ）：

   • ツール get_skill_file(path) —— パスに応じてオンデマンドでファイル内容を取得；

   • リソース skill://<相対パス> —— 発見された各ファイルに1リソース（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 などは引き続きテキストとして扱う）

• ✅ 3種類の公開方法：ツール / リソース / プロンプト（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 でサーバーを起動し、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