learn-mcp

An MCP server for agent-guided DSA practice. Connect it to an IDE agent (Claude Code, Cursor, etc.) and instead of static LeetCode problems, the agent generates immersive, LeetCode-style problems on demand and tutors you through them — escalating hints, concept explanations, and multi-step think-throughs.

The server provides structure and memory (problems, sessions, hint escalation, progress); the connected agent provides the creativity and teaching. No LLM runs inside the server.

Install

Install once from GitHub — it ships prebuilt (no build step on install) and exposes a learn-mcp command:

npm install -g https://github.com/abp2204/learn-mcp/tarball/main

Install from the tarball URL above, not the github:abp2204/learn-mcp shorthand. On recent npm versions a global git-dependency install links the package from npm's cache git-clone temp dir and then garbage-collects it, leaving a dangling symlink — so learn-mcp ends up "command not found". The tarball URL extracts a real package directory and avoids this. See Troubleshooting if a previous attempt left things broken.

Then register it with any MCP-capable agent. The command is global, but learn-mcp works inside one dedicated folder that becomes your personal practice environment (see Set up your practice folder below).

Claude Code:

claude mcp add learn-mcp -- learn-mcp

Cursor / Claude Desktop / any client (mcpServers config):

{
  "mcpServers": {
    "learn-mcp": { "command": "learn-mcp" }
  }
}

Prefer not to install globally? Use npx instead — same effect, nothing installed:

{
  "mcpServers": {
    "learn-mcp": { "command": "npx", "args": ["-y", "https://github.com/abp2204/learn-mcp/tarball/main"] }
  }
}

Set up your practice folder

learn-mcp turns one folder into your DSA practice repo. Make a clean folder, open it in your agent, and say "set up my practice workspace" (or have it call setup_workspace). That scaffolds:

active/         # problems you're solving now — one folder each (PROBLEM.md, solution.<ext>, notes.md)
completed/      # solved problems (moved here automatically on a pass)
paused/         # unsolved problems you've set aside (moved here via pause_problem)
STATS.md        # your progress over time
AGENTS.md       # the rules your agent follows in this folder
.learn-mcp/     # the workspace SQLite store + config
.claudeignore / .cursorignore / .gitignore

From then on, just talk to your agent: "generate me a medium graph problem in python". You can have several problems going at once in active/; the agent works there and never wanders into completed/ or paused/ — to look back it uses list_problems / revisit_problem. Every other tool requires this setup and will tell you to run setup_workspace first if you're in a plain folder.

From source (development)

git clone https://github.com/abp2204/learn-mcp && cd learn-mcp
npm install      # install deps
npm run build    # compile src/ -> dist/ (dist/ is committed; rebuild after src changes)
npm run dev      # run from TS source (stdio)
npm run inspect  # explore the tools in the MCP Inspector

How a session goes

0. One-time: setup_workspace in a clean folder (see above).
1. You ask the agent for, say, a medium graph problem with a story.
2. Agent authors it and calls generate_problem → it's stored with a stable id.
3. start_session drops you into the problem (answers hidden).
4. Stuck? get_hint escalates 1 → 4 (nudge → near-solution); the server tracks the level so hints don't over-reveal. explain_concept teaches an underlying idea. next_step advances multi-step problems.
5. submit_solution records your attempt; a pass marks it solved and moves it to completed/.
6. Stopping work on an unsolved one? pause_problem sets it aside in paused/.
7. progress shows what you've solved and which topics are weak.

Tools

Tool	Purpose
setup_workspace	Scaffold the current folder into a practice environment (run once)
generate_problem	Store an agent-authored problem (with a language); write it into active/<seq>-<slug>/
start_session	Begin a session; returns the solver-facing problem + sessionId
get_hint	Advance the escalating hint level (server-tracked)
explain_concept	Record/echo a taught concept
submit_solution	Record an attempt; pass solves it, moves it to completed/, refreshes STATS.md
pause_problem	Set aside an unsolved problem → paused/ (excluded from stats; solved problems can't be paused)
next_step	Advance a multi-step problem
progress	Single-user stats, solved-by-difficulty, weak topics
list_problems	List problems (titles + state) without dumping their content into context
revisit_problem	Re-open a past problem by slug/id (solver view)

Plus an author_problem MCP prompt: a rubric the agent can pull in to write well-calibrated, immersive problems.

Storage

Everything lives in your workspace folder: a SQLite store at <folder>/.learn-mcp/store.sqlite (the source of truth) plus a human-browsable file mirror (active/, completed/, paused/, STATS.md). Uses Node's built-in node:sqlite, so there's no native build step. The workspace root is found by walking up from the launch directory to the .learn-mcp/workspace.json marker (override with LEARN_MCP_WORKSPACE); the server prints the detected workspace to stderr on startup. Finished/paused problems (completed/, paused/) and the internal store are kept out of the agent's context via .claudeignore/.cursorignore.

Troubleshooting

npm error ENOTDIR ... rename '.../node_modules/learn-mcp' (install aborts instantly). A previous npm install -g . or npm link left a leftover symlink at <npm-prefix>/lib/node_modules/learn-mcp that npm can't move out of the way. Remove it and reinstall:

rm -f "$(npm prefix -g)/lib/node_modules/learn-mcp" "$(npm prefix -g)/bin/learn-mcp"
npm install -g https://github.com/abp2204/learn-mcp/tarball/main

Install succeeds but learn-mcp is "command not found". You likely installed via the github:abp2204/learn-mcp shorthand, which leaves a dangling symlink (see the note under Install). Clean up as above and reinstall from the tarball URL. Confirm it took with ls -ld "$(npm prefix -g)/lib/node_modules/learn-mcp" — it should be a real directory, not a -> symlink.

Status

v1. Solutions are agent-judged (the agent evaluates your code and reports pass/fail). A sandboxed code executor with generated test cases is the planned next step. Domain is DSA; DSP is a parked future idea.

Development

See CLAUDE.md for architecture and conventions. Run the end-to-end test with:

node scripts/smoke.mjs

Requires Node 22.5+ (uses built-in node:sqlite).