# notes-mcp

A personal knowledge/notes **MCP server** in Python. It gives Claude (Desktop, Code, or any MCP-compatible client) a set of tools to create, search, edit, and manage a collection of notes stored in a local SQLite database.

Built with the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) (FastMCP), fully typed, with structured input/output schemas on every tool and a two-layer test suite.

![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)
![MCP SDK 1.28](https://img.shields.io/badge/MCP%20SDK-1.28-8A2BE2)
![Tests: 38 passing](https://img.shields.io/badge/tests-38%20passing-brightgreen)
![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)

![Live demo: all six tools called over stdio by a real MCP client](docs/demo.svg)

*Real output of [`examples/demo.py`](examples/demo.py) — a genuine MCP client session against the server over stdio, the same path Claude Desktop uses. Reproduce it with `uv run python examples/demo.py`.*

---

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard (originally by Anthropic) that lets AI applications talk to external systems in a uniform way. Instead of every AI app writing custom integrations for every data source, MCP defines one protocol:

- A **host** (Claude Desktop, Claude Code, an IDE…) runs one or more **clients**.
- Each client holds a 1:1 connection to a **server** — a small program that exposes capabilities.
- Servers expose three primitive types: **tools** (actions the model can invoke), **resources** (data the host can read), and **prompts** (reusable templates).

The wire format is **JSON-RPC 2.0**. For local servers like this one, the transport is **stdio**: the host launches the server as a subprocess, writes requests to its stdin, and reads responses from its stdout. That's why an MCP stdio server must never `print()` — stdout belongs to the protocol; diagnostics go to stderr.

A minimal MCP server needs exactly three things:

1. A server instance with a name (identifies it during the initialization handshake).
2. Registered capabilities — here, six tools, each with a JSON Schema for its inputs and outputs.
3. A transport loop — the SDK's `mcp.run(transport="stdio")` handles the handshake, request dispatch, validation, and serialization.

This project exposes **tools only**, which is the right primitive for note CRUD: the model decides when to call them, and each call is validated against a schema.

## Tools

| Tool | What it does | Key inputs → output |
|---|---|---|
| `add_note` | Create a note | `title`, `body`, `tags?` → full `Note` |
| `get_note` | Fetch one note in full | `note_id` *or* `title` → full `Note` |
| `search_notes` | Keyword and/or tag search | `query?`, `tag?`, `limit?` → `SearchResult` (summaries) |
| `update_note` | Edit any subset of fields | `note_id`, `title?`, `body?`, `tags?` → updated `Note` |
| `delete_note` | Permanently remove a note | `note_id` → `DeleteResult` |
| `list_recent_notes` | Newest-updated notes first | `limit?` → `RecentNotes` (summaries) |

Every tool declares a full **input schema** (generated from type hints + `pydantic.Field` constraints, e.g. `limit` is `1–100`) and an **output schema** (generated from the Pydantic return models in [`models.py`](src/notes_mcp/models.py)). Tools carry honest MCP annotations: `readOnlyHint` on get/search/list, `destructiveHint` on `delete_note` *and* `update_note` (an overwrite destroys prior content — the MCP spec reserves `destructiveHint: false` for purely additive updates), and `openWorldHint: false` everywhere since nothing leaves the local database. Hosts can use these to gate confirmation UX.

Failure cases (missing note, no search criteria, invalid arguments) come back as proper MCP tool errors with readable messages, so the model can recover — e.g. by searching before retrying a `get_note`.

## Architecture

![Architecture: MCP host talks JSON-RPC over stdio to the layered server, which persists to SQLite](docs/architecture.svg)

- **`db.py`** is pure Python + SQLite — it has no idea MCP exists. Normalized schema (`notes`, `tags`, `note_tags`) with `ON DELETE CASCADE` and orphan-tag pruning. Testable with plain pytest.
- **`tools.py`** is the protocol surface: thin wrappers that translate between MCP tool calls and the data layer, and own all the schema/description metadata the model sees.
- **`server.py`** wires them together and picks the database location.

## Quickstart

Requires Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/).

```bash
git clone <this repo> && cd notes-mcp
uv sync          # install dependencies into .venv
uv run pytest    # 38 tests: data layer + full MCP integration
uv run notes-mcp # runs the server on stdio (Ctrl-C to exit)
```

### Connect to Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "notes": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/notes-mcp", "notes-mcp"]
    }
  }
}
```

Restart Claude Desktop; the six tools appear under the `notes` server. Try: *“Add a note titled ‘Reading list’ with the books I mention, tagged reading.”*

### Connect to Claude Code

```bash
claude mcp add notes -- uv run --directory /ABSOLUTE/PATH/TO/notes-mcp notes-mcp
```

### Inspect interactively

The MCP Inspector gives you a debugging UI over any server:

```bash
npx @modelcontextprotocol/inspector uv run --directory /ABSOLUTE/PATH/TO/notes-mcp notes-mcp
```

## Data storage

Notes live in a single SQLite file, `~/.notes-mcp/notes.db` by default. Override with the `NOTES_MCP_DB` environment variable — in `claude_desktop_config.json`, add an `env` key inside the server entry, next to `command` and `args`:

```json
{
  "mcpServers": {
    "notes": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/notes-mcp", "notes-mcp"],
      "env": { "NOTES_MCP_DB": "/path/to/work-notes.db" }
    }
  }
}
```

For Claude Code, pass it with `-e`:

```bash
claude mcp add notes -e NOTES_MCP_DB=/path/to/work-notes.db -- \
  uv run --directory /ABSOLUTE/PATH/TO/notes-mcp notes-mcp
```

The default is an **absolute** path on purpose: MCP hosts launch servers with an arbitrary working directory, so a relative path would silently create a new database per launch location.

## Testing

Two layers, mirroring the architecture:

- [`tests/test_db.py`](tests/test_db.py) — unit tests for the storage layer: CRUD, tag dedup/pruning, Unicode case-insensitivity, literal wildcard handling, duplicate-title resolution, persistence across connections.
- [`tests/test_tools.py`](tests/test_tools.py) — integration tests that connect a **real MCP client session** to the server over the SDK's in-memory transport and exercise every tool through the full protocol stack: handshake, discovery, schema validation, structured output, and error paths.
- [`tests/test_server.py`](tests/test_server.py) — database-path resolution (`NOTES_MCP_DB` override, home expansion, absolute default).

![Test suite: 38 tests across data layer, server wiring, and MCP protocol integration](docs/tests.svg)

```bash
uv run pytest
```

## Project structure

```
notes-mcp/
├── pyproject.toml          # uv project; console script: notes-mcp
├── README.md
├── DEVLOG.md               # build log: decisions and why
├── src/notes_mcp/
│   ├── server.py           # entry point + FastMCP wiring
│   ├── tools.py            # the 6 MCP tool definitions
│   ├── models.py           # Pydantic output models (→ output schemas)
│   └── db.py               # SQLite data layer (MCP-free)
├── tests/
│   ├── test_db.py          # data-layer unit tests
│   ├── test_tools.py       # end-to-end MCP integration tests
│   └── test_server.py      # DB-path resolution tests
├── examples/demo.py        # runnable stdio demo (source of the image above)
└── docs/                   # README images
```

## Design decisions (short version — full rationale in [DEVLOG.md](DEVLOG.md))

- **Official `mcp` SDK, FastMCP API** — schemas derive from type hints, so the code and the contract can't drift apart.
- **Normalized tag schema** instead of a JSON column — real tag queries, dedup, and orphan cleanup in SQL. Each tag stores a display name plus a `casefold()`ed `name_key`, so one equality rule governs dedup and lookup.
- **Literal substring search with Unicode-correct case folding** — SQLite's built-in `NOCASE`/`LIKE` only fold ASCII, so search uses a registered `casefold` SQL function; no wildcard syntax surprises for the model. FTS5 is the documented upgrade path.
- **Microsecond UTC timestamps** — recency ordering must distinguish writes within the same second (a bug the test suite caught).

## Roadmap

- Full-text search via SQLite FTS5 (ranked results, prefix queries)
- MCP **resources** exposing notes as `notes://{id}` for direct context inclusion
- Note export (Markdown folder sync)