📝 AI Sticky Notes - Servidor MCP en Python

Un servidor Model Context Protocol (MCP) ligero e independiente del cliente, construido en Python con FastMCP. Este servidor expone capacidades de toma de notas persistentes a asistentes de IA (como Claude Desktop, Google Antigravity, Cursor y cualquier cliente compatible con MCP).

🌟 Características principales

Este servidor implementa las tres primitivas básicas del Model Context Protocol:

• 🛠️ Herramientas (Ejecución de acciones):

  • add_note(message: str) -> str: Añade una nueva nota adhesiva al archivo de almacenamiento local.

  • read_notes() -> str: Lee y devuelve todas las notas guardadas formateadas como una sola cadena.

• 📦 Recursos (Fuentes de contexto):

  • notes://latest: Expone la nota guardada más reciente dinámicamente a través de una URI personalizada.

• 💬 Prompts (plantillas de LLM reutilizables):

  • note_summary_prompt(): Genera un prompt listo para usar que le indica a la IA que resuma todas las notas adhesivas actuales.

📂 Estructura del Proyecto

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

🚀 Primeros pasos

Requisitos previos

• Python 3.12+

• uv (recomendado para la gestión rápida de paquetes y entornos)

1. Instalación

Clona este repositorio y sincroniza las dependencias:

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

🧪 Ejecución y pruebas

Opción A: Inspector MCP interactivo (Recomendado)

El Inspector MCP ofrece una interfaz web visual para probar herramientas, inspeccionar recursos y ejecutar prompts de forma interactiva:

uv run mcp dev main.py

Abre la URL que aparece en la terminal (normalmente http://localhost:5173 o similar) para interactuar con tu servidor.

Opción B: Integración con Claude Desktop

Añade la definición del servidor a tu 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"
      ]
    }
  }
}

💡 Consejo para entornos Linux / GUI: Si tu entorno de escritorio no hereda el PATH interactivo de tu shell (lo que provoca spawn uv ENOENT), especifica la ruta absoluta de tu binario uv (p. ej. /home/<user>/.local/bin/uv o /home/<user>/miniconda3/bin/uv). Consulta BITACORA_DE_ERRORES.md para más detalles.

Opción C: Integración con clientes MCP estándar (Cursor, Antigravity, CLI personalizado)

Configura el transporte stdio estándar usando:

• Comando: uv

• Argumentos: ["--directory", "<PROJECT_PATH>", "run", "main.py"]

📖 Referencia de la API de MCP

Herramientas

Recursos

Prompts

🛠️ Desarrollo y resolución de problemas

Para obtener un registro detallado de los pasos de depuración, de los workarounds para plataformas Linux y de los problemas de configuración habituales encontrados durante el desarrollo, consulta:

• 📓 BITACORA_DE_ERRORES.md (Registro en español)

• 📘 MCP_PYTHON_SDK.md (Hoja de referencia del SDK)

📄 Licencia y créditos

• Construido con Model Context Protocol y FastMCP.

• Inspirado en el tutorial de desarrollo de servidores MCP de Tech With Tim.