# 🚀 Servidor MCP Modular


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:

```text
[ 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:

```javascript
path.resolve()
path.normalize()
```

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

Ejemplo bloqueado:

```text
../../../../etc/passwd
```

### Recursos Protegidos

Acceso denegado a:

```text
.env
.git
node_modules
```

### Auditoría

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

```text
[TFM-AGENT]
```

permitiendo trazabilidad completa de cambios.

---

# 📂 Estructura del Proyecto

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

```bash
git clone <URL_REPOSITORIO>
cd tfm-mcp
```

## 2. Instalar dependencias

```bash
npm install
```

## 3. Configurar variables de entorno

Crear archivo `.env`:

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

```text
claude_desktop_config.json
```

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

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

```text
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:** edwareang@alum.us.es
* **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