README - AINotesMCPServer by izarlabs

📝 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

Clona este repositorio o crea un nuevo directorio:

mkdir ainotes
cd ainotes

Crea y activa un entorno virtual con uv:

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

Instala las dependencias:

uv add "mcp[cli]"

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:

Asegúrate de tener Claude Desktop instalado y actualizado.
Instala el servidor en Claude Desktop:

mcp install main.py

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:

Herramientas (Tools): Funciones que pueden ser llamadas por el LLM para realizar acciones (añadir y leer notas).
Recursos (Resources): Datos contextuales que pueden ser consumidos por los LLMs (la última nota).
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):

📄 Licencia

Este proyecto está bajo la Licencia MIT.