@slorenzot/memento-mcp-server

Model Context Protocol (MCP) server providing 15 memory tools for AI agent integration with Claude Desktop, VS Code, and other MCP clients.

🚀 Instalación

# Using Bun (recomendado)
bun add @slorenzot/memento-mcp-server

# Using npm
npm install @slorenzot/memento-mcp-server

💡 Uso Básico

TypeScript

import { MCPServer } from '@slorenzot/memento-mcp-server';

// Inicializar servidor MCP
const server = new MCPServer('./data/memento.db');

// Iniciar servidor (usa stdio para comunicación MCP)
// Nota: Este servidor está diseñado para ser ejecutado por clientes MCP
// No es necesario llamar start() manualmente en producción

Shell/Bun

# Ejecutar servidor MCP (recomendado)
npx -p @slorenzot/memento-mcp-server

# O usando bunx (si está instalado globalmente)
bunx @slorenzot/memento-mcp-server

# Usar con variable de entorno para base de datos personalizada
MEMENTO_DB_PATH=/custom/path/database.db npx -p @slorenzot/memento-mcp-server

🔧 API Esencial

Clase Principal

MCPServer(dbPath?: string)

Constructor del servidor MCP con integración automática al motor de memoria.

Parámetros:

• dbPath (opcional): Ruta al archivo de base de datos. Default: './data/memento.db'

Ejemplo:

const server = new MCPServer('./custom/path.db');

Métodos de Control

start()

Inicia el servidor MCP y comienza a escuchar solicitudes MCP via stdio.

Retorna: Promise<void>

Nota: Este método es llamado automáticamente cuando el servidor se inicia como proceso independiente.

close()

Detiene el servidor MCP y cierra la conexión con la base de datos.

Retorna: void

Ejemplo:

const server = new MCPServer();

// En cleanup o shutdown
server.close();

🛠️ Herramientas MCP Disponibles

El servidor proporciona 15 herramientas MCP para gestión de memoria:

Gestión de Observaciones

mem_save

Guarda una nueva observación en la memoria.

Parámetros:

{
  title: string;
  content: string;
  type?: 'decision' | 'bug' | 'discovery' | 'note';
  topic_key?: string;
  project_id?: string;
  metadata?: Record<string, unknown>;
}

Ejemplo de uso:

await mem_save({
  title: 'Decisión de arquitectura',
  content: 'Usar PostgreSQL en lugar de MySQL',
  type: 'decision',
  project_id: 'my-project'
});

mem_search

Busca observaciones usando búsqueda full-text.

Parámetros:

{
  query?: string;
  type?: 'decision' | 'bug' | 'discovery' | 'note';
  project_id?: string;
  topic_key?: string;
  limit?: number;
  offset?: number;
}

mem_get_observation

Obtiene una observación específica por ID.

Parámetros:

{
  id: number;
}

mem_update

Actualiza una observación existente.

Parámetros:

{
  id: number;
  title?: string;
  content?: string;
  type?: 'decision' | 'bug' | 'discovery' | 'note';
  topic_key?: string;
  metadata?: Record<string, unknown>;
}

mem_delete

Elimina una observación por ID.

Parámetros:

{
  id: number;
}

Gestión de Sesiones

mem_session_start

Inicia una nueva sesión para seguimiento de conversaciones.

Parámetros:

{
  project_id: string;
  metadata?: Record<string, unknown>;
}

mem_session_end

Finaliza una sesión activa.

Parámetros:

{
  id: number;
}

mem_list_sessions

Lista todas las sesiones del proyecto.

Parámetros:

{
  project_id?: string;
  limit?: number;
  offset?: number;
}

mem_get_session

Obtiene una sesión específica.

Parámetros:

{
  id: number;
}

Herramientas de Utilidad

mem_timeline

Obtiene una línea temporal de observaciones.

Parámetros:

{
  project_id?: string;
  session_id?: number;
  limit?: number;
  offset?: number;
}

mem_stats

Obtiene estadísticas del sistema de memoria.

Retorna: Métricas de uso, totales por tipo, etc.

mem_import

Importa observaciones desde JSON.

Parámetros:

{
  data: Array<{
    title: string;
    content: string;
    type?: string;
    project_id?: string;
  }>;
}

mem_export

Exporta observaciones a JSON.

Parámetros:

{
  project_id?: string;
  type?: string;
  limit?: number;
}

Herramientas de Sistema

mem_health

Verifica el estado del sistema de memoria.

Retorna: Estado de conexión, salud de base de datos, etc.

mem_config

Obtiene la configuración actual del servidor.

Retorna: Configuración de rutas, versión, etc.

⚡ Ejemplos Prácticos

Ejemplo 1: Integración con Claude Desktop

{
  "mcpServers": {
    "memento": {
      "command": "bun",
      "args": ["run", "node_modules/@slorenzot/memento-mcp-server/dist/index.js"],
      "env": {
        "DATABASE_PATH": "./data/memento.db"
      }
    }
  }
}

Ejemplo 2: Uso Programático del Servidor

import { MCPServer } from '@slorenzot/memento-mcp-server';

// Crear servidor personalizado
const server = new MCPServer('./memory.db');

// El servidor manejará automáticamente solicitudes MCP
// cuando sea ejecutado por un cliente MCP

// Para control manual (testing)
const toolResult = await server.handleToolCall('mem_save', {
  title: 'Test observación',
  content: 'Contenido de prueba',
  type: 'note',
  project_id: 'test-project'
});

console.log('Resultado:', toolResult);

// Cerrar cuando termine
server.close();

Ejemplo 3: Flujo Completo de Sesión

// Usando herramientas MCP a través del servidor

// 1. Iniciar sesión
const sessionStart = await mem_session_start({
  project_id: 'my-app',
  metadata: { agent: 'claude' }
});

console.log('Sesión iniciada:', sessionStart.id);

// 2. Guardar observaciones durante trabajo
await mem_save({
  title: 'Configuración completada',
  content: 'Servidor configurado en puerto 3000',
  type: 'decision',
  project_id: 'my-app'
});

// 3. Buscar decisiones anteriores
const searchResults = await mem_search({
  query: 'configuración servidor',
  type: 'decision'
});

console.log('Decisiones encontradas:', searchResults.observations);

// 4. Finalizar sesión
await mem_session_end({ id: sessionStart.id });

// 5. Obtener estadísticas
const stats = await mem_stats();
console.log('Total observaciones:', stats.total);
console.log('Por tipo:', stats.by_type);

🔗 Integración con Clientes MCP

Claude Desktop

{
  "mcpServers": {
    "memento": {
      "command": "bun",
      "args": [
        "run",
        "node_modules/@slorenzot/memento-mcp-server/dist/index.js"
      ],
      "env": {
        "DATABASE_PATH": "${userHome}/.memento/database.db"
      }
    }
  }
}

VS Code (con extensión MCP)

{
  "mcp.servers": {
    "memento": {
      "command": "bun",
      "args": [
        "run",
        "node_modules/@slorenzot/memento-mcp-server/dist/index.js"
      ]
    }
  }
}

⚠️ Licencia Restrictiva

Este paquete está bajo Licencia CC BY-NC-ND 4.0:

• ✅ Uso personal y educacional permitido
• ✅ Compartir con atribución al autor
• ❌ Uso comercial NO permitido
• ❌ Modificaciones o forks NO permitidos

Autor: Soulberto Lorenzo ([email protected])

🔄 Dependencias

Dependencias Principales

• @slorenzot/memento-core - Motor de memoria
• @modelcontextprotocol/sdk - SDK de Model Context Protocol
• zod - Validación de esquemas

Peer Dependencies

• bun v1.0+ (recomendado)
• node v20+ (compatible)

🛠️ Desarrollo

# Clonar el proyecto
git clone https://github.com/slorenzot/memento.git
cd memento/packages/mcp-server

# Instalar dependencias
bun install

# Desarrollo
bun run dev

# Build
bun run build

# Tests
bun test

📋 Changelog

[0.1.1] - 2024-04-04

• Fixed: Actualización de dependencias core
• Fixed: Corrección de método deleteObservation
• Updated: Mejora en validación de parámetros

[0.1.0] - 2024-04-04

• Added: Versión inicial del servidor MCP
• Added: 15 herramientas de gestión de memoria
• Added: Integración completa con Model Context Protocol
• Added: Soporte para Claude Desktop y VS Code

👤 Autor

Soulberto Lorenzo

• GitHub: @slorenzot
• Email: [email protected]

📄 Licencia

Este paquete está bajo Licencia Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International.

Ver Licencia Completa

⚠️ Importante: Este paquete tiene licencia restrictiva. Respeta los términos de la licencia CC BY-NC-ND 4.0.