remote-skill-mcp

Dynamically expose skill files (skill.md and its sub-files) on a remote HTTP service as MCP (Model Context Protocol) tools, resources, and prompts, so any MCP client (Claude Desktop, Cursor, LobeHub, etc.) can read remote skill documents directly over stdio.

📖 English documentation / 英文文档: README.en.md

Built on the standard MCP SDK's FastMCP runtime (not a hand-written JSON-RPC protocol layer), fully compliant with the MCP specification, directly connectable by any MCP client, and adapted for the LobeHub MCP marketplace (see lhm.plugin.json).

How it works (lazy loading, saves context)

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

At startup (lifespan, lazy loading):

1. Fetch skill.md from REMOTE_SKILL_BASE_URL (a lightweight capability catalog describing the available skill areas);

2. Parse its markdown links / images / bare file tokens / directory names, and run a HEAD probe on each reference (without downloading the body):

   • Reference is a file → record path + mime/size;

   • Reference is a directory → GET its HTML listing page and record the listed files (without recursively downloading file bodies);

   • Bare file names that 404 are automatically retried against known directories;

3. Dynamically generate MCP exposures (description contains only the path list, not the body, to avoid context bloat):

   • Tool get_skill_file(path) — fetch file content on demand by path;

   • Resources skill://<relative path> — one resource per discovered file (downloaded only on read; text inlined, binary converted to base64);

   • Prompts skill / list_skills — return the full skill.md text / capability catalog summary.

This way the agent only sees "what capability areas exist" at any given time, and only pulls the detailed document when a specific skill is actually needed, avoiding dumping all skill details into context at once. If skill.md does not list all files directly and directory drilling is required, set MCP_DISCOVER_DEPTH>=1 to recurse N levels (this downloads intermediate-level bodies to parse more references).

Related MCP server: skills-mcp-server

Features

• ✅ Implemented with the standard MCP SDK (FastMCP), fully MCP-compliant, stdio transport

• ✅ Lazy loading: only skill.md is read at startup; sub-files only record paths, bodies are downloaded on demand (saves context)

• ✅ Dynamic discovery: HEAD probes for files + GET directory listing pages, parsing links/images/bare files/directory names in skill.md

• ✅ 404 retry: failed paths are automatically retried against known directories

• ✅ MIME inference: falls back to extension when content-type is application/octet-stream (.md etc. still treated as text)

• ✅ Three exposure modes: tool / resource / prompt (description contains only the path list, not the body)

• ✅ Large-file protection: refuses to read files exceeding MCP_MAX_FILE_BYTES

• ✅ Logs go only to stderr; stdout is used solely for protocol messages

• ✅ Tool errors are returned with isError=True (MCP convention, no client-side exceptions)

• ✅ Adapted for the LobeHub MCP marketplace: includes lhm.plugin.json manifest, pyproject.toml metadata, MIT license

Provided MCP capabilities

Installation

cd remote_skill_mcp
pip install -r requirements.txt

Dependencies: mcp (protocol types + stdio transport + FastMCP runtime), httpx (HTTP client).

Configuration (environment variables)

Running

Run directly (debugging)

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

After startup, the server blocks waiting for stdio input.

Connecting to an MCP client

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 / any other stdio-MCP-capable client works the same way: launch server.py as a subprocess.

Publishing to the LobeHub MCP marketplace

This repository already includes the marketplace manifest lhm.plugin.json (with identifier/name/version/author/homepage/icon/category/tags/description/tools/prompts/resources all present).

1. Make sure the repository is pushed to GitHub (origin = git@github.com:Congenital/remote_skill_mcp.git);

2. Install the marketplace CLI (requires Node.js ≥ 22) and log in:

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

3. Publish (reads lhm.plugin.json from the repository root):

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

   For subsequent version updates: npx -y @lobehub/market-cli plugin update (just change the version in lhm.plugin.json).

The marketplace ranks by dimensions such as activity / stability / community feedback. This manifest already includes author, homepage, icon, category, tags, tools/prompts/resources, and other fields to improve the completeness score.

Testing

python tests/e2e_test.py

End-to-end tests launch the server via mcp.ClientSession and verify the full chain: initialize / tools/list / tools/call (including invalid-path errors) / resources/list / resources/read / prompts/list / prompts/get (skill + list_skills).

Directory structure

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

Remote service requirements

• An HTTP service that can statically list/download files (e.g. python -m http.server);

• A skill.md at the root (or specify an entry file via SKILL_FILE);

• Sub-files referenced by relative path (supports markdown links, images, bare file names, and directory name: form).

License

MIT © Congenital