{
  "markdown": "# mcp-roadmapsh\n\n[![npm](https://img.shields.io/npm/v/mcp-roadmapsh.svg)](https://www.npmjs.com/package/mcp-roadmapsh)\n[![Node](https://img.shields.io/node/v/mcp-roadmapsh.svg)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\nMCP server for [roadmap.sh](https://roadmap.sh) — developer roadmaps, best\npractices, interview questions, project ideas, videos, and local progress\ntracking. Built on the official `@modelcontextprotocol/sdk` (TypeScript / stdio).\n\nAll data comes from official, public sources — no scraping, no mock data:\n\n- `https://roadmap.sh/{slug}.json` — rendered roadmap graphs\n- `raw.githubusercontent.com/nilbuild/developer-roadmap` — topic markdown\n- GitHub contents API — dynamic slug listings\n\n## Prerequisite\n\n[Node.js](https://nodejs.org) **20 or newer** (`node --version` to check). That is\nthe only requirement — `npx` (bundled with Node) handles the rest, no manual\nclone or build needed.\n\n## Quick start\n\n### Claude Code (one command)\n\n```bash\n# Once published to npm:\nclaude mcp add roadmapsh -- npx -y mcp-roadmapsh\n\n# Works today, straight from GitHub (npx builds it for you):\nclaude mcp add roadmapsh -- npx -y github:aissablk1/mcp-roadmapsh\n```\n\n### Any MCP client (JSON config)\n\n```json\n{\n  \"mcpServers\": {\n    \"roadmapsh\": { \"command\": \"npx\", \"args\": [\"-y\", \"mcp-roadmapsh\"] }\n  }\n}\n```\n\nReplace `mcp-roadmapsh` with `github:aissablk1/mcp-roadmapsh` to run the latest\nGitHub version before the npm release.\n\n### From source (contributors)\n\n```bash\ngit clone https://github.com/aissablk1/mcp-roadmapsh.git\ncd mcp-roadmapsh\nnpm install        # `prepare` builds dist/ automatically\nnpm test           # end-to-end test against real data\nnode dist/index.js # stdio MCP server\nnpm run inspect    # open the MCP Inspector\n```\n\n## Tools\n\n| Tool | Purpose |\n|------|---------|\n| `roadmap_diagnose` | Connectivity + cache/state status |\n| `roadmap_list` | List all roadmap slugs |\n| `roadmap_get` | Roadmap graph by slug (`outline` or `raw`) |\n| `roadmap_topic` | Topic markdown + links (by `nodeId` or `query`) |\n| `roadmap_export` | Export a whole roadmap as markdown/text |\n| `roadmap_search` | Search slugs by keyword within a scope |\n| `best_practices_list` / `best_practices_get` | Best-practice guides |\n| `questions_list` / `questions_get` | Interview question groups |\n| `projects_list` / `project_get` | Practice project ideas |\n| `videos_list` | Video resources |\n| `progress_mark` | Mark a topic learning / done / skip (local) |\n| `progress_status` | Completion percent for a roadmap |\n| `progress_next` | Recommend the next topic to learn |\n\n## Configuration (env)\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `ROADMAPSH_CACHE_DIR` | `~/.cache/mcp-roadmapsh` | HTTP cache directory |\n| `ROADMAPSH_CACHE_TTL_MS` | `86400000` (24 h) | Cache TTL |\n| `ROADMAPSH_STATE_DIR` | `~/.local/state/mcp-roadmapsh` | Progress state |\n| `ROADMAPSH_TIMEOUT_MS` | `20000` | HTTP timeout |\n| `ROADMAPSH_OWNER` | `nilbuild` | GitHub owner of the developer-roadmap repo |\n| `ROADMAPSH_BRANCH` | `master` | developer-roadmap branch |\n| `GITHUB_TOKEN` | — | Optional, raises GitHub API rate limit |\n\n## Publishing (maintainers)\n\n```bash\nnpm publish                       # to npmjs.com (npm login required first)\nnpx -y @modelcontextprotocol/publisher publish   # to the official MCP registry (server.json)\n```\n\nThe package ships `mcpName` and a `server.json` so it can be listed in the\nofficial Model Context Protocol registry.\n\n## License\n\nMIT — Aïssa BELKOUSSA\n",
  "bytes": 3561,
  "sha": "300f69005736a150bea70a944a94c21d6588ea18541f9fa487389b279b06e667",
  "repo_slug": "aissablk1/mcp-roadmapsh",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aissablk1_mcp_roadmapsh_5292bd1e/readme"
}