# AI Notes MCP Server

[![CI](https://github.com/YOUR_USERNAME/ai-notes-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_USERNAME/ai-notes-mcp-server/actions/workflows/ci.yml)
![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-server-black)
![License: MIT](https://img.shields.io/badge/license-MIT-green)

An **MCP server** that gives AI assistants like Claude a personal knowledge base.
Ask the AI to save what you learn, find it again later, summarize a topic, or quiz you on it.

> **You:** "Save a note: list comprehensions build a list in one line, like `[x*x for x in range(10)]`. Tag it python."
> **AI:** *calls `add_note`* → "Saved note *Python list comprehensions*."
>
> **You:** "Quiz me on everything I noted about Python."
> **AI:** *uses the `study_quiz` prompt* → asks you 5 questions built from your own notes.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that connects AI applications to external tools and data.
Instead of building a custom integration for every AI app, you build **one MCP server**, and any MCP-compatible client
(Claude Desktop, IDEs, agents) can use it.

```mermaid
flowchart LR
    U[You] -->|chat| C[AI app<br/>e.g. Claude Desktop]
    C <-->|MCP over stdio<br/>JSON-RPC| S[AI Notes MCP Server]
    S <-->|read / write| F[(notes.json)]
```

## Features

This server uses all three MCP building blocks:

### 🛠 Tools — actions the AI can take

| Tool | What it does |
|------|--------------|
| `add_note` | Save a note with a title, Markdown content and tags |
| `search_notes` | Keyword search, ranked by relevance (title › tags › content) |
| `get_note` | Read one note in full |
| `list_notes` | List notes, newest first, optionally filtered by tag |
| `update_note` | Change title, content or tags of a note |
| `delete_note` | Delete a note (marked as *destructive*, so clients ask for confirmation) |
| `knowledge_stats` | Number of notes, words, tags and last activity |

### 📄 Resources — data the AI can read

| URI | Content |
|-----|---------|
| `notes://note/{id}` | Every note as a Markdown document |
| `notes://tags` | All tags with their note counts (JSON) |

### 💬 Prompts — ready-made tasks for the user

| Prompt | What it does |
|--------|--------------|
| `summarize_notes` | Summarizes all notes (or one tag), highlights key points and open questions |
| `study_quiz` | Creates quiz questions from your notes about a topic |

## Quick start

**Requirements:** [Node.js](https://nodejs.org) 18 or newer.

```bash
git clone https://github.com/YOUR_USERNAME/ai-notes-mcp-server.git
cd ai-notes-mcp-server
npm install
npm run build
```

Try it without any AI app — this starts the server and calls its tools like a real client would:

```bash
npm run demo
```

## Use it with Claude Desktop

1. Open Claude Desktop → **Settings → Developer → Edit Config**.
2. Add the server to `claude_desktop_config.json` (use the full path to **your** folder):

**Windows**
```json
{
  "mcpServers": {
    "ai-notes": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_NAME\\ai-notes-mcp-server\\dist\\index.js"]
    }
  }
}
```

**macOS / Linux**
```json
{
  "mcpServers": {
    "ai-notes": {
      "command": "node",
      "args": ["/Users/YOUR_NAME/ai-notes-mcp-server/dist/index.js"]
    }
  }
}
```

3. Restart Claude Desktop. The tools appear in the tools menu of the chat.

Notes are saved in `~/.ai-notes-mcp/notes.json`. To use another file, set the `NOTES_FILE` environment variable:

```json
"ai-notes": {
  "command": "node",
  "args": ["/path/to/ai-notes-mcp-server/dist/index.js"],
  "env": { "NOTES_FILE": "/path/to/my-notes.json" }
}
```

## Project structure

```
src/
├── index.ts    # Entry point: loads the notes file, starts the stdio transport
├── server.ts   # Registers the MCP tools, resources and prompts
└── store.ts    # NoteStore: storage, search ranking, atomic JSON persistence
tests/
├── store.test.ts   # Unit tests for storage and search
└── server.test.ts  # Integration tests: a real MCP client talks to the server
scripts/
└── demo.ts     # Starts the built server as a process and calls it over stdio
```

## Design decisions

- **Separation of concerns:** `NoteStore` knows nothing about MCP, and `server.ts` knows nothing about files.
  The storage can be swapped (for example for SQLite) without touching the MCP layer.
- **Input validation with Zod:** every tool has a schema, so invalid input (an empty title, too many tags)
  is rejected before it reaches the code, and the AI sees exactly which parameters exist.
- **Safe writes:** changes are written to a temporary file and then renamed, which is atomic —
  a crash can't leave a half-written `notes.json`.
- **Logging to stderr:** with the stdio transport, stdout carries the protocol messages,
  so anything printed there would break the connection.
- **Tool annotations:** read-only tools are marked `readOnlyHint` and `delete_note` is marked
  `destructiveHint`, so clients can decide when to ask the user for permission.

## Testing

```bash
npm test          # 15 unit + integration tests
npm run typecheck # strict TypeScript check
```

The integration tests connect a real MCP `Client` to the server over an in-memory transport,
so they test the server exactly the way an AI app uses it. GitHub Actions runs everything on Node 20 and 22 for every push.

## Ideas for next steps

- Semantic search with embeddings, so "car" also finds notes about "vehicles"
- SQLite storage for large knowledge bases
- Streamable HTTP transport to run the server remotely
- Import notes from Markdown files or an Obsidian vault

## Tech stack

TypeScript (strict) · Node.js · [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) · Zod · node:test · GitHub Actions

## License

MIT © Ibrahim Belkahla