# 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 builds itself on install and exposes a `learn-mcp` command:

```bash
npm install -g github:abp2204/learn-mcp
```

Then register it with any MCP-capable agent. Because it's a global command, the config is the same in **every folder** — and so is your progress (one store in your home dir).

**Claude Code:**

```bash
claude mcp add learn-mcp -- learn-mcp
```

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

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

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

```json
{
  "mcpServers": {
    "learn-mcp": { "command": "npx", "args": ["-y", "github:abp2204/learn-mcp"] }
  }
}
```

Now open any project in your agent and say *"generate me a medium graph problem"* — it works regardless of which folder you're in.

### From source (development)

```bash
git clone https://github.com/abp2204/learn-mcp && cd learn-mcp
npm install      # builds via the prepare script
npm run dev      # run from TS source (stdio)
npm run inspect  # explore the tools in the MCP Inspector
```

## How a session goes

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.
6. **`progress`** shows what you've solved and which topics are weak.

## Tools

| Tool | Purpose |
|---|---|
| `generate_problem` | Store an agent-authored, LeetCode-style problem |
| `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 the session |
| `next_step` | Advance a multi-step problem |
| `progress` | Single-user stats, solved-by-difficulty, weak topics |

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

## Storage

One global SQLite file in your home dir — **`~/.learn-mcp/learn.sqlite`** (respects `XDG_DATA_HOME`; override with the `LEARN_MCP_DB` env var). This is why your problems and progress are shared across every folder and agent, and survive restarts. Uses Node's built-in `node:sqlite`, so there's no native build step. The server prints the active store path to stderr on startup.

## 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](./CLAUDE.md) for architecture and conventions. Run the end-to-end test with:

```bash
node scripts/smoke.mjs
```

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