Metadata-Version: 2.4
Name: upnote-lens-mcp
Version: 0.1.2
Summary: Let AI read, search, and summarize your UpNote notes — and create new ones — right from your chat.
Project-URL: Homepage, https://github.com/AwesomeHye/upnote-lens-mcp
Author: elsboo
License: MIT License
        
        Copyright (c) 2025  (original upnote-mcp project by chadthornton — https://github.com/chadthornton/upnote-mcp)
        Copyright (c) 2026 elsboo  (upnote-lens-mcp)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: mcp,notes,sqlite,upnote
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# upnote-lens-mcp

<!-- mcp-name: io.github.AwesomeHye/upnote-lens-mcp -->

A hybrid MCP server that lets your AI assistant work with your UpNote notes:

- **🔍 Find & search** notes by keyword across titles and bodies.
- **📖 Read & summarize** — it returns the *actual note text*, so the AI can
  summarize, analyze, or answer questions about what you've written.
- **✍️ Create** new notes from the chat.

Under the hood: reads come from the local UpNote SQLite database (**read-only**),
so real content comes back as text; writes go through the `upnote://` URL scheme
(x-callback-url) and **never touch the database**.

> The write side (URL scheme) is based on [chadthornton/upnote-mcp](https://github.com/chadthornton/upnote-mcp) (MIT).

## Usage

Once it's registered, just talk to your AI assistant in plain language — it
picks the right tool for you. No commands or syntax to memorize. For example:

- "Summarize my UpNote notes about the Q3 roadmap."
- "Find notes where I mentioned Postgres tuning and pull out the key points."
- "What did I write about onboarding last month?"
- "Show me my 5 most recent notes."
- "Create a note titled 'Standup 6/4' with today's three priorities."

Reading, searching, summarizing, and creating all happen through natural
conversation.

## Requirements

- **macOS** — fully supported and verified.
- **Windows** — best-effort. URLs launch through the registered scheme handler,
  and the default DB path is guessed under `%APPDATA%\UpNote\`. This path is
  **not verified** by the author — if reads fail, set `UPNOTE_LENS_DB` (see below).
- Python 3.10+ (or just [uv](https://docs.astral.sh/uv/), which brings its own).
- UpNote desktop app installed.

## Install & register

### 🤖 Let AI install it (easiest)

Give your MCP client (Claude, etc.) a link to
[`llms-install.md`](llms-install.md) and it will run the steps and set everything
up for you.

### 🧑 Install it yourself

Pick the first option that fits what you already have. Each option includes how
to register it in Claude.

> **Claude Desktop config file** (referenced in each option):
> - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
> - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

#### Option 1 — with uv (recommended)

Requires [uv](https://docs.astral.sh/uv/) installed once
(`brew install uv`, or `curl -LsSf https://astral.sh/uv/install.sh | sh`).
After that there's **no package install step** — `uvx` downloads, caches, and
runs upnote-lens-mcp on demand.

Claude Code:
```bash
claude mcp add upnote-lens -- uvx upnote-lens-mcp
```
Claude Desktop:
```json
{ "mcpServers": { "upnote-lens": { "command": "uvx", "args": ["upnote-lens-mcp"] } } }
```

#### Option 2 — with pip (if you don't have uv)

```bash
pip install upnote-lens-mcp
```

Claude Code:
```bash
claude mcp add upnote-lens -- upnote-lens-mcp
```
Claude Desktop:
```json
{ "mcpServers": { "upnote-lens": { "command": "upnote-lens-mcp" } } }
```

#### Option 3 — from GitHub over HTTPS (if you don't have pip)

When you can't use PyPI/pip, install straight from the repo with uv. (No uv yet?
`curl -LsSf https://astral.sh/uv/install.sh | sh`.)

Claude Code:
```bash
claude mcp add upnote-lens -- uvx --from git+https://github.com/AwesomeHye/upnote-lens-mcp upnote-lens-mcp
```
Claude Desktop:
```json
{ "mcpServers": { "upnote-lens": { "command": "uvx", "args": ["--from", "git+https://github.com/AwesomeHye/upnote-lens-mcp", "upnote-lens-mcp"] } } }
```

## Tools

### Read (queries the local DB → returns real text)

| Tool | Description |
|---|---|
| `search_notes(query, limit=20)` | Substring search over title/body. Returns id, title, updated time, snippet |
| `get_note(note_id, include_html=False)` | Full title + body text of a note (optionally raw HTML) |
| `list_recent(limit=20)` | Most recently updated notes |
| `list_notebooks()` | Notebooks with note counts and parent |
| `list_notes_in_notebook(notebook_id, limit=50)` | Notes inside a notebook |
| `list_tags()` | Tags with note counts |
| `list_notes_by_tag(tag_title, limit=50)` | Notes carrying a tag |

### Write (`upnote://` URL scheme)

| Tool | Description |
|---|---|
| `create_note(title, content, notebook?, markdown=True, new_window=False)` | Create a note. `content` is Markdown by default. `notebook` matches by name. **Tags can't be set** (see below) |
| `open_note(note_id, new_window=False)` | Open an existing note in the app |
| `open_notebook(notebook_id)` | Open a notebook in the app |

> **Tag limitation**: UpNote's `note/new` URL scheme has no tag parameter, and
> hashtags placed in the body stay as plain text rather than becoming real tags
> (they only convert to tags when typed in the editor). If you need tags, add
> them manually in the app after the note is created.

## Override the DB path

If the database isn't in the default location (or you're on Windows), point at it
with an environment variable:

```
UPNOTE_LENS_DB=/path/to/upnote.sqlite3
```

Default paths:
- macOS: `~/Library/Containers/com.getupnote.desktop/Data/Library/Application Support/UpNote/upnote.sqlite3`
- Windows (best guess): `%APPDATA%\UpNote\upnote.sqlite3`

## License

MIT. See [LICENSE](LICENSE) for details.
The URL-scheme formats and launch approach on the write side are adapted from
chadthornton/upnote-mcp (MIT).
