🎓 What this is

DevNotes is a small, in-memory notes server — think a minimal Notion, exposed over MCP instead of a web UI. It's deliberately not trying to be a real product; every tool exists to be a clean, runnable example of one specific advanced MCP feature, and the notes themselves are just the excuse to have something worth calling a tool on.

Course topic	Where it lives
Sampling — server asks the client's LLM to do the work	summarize-note
Elicitation — server pauses to ask the user something	create-note (priority, if omitted)
Roots — client grants the server a specific local folder	index-roots
Progress & logging notifications	also index-roots, via sendNotification/sendLoggingMessage
Pagination	search-notes, cursor-based
Structured output	every tool returns structuredContent alongside its text
stdio vs. Streamable HTTP transports	stdio.ts / http.ts
Resumable transport	eventStore.ts, stateful HTTP mode
Stateless transport	http.ts --stateless
OAuth 2.1 + PKCE authorization	auth.ts, http.ts --oauth

🏗️ Architecture

flowchart LR
    subgraph client["interactiveClient.ts"]
        cap["declares: sampling, roots, elicitation"]
    end

    subgraph transport["pick one"]
        stdio["stdio.ts"]
        http["http.ts (Streamable HTTP)"]
    end

    subgraph server["createServer.ts"]
        t1["create-note<br/><i>elicitation</i>"]
        t2["search-notes<br/><i>pagination</i>"]
        t3["summarize-note<br/><i>sampling</i>"]
        t4["index-roots<br/><i>roots + notifications</i>"]
        store[("NotesStore<br/>(in-memory)")]
    end

    auth["auth.ts<br/>OAuth 2.1 + PKCE"]
    evt["eventStore.ts<br/>resumability"]

    client <-->|JSON-RPC over stdio or HTTP| transport
    transport --> server
    t1 & t2 & t3 & t4 --> store
    http -. "--oauth protects" .-> auth
    http -. "stateful mode uses" .-> evt

Sampling is the one genuinely bidirectional flow in the demo — the server calls back into whichever process holds the model credentials — so it's worth seeing on its own:

sequenceDiagram
    participant You
    participant Client as interactiveClient.ts
    participant Server as DevNotes server
    You->>Client: summarize-note
    Client->>Server: tools/call
    Server->>Client: sampling/createMessage
    alt ANTHROPIC_API_KEY set
        Client->>Anthropic API: messages.create()
        Anthropic API-->>Client: completion
    else no key configured
        Client->>Client: return a mock completion
    end
    Client-->>Server: CreateMessageResult
    Server-->>Client: tool result (the summary)
    Client-->>You: print it

The server never holds a model API key itself — that's the point of sampling. Only the client in this diagram needs one, and only optionally (see Quick start).

🚀 Quick start

npm install
cp .env.example .env   # optional — see below

Everything runs with zero configuration. .env only matters if you want real Claude completions for summarize-note instead of a mocked one — set ANTHROPIC_API_KEY there.

Local (stdio) — what Claude Desktop and the MCP Inspector use:

npm run client            # spawns the server itself, opens an interactive prompt
# or, to poke at it directly:
npm run inspector

Remote (Streamable HTTP):

npm run start:http                # stateful, resumable — default
npm run start:http:stateless      # no session id, horizontally scalable
npm run start:http:oauth          # requires a bearer token (see below)
npm run start:http:oauth-strict   # + RFC 8707 resource-indicator enforcement

npm run client:http               # talk to whichever one is running on :3000

Try roots by pointing the client at the bundled example notes:

npm run client -- --root ./examples
# then call index-roots from the prompt

Try the full OAuth flow: run npm run start:http:oauth, then open the MCP Inspector (npx @modelcontextprotocol/inspector) and connect to http://127.0.0.1:3000/mcp — its built-in "Connect" flow walks through dynamic client registration, the authorization redirect, and the PKCE token exchange for you. auth.ts has a header-comment listing exactly what it does and doesn't do — it's a real OAuth 2.1 authorization server, but an intentionally minimal one (in-memory storage, no real login screen); the same file explains what a production deployment needs to add back.

📁 Project structure

src/
  server/
    createServer.ts     factory: builds one McpServer + registers all four tools
    store.ts             the in-memory NotesStore (create/search/importFromRoot)
    stdio.ts              entrypoint: stdio transport
    http.ts                entrypoint: Streamable HTTP, stateful/stateless/oauth
    auth.ts               demo OAuth 2.1 + PKCE authorization server
    eventStore.ts        in-memory EventStore for resumable HTTP
    tools/
      createNote.ts        elicitation
      searchNotes.ts       pagination
      summarizeNote.ts     sampling
      indexRoots.ts        roots + progress/logging notifications
  client/
    interactiveClient.ts  demo client: implements the handlers a server can call back into
examples/                sample notes for the index-roots demo
assets/                   the certificate this repo is a follow-up to

🔒 Notes on the security-relevant bits

• Roots are enforced entirely by the client — store.importFromRoot only ever reads the file:// URI it's handed, one directory level deep, capped at 200 files / 200 KB each. The server never picks its own path.
• createMcpExpressApp enables DNS-rebinding protection automatically for 127.0.0.1 — see http.ts.
• auth.ts is explicitly a demo authorization server (see the header comment in that file for the exact list of what it skips). In a real deployment you'd almost always point verifyAccessToken at an existing IdP rather than writing one.
• Every server-initiated request (createMessage, listRoots, elicitInput) passes relatedRequestId, so responses route to the right session under concurrent HTTP load instead of the first one that happens to be listening.

🗺️ Learning path

Part of a series built while working through Anthropic Academy:

1. claude-api-starter — Building with the Claude API
2. mcp-advanced-starter — MCP: Advanced Topics (this repo)
3. Claude Code in Action — next up

💸 Donations

• 🇦🇷 ARS (Argentina) Alias: lazaro.503.alaba.mp
• 🌎 USD (local transfers within Argentina only) Alias: ahogada.duras.foca

License

MIT — see LICENSE.