# 📝 AiNotes Server

[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-brightgreen.svg)](https://modelcontextprotocol.io/)
[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Claude Desktop](https://img.shields.io/badge/Claude%20Desktop-Compatible-purple.svg)](https://claude.ai/download)

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

```python
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

```python
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

```python
# 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

```python
@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

```python
@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)

```python
@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

```python
@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](https://claude.ai/download) (para usar el servidor con Claude)

### Configuración del entorno

1. Clona este repositorio o crea un nuevo directorio:

```bash
mkdir ainotes
cd ainotes
```

2. Crea y activa un entorno virtual con uv:

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

3. Instala las dependencias:

```bash
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):

```bash
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:

```bash
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](https://modelcontextprotocol.io/docs/concepts/architecture)
- [Tutorial para desarrolladores](https://modelcontextprotocol.io/quickstart/server)
- [GitHub del SDK de Python](https://github.com/modelcontextprotocol/python-sdk)

## 📄 Licencia

Este proyecto está bajo la Licencia MIT.