Modular Server

Servidor MCP (Model Context Protocol) centralizado y modular diseñado para conectar modelos de lenguaje (LLMs) con recursos corporativos críticos de forma segura, escalable y mantenible.

Su objetivo principal es eliminar silos de información y permitir que agentes inteligentes puedan interactuar con:

• Bases de datos MongoDB
• Repositorios GitHub
• Sistemas de archivos locales protegidos mediante sandbox

---

🎯 Características Principales

✅ Arquitectura modular y desacoplada

✅ Integración nativa con el protocolo MCP

✅ Gestión segura de repositorios GitHub

✅ Acceso controlado a MongoDB

✅ Sandbox dinámico para protección del sistema de archivos

✅ Auditoría y trazabilidad de acciones automatizadas

✅ Compatible con Claude Desktop y MCP Inspector

---

🏗️ Arquitectura

El proyecto implementa una arquitectura hexagonal dividida en tres capas:

[ Cliente MCP / Claude ]
           │
           ▼
┌──────────────────────────────────────┐
│ Capa de Aplicación (MCP Tools)       │
│ - mcp-server.js                      │
│ - database-tools.js                  │
│ - github-tools.js                    │
│ - file-system-tools.js               │
└───────────────┬──────────────────────┘
                │
                ▼
┌──────────────────────────────────────┐
│ Capa de Dominio (Services)           │
│ - database-service.js                │
│ - github-service.js                  │
│ - file-system-service.js             │
└───────────────┬──────────────────────┘
                │
                ▼
┌──────────────────────────────────────┐
│ Capa de Infraestructura              │
│ - mongodb.js                         │
│ - github.js                          │
│ - file-system.js                     │
└──────────────────────────────────────┘

Capas

1. Aplicación

Expone funcionalidades mediante MCP Tools, Resources y Prompts.

Responsabilidades:

• Definición de esquemas JSON
• Gestión de handlers
• Exposición de capacidades MCP

2. Dominio

Contiene la lógica de negocio:

• Orquestación de procesos
• Reglas de validación
• Políticas operativas

3. Infraestructura

Implementa la comunicación con sistemas externos:

• MongoDB
• GitHub API (Octokit)
• Sistema de archivos local

---

🔒 Seguridad

Sandbox Dinámico

El acceso al sistema de archivos está protegido mediante un sandbox configurable.

Protección contra Path Traversal

Se utilizan:

path.resolve()
path.normalize()

para garantizar que ninguna operación pueda salir de los directorios autorizados.

Ejemplo bloqueado:

../../../../etc/passwd

Recursos Protegidos

Acceso denegado a:

.env
.git
node_modules

Auditoría

Todas las acciones automáticas sobre GitHub incorporan la firma:

[TFM-AGENT]

permitiendo trazabilidad completa de cambios.

---

📂 Estructura del Proyecto

tfm-mcp/
│
├── index.js
├── pipeline.prompt
├── resumen_tfm.txt
│
├── src/
│   │
│   ├── application/
│   │   ├── mcp-server.js
│   │   └── tools/
│   │       ├── database-tools.js
│   │       ├── github-tools.js
│   │       └── file-system-tools.js
│   │
│   ├── domain/
│   │   ├── database-service.js
│   │   ├── github-service.js
│   │   └── file-system-service.js
│   │
│   └── infrastructure/
│       ├── mongodb.js
│       ├── github.js
│       └── file-system.js
│
└── .env

---

⚙️ Requisitos

• Node.js 18+
• MongoDB
• Token de GitHub con permisos de lectura/escritura

---

🚀 Instalación

1. Clonar repositorio

git clone <URL_REPOSITORIO>
cd tfm-mcp

2. Instalar dependencias

npm install

3. Configurar variables de entorno

Crear archivo .env:

# MongoDB
MONGODB_URI=mongodb://127.0.0.1:27017/tu_base_datos

# GitHub
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxx

# Directorio raíz autorizado
USER_HOME=C:/tfm-mcp

# Carpetas permitidas dentro del sandbox
ALLOWED_PATHS=workspace,logs,auditoria

---

🛠️ Herramientas MCP Disponibles

🍃 Base de Datos (MongoDB)

Herramienta	Descripción
listar_bases_de_datos	Lista todas las bases de datos
ver_colecciones	Muestra colecciones
crear_documento	Inserta documentos
contar_documentos	Cuenta registros
listar_documentos	Obtiene los últimos documentos
actualizar_documento	Actualiza registros
eliminar_documento	Elimina registros

---

🐙 GitHub

Herramienta	Descripción
ver_mis_repositorios	Lista repositorios del usuario
crear_repositorio	Crea repositorios privados
crear_rama_github	Genera ramas
crear_pull_request	Abre Pull Requests
subir_archivo_github	Crea o actualiza archivos

---

📂 Sistema de Archivos

Herramienta	Descripción
leer_archivo_local	Lee archivos autorizados
listar_archivos_proyecto	Explora directorios
clonar_proyecto_github	Clona repositorios
ejecutar_git_local	Ejecuta comandos Git permitidos

---

🔄 Integración con Claude Desktop

Agregar la siguiente configuración en:

claude_desktop_config.json

{
  "mcpServers": {
    "tfm-enterprise-agent": {
      "command": "node",
      "args": [
        "--env-file=C:\\tfm-mcp\\.env",
        "C:\\tfm-mcp\\index.js"
      ]
    }
  }
}

Ajusta las rutas según la ubicación real del proyecto.

---

🔍 Depuración

Para inspeccionar y probar el servidor MCP:

npx @modelcontextprotocol/inspector node index.js

Esto abrirá la interfaz oficial de diagnóstico MCP para validar herramientas, recursos y prompts.

---

📚 Recursos MCP

El servidor expone capacidades MCP mediante:

Tools

Herramientas ejecutables por el agente.

Resources

Recursos de solo lectura como:

resumen://tfm-info

Prompts

Plantillas reutilizables para auditoría, análisis y automatización.

---

👥 Autoría y Datos Académicos 🎓

• Autor: Edwin Patricio Arévalo Angulo
• Correo: [email protected]
• Proyecto: Trabajo Fin de Máster (TFM)
• Programa: Máster en Ingeniería de Software Cloud, Datos y Gestión TI
• Tema: Estudio y Prueba de Concepto sobre el Model Context Protocol: Eliminación de silos de información, gobernanza y seguridad en agentes de IA
• Convocatoria: 2025/2026