mcp-roadmapsh

mcp-roadmapsh

roadmap.sh 的 MCP 服务——提供开发者路线图、最佳实践、面试题、项目创意、视频和本地进度跟踪。基于官方 @modelcontextprotocol/sdk 构建（TypeScript / stdio）。

所有数据均来自官方公开来源——不抓取数据，不使用模拟数据：

• https://roadmap.sh/{slug}.json — 渲染后的路线图图表
• raw.githubusercontent.com/nilbuild/developer-roadmap — 主题 Markdown
• GitHub contents API — 动态 slug 列表

前置条件

Node.js 20 或更高版本（运行 node --version 检查）。这是唯一的要求——npx（随 Node 捆绑）会处理其余一切，无需手动克隆或构建。

快速开始

Claude Code（一个命令）

# Once published to npm:
claude mcp add roadmapsh -- npx -y mcp-roadmapsh

# Works today, straight from GitHub (npx builds it for you):
claude mcp add roadmapsh -- npx -y github:aissablk1/mcp-roadmapsh

任意 MCP 客户端（JSON 配置）

{
  "mcpServers": {
    "roadmapsh": { "command": "npx", "args": ["-y", "mcp-roadmapsh"] }
  }
}

在 npm 发布之前，若要运行最新的 GitHub 版本，请将 mcp-roadmapsh 替换为 github:aissablk1/mcp-roadmapsh。

从源码开始（贡献者）

git clone https://github.com/aissablk1/mcp-roadmapsh.git
cd mcp-roadmapsh
npm install        # `prepare` builds dist/ automatically
npm test           # end-to-end test against real data
node dist/index.js # stdio MCP server
npm run inspect    # open the MCP Inspector

工具

工具	用途
roadmap_diagnose	连通性与缓存/状态检查
roadmap_list	列出所有路线图 slug
roadmap_get	按 slug 获取路线图图表（outline 或 raw）
roadmap_topic	获取主题 Markdown 和链接（按 nodeId 或 query）
roadmap_export	将完整路线图导出为 Markdown/文本
roadmap_search	在指定范围内按关键词搜索 slug
best_practices_list / best_practices_get	最佳实践指南
questions_list / questions_get	面试题组
projects_list / project_get	练习项目创意
videos_list	视频资源
progress_mark	将主题标记为学习中 / 已完成 / 跳过（本地）
progress_status	路线图完成百分比
progress_next	推荐下一个要学习的主题

配置（环境变量）

变量	默认值	用途
ROADMAPSH_CACHE_DIR	~/.cache/mcp-roadmapsh	HTTP 缓存目录
ROADMAPSH_CACHE_TTL_MS	86400000（24 小时）	缓存 TTL
ROADMAPSH_STATE_DIR	~/.local/state/mcp-roadmapsh	进度状态
ROADMAPSH_TIMEOUT_MS	20000	HTTP 超时时间
ROADMAPSH_OWNER	nilbuild	developer-roadmap 仓库的 GitHub 所有者
ROADMAPSH_BRANCH	master	developer-roadmap 分支
GITHUB_TOKEN	—	可选，可提高 GitHub API 速率限制

发布（维护者）

npm publish                       # to npmjs.com (npm login required first)
npx -y @modelcontextprotocol/publisher publish   # to the official MCP registry (server.json)

此软件包包含 mcpName 和 server.json，因此可以列入官方 Model Context Protocol 注册表。

许可证

MIT — Aïssa BELKOUSSA