MCP Tool Hub

Un hub modular y extensible de servidores múltiples Model Context Protocol — construido en TypeScript para equipos de automatización de TI.

Proporciona a tu LLM acceso a herramientas del mundo real: archivos, Git, contenido web y memoria persistente. Despliega en cualquier número de máquinas cliente simultáneamente mediante Ansible.

Arquitectura

mcp-tool-hub/
├── packages/
│   ├── core/              ← Shared types + BaseMCPServer abstract class
│   ├── server-filesystem/ ← Sandboxed local file access (read/write/list/delete)
│   ├── server-git/        ← Git log, diff, file contents, branches, status
│   ├── server-fetch/      ← Web fetching: HTML, JSON APIs, URL health checks
│   └── server-memory/     ← Persistent JSON knowledge base (survives restarts)
├── host/                  ← Orchestrator: registry + CLI + stdio JSON interface
├── ansible/               ← Playbook, inventory, systemd service templates
└── docs/                  ← How to add new servers (with template)

La arquitectura sigue el patrón del Model Context Protocol:

Cada servidor es completamente independiente: su propio paquete, su propia compilación
El registro en el host mapea toolName → server en tiempo de ejecución
La CLI expone una interfaz JSON stdio: cualquier integración de LLM envía {"toolName":"...", "arguments":{...}} a stdin y lee el resultado desde stdout
Añadir un nuevo servidor = crear un paquete, extender BaseMCPServer, registrar en cli.ts

Inicio rápido

1. Instalar y compilar

git clone https://github.com/your-org/mcp-tool-hub.git
cd mcp-tool-hub
npm install
npm run build

2. Configurar

cp .env.example .env
# Edit .env with your paths and settings

3. Ejecutar

# Via npm
npm run start --workspace=host

# Or directly
node host/dist/cli.js

4. Llamar a una herramienta

Envía JSON a stdin, obtén JSON desde stdout:

echo '{"toolName":"read_file","arguments":{"path":"hello.txt"}}' | node host/dist/cli.js

Herramientas disponibles

📁 Servidor de sistema de archivos

Todas las operaciones están aisladas en MCP_FS_ROOT. El recorrido de rutas (../) está bloqueado.

Herramienta	Descripción
`read_file`	Leer el contenido de un archivo (utf8 o base64)
`write_file`	Escribir o añadir contenido a un archivo
`list_directory`	Listar el contenido de un directorio (opcionalmente recursivo)
`delete_file`	Eliminar un archivo
`move_file`	Mover o renombrar un archivo
`get_file_info`	Obtener tamaño, fechas y tipo de una ruta

🔀 Servidor Git

Solo lectura. Sin operaciones de escritura.

Herramienta	Descripción
`git_log`	Historial de commits de un repositorio o archivo
`git_show_file`	Contenido de un archivo en un commit/rama específico
`git_diff`	Diferencias entre dos referencias
`git_status`	Estado del árbol de trabajo
`git_branches`	Listar ramas (locales + remotas opcionales)
`git_show_commit`	Detalles completos del commit y diferencias

🌐 Servidor de obtención (Fetch)

Admite una lista blanca de dominios opcional mediante MCP_FETCH_ALLOWED_DOMAINS.

Herramienta	Descripción
`fetch_url`	Obtener HTML o texto de una URL
`fetch_json`	Obtener y analizar una respuesta de API JSON
`check_url`	Comprobar si una URL es accesible (solicitud HEAD)

🧠 Servidor de memoria

Persistente tras reinicios. Respaldado por un archivo JSON.

Herramienta	Descripción
`memory_set`	Almacenar un valor con clave, espacio de nombres y etiquetas
`memory_get`	Recuperar un valor por clave
`memory_search`	Búsqueda de texto completo en todas las entradas
`memory_delete`	Eliminar una entrada
`memory_list_namespaces`	Listar todos los espacios de nombres con sus conteos
`memory_clear_namespace`	Eliminar todas las entradas en un espacio de nombres

Despliegue con Ansible

Despliega en todas tus máquinas cliente simultáneamente:

cd ansible

# First time
ansible-playbook -i inventory.yml deploy-mcp-hub.yml

# Update only (rebuild + restart)
ansible-playbook -i inventory.yml deploy-mcp-hub.yml --tags update

# Deploy to specific group
ansible-playbook -i inventory.yml deploy-mcp-hub.yml --limit servers

El playbook:

Instala Node.js 20 (si no está presente)
Crea un usuario de sistema dedicado mcp-hub
Copia y compila el proyecto
Escribe la configuración .env desde tus variables de Ansible
Instala e inicia un servicio systemd (reinicio automático en caso de fallo)

Las variables por host en inventory.yml te permiten configurar diferentes dominios permitidos, niveles de registro y rutas por grupo de máquinas.

Añadir un nuevo servidor

Consulta docs/adding-a-new-server.template.ts para ver la plantilla completa con comentarios.

En resumen:

// 1. Create packages/server-myservice/src/my-server.ts
export class MyServer extends BaseMCPServer {
  constructor(options: MyOptions) {
    super(SERVER_INFO, options);
    this.registerTool("my_tool", this.handleMyTool.bind(this));
  }
  private async handleMyTool(args) {
    return this.ok({ result: "done" });
  }
}

// 2. Register in host/src/cli.ts
hub.use(new MyServer({ apiKey: process.env.MY_API_KEY! }));

Ideas: server-slack, server-postgres, server-docker, server-ansible, server-ssh, server-jira

Variables de entorno

Variable	Predeterminado	Descripción
`MCP_DATA_DIR`	`./mcp-data`	Raíz para todos los datos del hub
`MCP_FS_ROOT`	`./mcp-data/files`	Raíz del entorno aislado del sistema de archivos
`MCP_GIT_WORKSPACE`	`./mcp-data/repos`	Ruta base de los repositorios Git
`MCP_MEMORY_PATH`	`./mcp-data/memory.json`	Archivo de almacenamiento de memoria
`MCP_FETCH_ALLOWED_DOMAINS`	(vacío = todos)	Lista blanca de dominios separados por comas
`MCP_LOG_LEVEL`	`info`	`debug	info	warn	error`

Notas de seguridad

Sistema de archivos: Estrictamente aislado. Los ataques de recorrido de rutas devuelven un error, no datos.
Git: Solo lectura. No se exponen operaciones de commit, push o clone.
Fetch: La lista blanca de dominios opcional evita SSRF a servicios internos.
Servicio Systemd: Se ejecuta como un usuario sin privilegios de root con PrivateTmp=true y NoNewPrivileges=true.

Requisitos

Node.js ≥ 18 (para la API fetch nativa)
Git (para server-git)
Linux con systemd (para el despliegue con Ansible)

mcp-tool-hub