# MCP Notes Server

A minimal [Model Context Protocol](https://modelcontextprotocol.io) server, built
from scratch in Python, that exposes a simple note-taking tool set to any
MCP-compatible client (Claude Desktop, the MCP Inspector, a custom agent, etc).

Built as a from-scratch, non-toy example of all three MCP primitives —
**tools**, a **resource**, and **prompts** — in one small, readable project.

## What it does

- `add_note(title, content)` — save a new note
- `list_notes()` — list all saved note titles
- `search_notes(keyword)` — search notes by title or content
- `delete_note(title)` — delete a note by exact title
- `notes://all` — a resource exposing every note as readable markdown
- `summarize_notes` — a prompt that generates a ready-made "summarize all my notes" message
- `clean_up_note` — a prompt that turns rough pasted text into a clean, titled note

Notes are persisted to a local `notes_data.json` file (created automatically on
first run).

## Project structure

```
store.py     # data layer — save/load/search notes (plain Python, no MCP code)
prompts.py   # reusable prompt templates (plain strings with placeholders)
app.py       # the MCP server itself — wires store.py and prompts.py into
             # MCP tools, a resource, and prompts using MCPServer
```

## Requirements

- Python 3.10+
- The official [`mcp` Python SDK](https://github.com/modelcontextprotocol/python-sdk), v2.x

## Setup

```bash
git clone https://github.com/<your-username>/mcp-notes-server.git
cd mcp-notes-server
pip install -r requirements.txt
```

## Running it

**Quick test with the built-in inspector** (a browser UI for calling tools
without a full client):

```bash
mcp dev app.py
```

This opens a browser tab where you can call each tool, read the resource, and
run the prompts directly.

**Connect it to Claude Desktop** — add this to your Claude Desktop MCP config
(adjust the path to wherever you cloned this repo):

```json
{
  "mcpServers": {
    "notes": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-notes-server/app.py"]
    }
  }
}
```

Restart Claude Desktop, and it will be able to call these tools, read the
resource, and offer the prompts directly inside a normal conversation.

## Why it's built this way

`store.py` knows nothing about MCP — it's just a plain Python class that reads
and writes a JSON file. `app.py` is a thin protocol wrapper on top of it. That
separation is the one pattern worth taking away from this example: keep your
actual logic MCP-agnostic, and wrap it at the edges. Swap `NoteStore` for a
real database and nothing about the MCP layer has to change.

## License

MIT — do whatever you want with this.