# notes-mcp

> An [MCP](https://modelcontextprotocol.io) server for a personal notes / knowledge base. Create, search, and retrieve notes — and let an AI assistant (Claude Desktop, Claude Code, …) work with them directly.

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard
that lets AI assistants securely call your tools and read your data. `notes-mcp`
is a small, self-contained MCP server that turns a folder of notes into something
an assistant can use in natural language — *"save this as a note tagged billing"*,
*"what did I write about late check-out?"*, *"summarize everything tagged onboarding"*.

It exercises all three MCP primitives:

| Primitive | What this server exposes |
| --------- | ------------------------ |
| **Tools** | `create_note`, `update_note`, `delete_note`, `get_note`, `search_notes`, `list_tags` |
| **Resources** | Every note at `note://<id>` — the client can pull note content straight into context |
| **Prompts** | `summarize_tag` — gathers all notes for a tag and asks the model to synthesize them |

## Tech

- **TypeScript** on Node 20+
- **`@modelcontextprotocol/sdk`** — the official MCP SDK (stdio transport)
- **Zod** — input schemas / validation
- **Zero native dependencies** — notes are stored in a plain JSON file, so there's
  nothing to compile. The storage layer is isolated in `src/store.ts`; swapping in
  SQLite later would touch only that file.
- **`node:test`** — the test suite spawns the built server and drives it over the
  real MCP protocol as a client would.

## Install & build

```bash
pnpm install     # or npm install
pnpm build       # compiles src → dist
pnpm test        # spawns the server and exercises the MCP protocol end-to-end
```

## Where notes are stored

A single JSON file at `~/.notes-mcp/notes.json` by default. Override the location
with the `NOTES_MCP_DIR` environment variable.

## Connect it to an assistant

The server speaks MCP over **stdio**, so any MCP client can launch it.

**Claude Desktop** — add to `claude_desktop_config.json`
(`~/Library/Application Support/Claude/` on macOS):

```json
{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/notes-mcp/dist/index.js"]
    }
  }
}
```

**Claude Code** — one command:

```bash
claude mcp add notes -- node /absolute/path/to/notes-mcp/dist/index.js
```

Then ask the assistant to create, search, or summarize notes — it will call the
tools above. To point the store somewhere specific, add an env var to the config
(`"env": { "NOTES_MCP_DIR": "/path/to/notes" }`).

## Try it without a client

The MCP Inspector is the quickest way to poke at the tools by hand:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Scripts

| Command          | What it does                                  |
| ---------------- | --------------------------------------------- |
| `pnpm build`     | Compile TypeScript to `dist/`                 |
| `pnpm watch`     | Recompile on change                           |
| `pnpm start`     | Run the built server on stdio                 |
| `pnpm test`      | Spawn the server and run the MCP round-trip   |
| `pnpm typecheck` | Type-check without emitting                   |

## How it's structured

```
src/
  store.ts    # file-backed note store: CRUD + search (no MCP knowledge)
  index.ts    # MCP server: wires the store to tools, resources, and prompts
test/
  smoke.test.mjs  # connects a real MCP client to the spawned server
```

Keeping `store.ts` free of any MCP types means the storage layer is testable on its
own and replaceable without touching the protocol wiring.

## License

MIT