📝 AI Sticky Notes — Python MCP-сервер

Облегченный, клиент-агностический Model Context Protocol (MCP)-сервер на Python, построенный на FastMCP. Этот сервер предоставляет AI-ассистентам (например, Claude Desktop, Google Antigravity, Cursor и любому MCP-совместимому клиенту) возможности постоянных заметок.

🌟 Ключевые возможности

Сервер реализует три основные примитива Model Context Protocol:

• 🛠️ Инструменты (Actions):

  • add_note(message: str) -> str: Добавляет новую заметку в локальный файл хранения.

  • read_notes() -> str: Считывает и возвращает все сохранённые заметки в виде одной строки.

• 📦 Ресурсы (Context Feeds):

  • notes://latest: Динамически предоставляет последнюю сохранённую заметку по настраиваемому URI.

• 💬 Промпты (переиспользуемые шаблоны LLM):

  • note_summary_prompt(): Генерирует готовый промпт, предписывающий ИИ обобщить все текущие заметки.

📂 Структура проекта

.
├── 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)

🚀 Начало работы

Предварительные требования

• Python 3.12+

• uv (рекомендуется для быстрого управления пакетами и окружением)

1. Установка

Клонируйте репозиторий и установите зависимости:

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

🧪 Запуск и тестирование

Вариант A: Интерактивный MCP Inspector (рекомендуется)

MCP Inspector предоставляет визуальный веб-интерфейс для тестирования инструментов, просмотра ресурсов и исполнения промптов в интерактивном режиме:

uv run mcp dev main.py

Откройте URL, отображаемый в терминале (обычно http://localhost:5173 или похожий), чтобы взаимодействовать с вашим сервером.

Вариант B: Интеграция с Claude Desktop

Добавьте определение сервера в ваш 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

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

💡 Совет по Linux / GUI-окружению: Если ваше десктопное окружение не наследует интерактивный PATH вашей оболочки (что вызывает spawn uv ENOENT), укажите абсолютный путь к вашему бинарю uv (например, /home/<user>/.local/bin/uv или /home/<user>/miniconda3/bin/uv). Подробнее см. БИТАКОРА_ОШИБОК.md.

Вариант C: Интеграция со стандартными MCP-клиентами (Cursor, Antigravity, свой CLI)

Настройте стандартный stdio-транспорт с помощью:

• Команда: uv

• Аргументы: ["--directory", "<ПУТЬ_К_ПРОЕКТУ>", "run", "main.py"]

📚 Справочник MCP API

Инструменты

Ресурсы

Промпты

🛠️ Разработка и устранение неполадок

Для подробного журнала изменений, обходных путей для Linux и типичных проблем при настройке обращайтесь к:

• 📓 ЖУРНАЛ_РАЗРАБОТКИ.md (Журнал на русском)

• 📘 MCP_PYTHON_SDK.md (Шпаргалка по SDK)

📄 Лицензия и благодарности

• Сделано на Model Context Protocol и FastMCP.

• Вдохновлено руководством по разработке MCP-сервера от Tech With Tim.