# 📝 AI Sticky Notes - Python MCP Server

A lightweight, client-agnostic **Model Context Protocol (MCP)** server built in Python using [FastMCP](https://github.com/modelcontextprotocol/python-sdk). This server exposes persistent note-taking capabilities to AI assistants (such as Claude Desktop, Google Antigravity, Cursor, and any MCP-compliant client).

---

## 🌟 Key Features

This server implements the three core primitives of the Model Context Protocol:

- 🛠️ **Tools (Action Execution)**:
  - `add_note(message: str) -> str`: Appends a new sticky note to the local storage file.
  - `read_notes() -> str`: Reads and returns all saved notes formatted as a single string.
- 📦 **Resources (Context Feeds)**:
  - `notes://latest`: Exposes the most recently saved note dynamically over a custom URI.
- 💬 **Prompts (Reusable LLM Templates)**:
  - `note_summary_prompt()`: Generates a ready-to-use prompt directing the AI to summarize all current sticky notes.

---

## 📂 Project Structure

```text
.
├── main.py                  # Primary FastMCP server implementation
├── main_final.py            # Clean reference implementation
├── notes.txt                # Persistent note storage (auto-generated)
├── pyproject.toml           # uv / Python package and dependency configuration
├── BITACORA_DE_ERRORES.md   # Troubleshooting log & root-cause analyses (Linux & PATH notes)
├── MCP_PYTHON_SDK.md        # FastMCP quick reference cheatsheet
└── README.md                # Project documentation (this file)
```

---

## 🚀 Getting Started

### Prerequisites

- **Python 3.12+**
- [**uv**](https://docs.astral.sh/uv/) (recommended for fast package and environment management)

### 1. Installation

Clone this repository and sync the dependencies:

```bash
git clone https://github.com/<your-username>/<your-repo-name>.git
cd <your-repo-name>
uv sync
```

---

## 🧪 Running & Testing

### Option A: Interactive MCP Inspector (Recommended)

The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) provides a visual web interface to test tools, inspect resources, and execute prompts interactively:

```bash
uv run mcp dev main.py
```

Open the URL displayed in the terminal (usually `http://localhost:5173` or similar) to interact with your server.

---

### Option B: Claude Desktop Integration

Add the server definition to your `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ai-sticky-notes": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project",
        "run",
        "main.py"
      ]
    }
  }
}
```

> **💡 Linux / GUI Environment Tip:** If your desktop environment does not inherit your shell's interactive `PATH` (causing `spawn uv ENOENT`), specify the absolute path to your `uv` binary (e.g. `/home/<user>/.local/bin/uv` or `/home/<user>/miniconda3/bin/uv`). See [BITACORA_DE_ERRORES.md](BITACORA_DE_ERRORES.md) for details.

---

### Option C: Integration with Standard MCP Clients (Cursor, Antigravity, Custom CLI)

Configure standard `stdio` transport using:
- **Command:** `uv`
- **Args:** `["--directory", "<PROJECT_PATH>", "run", "main.py"]`

---

## 📖 MCP API Reference

### Tools

| Name | Parameters | Return Type | Description |
| :--- | :--- | :--- | :--- |
| `add_note` | `message: str` | `str` | Adds a new note line to `notes.txt` |
| `read_notes` | *(none)* | `str` | Returns all recorded notes or `"No notes yet"` |

### Resources

| URI Pattern | Name / Description | Return Content |
| :--- | :--- | :--- |
| `notes://latest` | Get Latest Note | Text content of the last recorded note |

### Prompts

| Name | Arguments | Description |
| :--- | :--- | :--- |
| `note_summary_prompt` | *(none)* | Returns a prompt asking the AI model to summarize the current notes |

---

## 🛠️ Development & Troubleshooting

For a detailed changelog of debugging steps, Linux platform workarounds, and common setup issues encountered during development, refer to:
- 📓 [BITACORA_DE_ERRORES.md](BITACORA_DE_ERRORES.md) (Log in Spanish)
- 📘 [MCP_PYTHON_SDK.md](MCP_PYTHON_SDK.md) (SDK Cheatsheet)

---

## 📄 License & Credits

- Built with [Model Context Protocol](https://modelcontextprotocol.io/) and [FastMCP](https://github.com/modelcontextprotocol/python-sdk).
- Inspired by the MCP server development tutorial by [Tech With Tim](https://github.com/techwithtim/PythonMCPServer).