📝 AiNotes Server

Un servidor MCP (Model Context Protocol) para crear, almacenar y recuperar notas de texto de forma sencilla a través de una interfaz de IA conversacional como Claude Desktop. Este pequeño proyecto está enfocado para entender los conceptos básicos sobre MCP: tools, resources y prompts.

🌟 Características

• ✅ Añadir nuevas notas
• 📖 Leer todas las notas almacenadas
• 🔍 Obtener la última nota añadida
• 📊 Generar resúmenes de notas mediante IA

📚 Explicación del Código

Este proyecto implementa un servidor MCP (Model Context Protocol) para gestionar notas de texto. Vamos a desglosar cada parte del código para entender su funcionamiento.

Importación de Módulos

from mcp.server.fastmcp import FastMCP
import os

• FastMCP: La clase principal del SDK de MCP en Python que facilita la creación de servidores MCP.
• os: Módulo de Python para interactuar con el sistema operativo, usado aquí para manejar rutas de archivos.

Configuración del Archivo de Notas

NOTES_FILE = os.path.join(os.path.dirname(__file__), "ainotes.txt")

def check_and_create_file():
    """
    Comprueba  la existencia del fichero de texto donde
    se guardan las notas. Si no existe se crea vacio
    """
    if not os.path.exists(NOTES_FILE):
        with open(NOTES_FILE, "w") as f:
            f.write("")

• NOTES_FILE: Define la ruta al archivo de texto donde se guardarán las notas.
• check_and_create_file(): Función utilitaria que verifica si el archivo existe y lo crea vacío si no.

Creación del Servidor MCP

# Create an MCP server
mcp = FastMCP("AiNotesServer")

Instancia un nuevo servidor MCP con el nombre "AiNotesServer". Este objeto será usado para registrar herramientas, recursos y prompts.

Herramientas (Tools)

1. Añadir una Nota

@mcp.tool()
def add_note(message: str) -> str:
    """
    Añade una nueva nota al fichero de notas.

    Args:
        message (str): La nota a ser añadida.

    Returns:
        str: Mensaje de confirmación de que se ha añadido la nota.
    """
    check_and_create_file()
    with open(NOTES_FILE, "a") as f:
        f.write(message + "\n")
    return "Nota añadida"

• @mcp.tool(): Decorador que registra la función como una herramienta en el servidor MCP.
• La función recibe un mensaje de texto y lo añade al archivo de notas.
• Los comentarios en formato docstring proporcionan información que el LLM utilizará para entender cómo invocar la herramienta.

2. Leer Todas las Notas

@mcp.tool()
def read_notes() -> str:
    """
    Lee y devuelve todas las notas del fichero de notas.

    Returns:
        str: Devuelve todas las notas separadas por saltos de linea.
             Si no hubiera notas se devuelve un mensaje.
    """
    check_and_create_file()
    with open(NOTES_FILE, "r") as f:
        content = f.read().strip()
    return content or "No se han encontrado notas."

• Esta herramienta lee todas las notas almacenadas y las devuelve como una cadena de texto.
• Si no hay notas, devuelve un mensaje indicándolo.

Recursos (Resources)

@mcp.resource("notes://latest")
def get_latest_note() -> str:
    """
    Devuelve la ultima nota añadida al fichero.

    Returns:
        str: La ultima nota. En caso de no existir, se devuelve un mensaje.
    """
    check_and_create_file()
    with open(NOTES_FILE, "r") as f:
        lines = f.readlines()
    return lines[-1].strip() if lines else "No se han encontrado notas."

• @mcp.resource("notes://latest"): Decorador que registra la función como un recurso en el servidor MCP.
• Los recursos en MCP son entidades que proporcionan datos contextuales, en este caso, la última nota añadida.
• El URI notes://latest es cómo el cliente accederá a este recurso.

Prompts

@mcp.prompt()
def note_summary_prompt() -> str:
    """
    Mediante un prompt se le solicita a la IA que haga un resumen de las notas

    Returns:
        str: Un prompt con las notas solicitando un resumen de las mismas.
             Si no existen notas se devuelve un mensaje.
    """
    check_and_create_file()
    with open(NOTES_FILE, "r") as f:
        content = f.read().strip()
    if not content:
        return "No se han encontrado notas."

    return f"Hazme un resumen de las siguientes notas: {content}"

• @mcp.prompt(): Decorador que registra la función como un prompt en el servidor MCP.
• Los prompts son plantillas predefinidas para interacciones con la IA.
• Este prompt solicita a la IA que haga un resumen de todas las notas almacenadas.

🚀 Instalación y Uso

Requisitos previos

• Python 3.10 o superior
• Claude Desktop (para usar el servidor con Claude)

Configuración del entorno

1. Clona este repositorio o crea un nuevo directorio:

mkdir ainotes
cd ainotes

2. Crea y activa un entorno virtual con uv:

uv init .
uv venv
source .venv/bin/activate  # En Windows: .venv\Scripts\activate

3. Instala las dependencias:

uv add "mcp[cli]"

4. Se ha creado un archivo main.py en el cual escribiremos el código.

Prueba con el Inspector MCP

Para probar el servidor usando el Inspector MCP (una herramienta visual para inspeccionar servidores MCP):

mcp dev main.py

Esto abrirá una interfaz web donde podrás explorar y probar las herramientas, recursos y prompts del servidor. Para que funcione correctamente debe de tener instalado en su ordenador Node y sus dependencías.

Instalación en Claude Desktop

Para usar el servidor con Claude Desktop:

1. Asegúrate de tener Claude Desktop instalado y actualizado.

2. Instala el servidor en Claude Desktop:

mcp install main.py

3. Reinicia Claude Desktop para que reconozca el nuevo servidor.

💡 Uso con Claude Desktop

Una vez instalado, puedes interactuar con tu servidor AiNotes a través de Claude Desktop:

• Añadir una nota: "Por favor, añade esta nota: Reunión con el equipo mañana a las 10 AM"
• Leer notas: "¿Puedes mostrarme todas mis notas?"
• Ver última nota: "¿Cuál fue mi última nota?"
• Resumir notas: "Haz un resumen de mis notas, por favor"

Claude utilizará automáticamente las herramientas, recursos y prompts expuestos por tu servidor MCP según sea necesario para responder a tus solicitudes.

🛠️ Estructura del Protocolo MCP

Este proyecto utiliza tres primitivas principales de MCP:

1. Herramientas (Tools): Funciones que pueden ser llamadas por el LLM para realizar acciones (añadir y leer notas).
2. Recursos (Resources): Datos contextuales que pueden ser consumidos por los LLMs (la última nota).
3. Prompts: Plantillas predefinidas para tareas específicas (resumen de notas).

Cada uno de estos componentes sirve para un propósito diferente en la interacción entre la aplicación y el modelo de lenguaje.

🛠️ Mejoras

Este proyecto es educativo por lo que se ha obviado cierta funcionalidad para simplicarlo al máximo,como la gestión de Excepciones.

• Añadir excepciones relacionadas con el fichero de notas.
• Cambiar el uso de un fichero de texto por una base de datos Sqllite, con las modificaciones pertienentes en las tools.
• Gestion de prioridades y fechas en las notas.

📘 Más información

Para aprender más sobre el Protocolo de Contexto de Modelo (MCP):

• Documentación MCP
• Tutorial para desarrolladores
• GitHub del SDK de Python

📄 Licencia

Este proyecto está bajo la Licencia MIT.