# NoteAgent

[![npm version](https://img.shields.io/npm/v/apple-notes-agent-mcp.svg)](https://www.npmjs.com/package/apple-notes-agent-mcp)
[![license](https://img.shields.io/npm/l/apple-notes-agent-mcp.svg)](https://github.com/jayprajapati/apple-notes-agent-mcp/blob/main/LICENSE)

**Your AI coding agent's secondary brain.**

NoteAgent is an MCP (Model Context Protocol) server that connects AI coding agents — Claude Code, Cursor, OpenCode — with Apple Notes. Use it to capture debug sessions, log commit context, save code snippets, and manage notes without leaving your terminal.

> Built for developers who think in code and organize in notes.

## Quick Start

```bash
# Run directly (no install needed)
npx apple-notes-agent-mcp

# Or install globally
npm install -g apple-notes-agent-mcp
apple-notes-agent-mcp
```

## Why NoteAgent?

Existing Apple Notes MCP servers are generic note managers. NoteAgent is built for developers:

- **Developer workflows** — Pre-built templates for standups, debug sessions, commit logs
- **Code snippet capture** — Save language-aware snippets with file path context
- **Zero config** — `npx apple-notes-agent-mcp` just works on macOS
- **Health checks** — `doctor` tool verifies Notes.app permissions and connectivity
- **Error recovery** — Automatic retries with exponential backoff and clear error messages

## Installation

### Requirements

- macOS with Apple Notes.app
- Node.js >= 18
- Terminal/IDE with automation permissions (System Settings → Privacy & Security → Automation)

### npm (recommended)

```bash
npx apple-notes-agent-mcp
```

### Local development

```bash
git clone https://github.com/jayprajapati/apple-notes-agent-mcp.git
cd apple-notes-agent-mcp
npm install
npm run build
node dist/index.js
```

## MCP Client Configuration

### Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "noteagent": {
      "command": "npx",
      "args": ["apple-notes-agent-mcp"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "noteagent": {
      "command": "npx",
      "args": ["apple-notes-agent-mcp"]
    }
  }
}
```

### OpenCode

Add to your MCP configuration file:

```json
{
  "mcpServers": {
    "noteagent": {
      "command": "npx",
      "args": ["apple-notes-agent-mcp"]
    }
  }
}
```

## Tools (15 total)

### Note Operations

| Tool | Description |
|------|-------------|
| `create_note` | Create a new note with title and content |
| `get_note` | Get a note's content by title or ID |
| `update_note` | Update a note (replace, append, or prepend) |
| `delete_note` | Delete a note by title or ID |
| `list_notes` | List notes in a folder or account |
| `move_note` | Move a note to a different folder |

### Folder Operations

| Tool | Description |
|------|-------------|
| `create_folder` | Create a new folder |
| `delete_folder` | Delete a folder |
| `list_folders` | List all folders with note counts |

### Search & Account

| Tool | Description |
|------|-------------|
| `search_notes` | Search notes by keyword |
| `list_accounts` | List available Notes accounts |
| `get_recent_notes` | Get notes modified in last N hours/days |

### Developer Workflows

| Tool | Description |
|------|-------------|
| `create_dev_note` | Create a developer-formatted note (standup, debug, commit) |
| `create_snippet_note` | Save a code snippet with language and context |
| `doctor` | Run diagnostics on Notes.app connectivity and permissions |

## Usage Examples

### Create a note

```
Create a note titled "Meeting Notes" in the "Work" folder with today's action items.
```

The agent will use `create_note` with your content. Folders are created automatically if they don't exist.

### Debug session logging

```
Log this debugging session as a dev note. The issue was a race condition in the auth middleware.
Steps to reproduce: send two concurrent login requests.
Root cause: shared mutable state in session store.
Fix: use atomic operations.
```

The agent will use `create_dev_note` with the `debug` template.

### Save a code snippet

```
Save this code snippet to my notes — it's a TypeScript utility function from src/utils.ts
```

The agent will use `create_snippet_note` with the file path and language context.

### Search notes

```
Search my notes for anything about "deployment pipeline"
```

### Health check

```
Check if Notes.app is working properly with NoteAgent
```

The agent will run `doctor` to verify permissions and connectivity.

### Daily standup

```
Create a standup note for today. I finished the auth module and started on the API layer.
```

The agent will use `create_dev_note` with the `standup` template.

## Developer Templates

### Daily Standup (`standup`)
Pre-formatted with:
- What I did yesterday
- What I'll do today
- Blockers

### Debug Session (`debug`)
Pre-formatted with:
- Issue description
- Steps to reproduce
- Root cause analysis
- Fix applied

### Commit Log (`commit`)
Pre-formatted with:
- Commit message
- Files changed
- Context notes

### Code Snippet (`snippet`)
Includes:
- Language tag
- File path context
- Formatted code block

## Troubleshooting

### "Apple Notes access denied"

Grant automation permissions:
1. Open **System Settings**
2. Go to **Privacy & Security → Automation**
3. Enable access for your terminal app (Terminal, iTerm2, VS Code, etc.)

### "Apple Notes is not running"

Open Notes.app before using NoteAgent. The MCP server communicates with Notes via AppleScript.

### Notes not found

NoteAgent searches by exact title match. Use `list_notes` or `search_notes` to find the correct title.

### Connection issues

Run the diagnostic tool:
```
Run the doctor tool to check NoteAgent status
```

This verifies Notes.app is installed, running, and accessible.

## Architecture

```
src/
├── index.ts                 # MCP server entry point
├── types.ts                 # TypeScript interfaces
├── services/
│   ├── applescript.ts       # AppleScript executor with retry logic
│   └── notes-manager.ts     # High-level Notes operations
├── tools/
│   ├── note-tools.ts        # 6 note CRUD tools
│   ├── folder-tools.ts      # 3 folder management tools
│   ├── search-tools.ts      # 3 search/account tools
│   └── developer-tools.ts   # 3 developer workflow tools
└── utils/
    ├── helpers.ts           # Shared utilities
    └── parsing.ts           # AppleScript output parsing
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run integration tests (requires Notes.app)
npm run test:integration

# Type check
npm run lint
```

## License

MIT