io.github.aissablk1/mcp-roadmapsh
MCP server for roadmap.sh: roadmaps, best practices, interview questions, projects & progress
Open source Open in the app JSON README (API)
About
MCP server for roadmap.sh: roadmaps, best practices, interview questions, projects & progress
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- aissablk1
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0
- Stars
- 2
- Last push
- 2026-06-11T10:01:01Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-08-29 03:02:24
- Origin id
io.github.aissablk1/mcp-roadmapsh
README
# mcp-roadmapsh
[](https://www.npmjs.com/package/mcp-roadmapsh)
[](https://nodejs.org)
[](./LICENSE)
MCP server for [roadmap.sh](https://roadmap.sh) — developer roadmaps, best
practices, interview questions, project ideas, videos, and local progress
tracking. Built on the official `@modelcontextprotocol/sdk` (TypeScript / stdio).
All data comes from official, public sources — no scraping, no mock data:
- `https://roadmap.sh/{slug}.json` — rendered roadmap graphs
- `raw.githubusercontent.com/nilbuild/developer-roadmap` — topic markdown
- GitHub contents API — dynamic slug listings
## Prerequisite
[Node.js](https://nodejs.org) **20 or newer** (`node --version` to check). That is
the only requirement — `npx` (bundled with Node) handles the rest, no manual
clone or build needed.
## Quick start
### Claude Code (one command)
```bash
# 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
```
### Any MCP client (JSON config)
```json
{
"mcpServers": {
"roadmapsh": { "command": "npx", "args": ["-y", "mcp-roadmapsh"] }
}
}
```
Replace `mcp-roadmapsh` with `github:aissablk1/mcp-roadmapsh` to run the latest
GitHub version before the npm release.
### From source (contributors)
```bash
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
```
## Tools
| Tool | Purpose |
|------|---------|
| `roadmap_diagnose` | Connectivity + cache/state status |
| `roadmap_list` | List all roadmap slugs |
| `roadmap_get` | Roadmap graph by slug (`outline` or `raw`) |
| `roadmap_topic` | Topic markdown + links (by `nodeId` or `query`) |
| `roadmap_export` | Export a whole roadmap as markdown/text |
| `roadmap_search` | Search slugs by keyword within a scope |
| `best_practices_list` / `best_practices_get` | Best-practice guides |
| `questions_list` / `questions_get` | Interview question groups |
| `projects_list` / `project_get` | Practice project ideas |
| `videos_list` | Video resources |
| `progress_mark` | Mark a topic learning / done / skip (local) |
| `progress_status` | Completion percent for a roadmap |
| `progress_next` | Recommend the next topic to learn |
## Configuration (env)
| Variable | Default | Purpose |
|----------|---------|---------|
| `ROADMAPSH_CACHE_DIR` | `~/.cache/mcp-roadmapsh` | HTTP cache directory |
| `ROADMAPSH_CACHE_TTL_MS` | `86400000` (24 h) | Cache TTL |
| `ROADMAPSH_STATE_DIR` | `~/.local/state/mcp-roadmapsh` | Progress state |
| `ROADMAPSH_TIMEOUT_MS` | `20000` | HTTP timeout |
| `ROADMAPSH_OWNER` | `nilbuild` | GitHub owner of the developer-roadmap repo |
| `ROADMAPSH_BRANCH` | `master` | developer-roadmap branch |
| `GITHUB_TOKEN` | — | Optional, raises GitHub API rate limit |
## Publishing (maintainers)
```bash
npm publish # to npmjs.com (npm login required first)
npx -y @modelcontextprotocol/publisher publish # to the official MCP registry (server.json)
```
The package ships `mcpName` and a `server.json` so it can be listed in the
official Model Context Protocol registry.
## License
MIT — Aïssa BELKOUSSA