Herramientas de IA Nexus

Un kit de herramientas integral del Protocolo de Contexto de Modelo para asistentes de IA

License: MIT Node Version TypeScript MCP

Transforma cualquier asistente de IA en un agente autónomo capaz de ejecutar tareas del mundo real.

Documentación • Primeros pasos • Hoja de ruta • Arquitectura

🎯 Descripción general

Nexus-MCP es un potente servidor de Protocolo de Contexto de Modelo (MCP) construido con TypeScript/Node.js que proporciona a los modelos de IA herramientas universales para:

📁 Operaciones del sistema de archivos (18 herramientas) - Leer, escribir, buscar y monitorear archivos
🌐 Solicitudes HTTP/Web (16 herramientas) - Obtener datos, extraer contenido de sitios web, llamar a APIs
🔄 Flujos de trabajo de Git (15 herramientas) - Clonar, confirmar, crear ramas y gestionar repositorios
Comandos del sistema (8 herramientas) - Ejecutar comandos de shell y gestionar procesos
🔧 Utilidades (8 herramientas, listas para código) - Análisis de JSON/YAML, compresión, cifrado y más

Estado actual: 49 herramientas listas para producción, 8 herramientas de utilidad implementadas en código (pendiente de integración de configuración)

🚀 Inicio rápido

Instalación

npm install -g nexus-ai-tools

Configuración

# Copy example environment file
cp .env.example .env

# Edit with your settings
nano .env

Ejecución

# Build the project
npm run build

# Run the MCP server (production)
npm start
# or
npm run start:mcp

# Run with CLI
npm run mcp

# Run in development mode
npm run dev

Integración con Claude Code

Añadir a la configuración de Claude Desktop:

{
  "mcpServers": {
    "nexus-mcp": {
      "command": "node",
      "args": ["/path/to/nexus-mcp/dist/index.js"]
    }
  }
}

Uso de sustitución de variables de entorno

Crear un archivo .env:

NEXUS_LOG_LEVEL=debug
DB_PASSWORD=secret123
ANTHROPIC_API_KEY=sk-ant-...

Usar en config.yaml:

server:
  log_level: "${NEXUS_LOG_LEVEL:-info}"
database:
  postgresql:
    password: "${DB_PASSWORD}"
ai:
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"

Validar las variables requeridas antes de comenzar:

import { validateEnvironment, loadConfig } from './config.js';

validateEnvironment(['ANTHROPIC_API_KEY', 'DB_PASSWORD']);
const config = loadConfig();

Uso del registrador contextual

import { ContextualLogger } from './logger.js';
import path from 'path';

const workDir = path.join(process.cwd(), 'logs');
const logger = ContextualLogger.create(workDir, 'workflow-001');

logger.info('workflow.started', { step: 1 });
logger.info('processing.data', { items: 100 });
logger.info('workflow.completed', { success: true });

logger.close();

Consulta la Guía de mejoras de configuración para obtener todos los detalles.

📦 Características

Herramientas de sistema de archivos

nexus_read_file - Leer archivos con soporte de codificación
nexus_write_file - Escribir/crear archivos
nexus_list_directory - Listar el contenido de directorios
nexus_search_files - Buscar archivos por patrón
nexus_search_content - Buscar contenido dentro de archivos
nexus_watch_directory - Monitorear cambios en directorios

Herramientas HTTP

nexus_http_get - Solicitudes HTTP GET
nexus_http_post - Solicitudes HTTP POST
nexus_fetch_url - Obtener y analizar contenido web
nexus_parse_html - Analizar HTML con Cheerio
nexus_call_api - Llamadas genéricas a API

Herramientas Git

nexus_git_clone - Clonar repositorios
nexus_git_commit - Crear confirmaciones (commits)
nexus_git_push - Enviar a remoto
nexus_git_pr_create - Crear solicitudes de extracción (pull requests)
Integración con GitHub, GitLab, Bitbucket

Herramientas de base de datos

nexus_db_query - Ejecutar consultas SQL
nexus_db_list_tables - Listar tablas de base de datos
nexus_db_describe_table - Describir el esquema de la tabla
Soporte para PostgreSQL, MySQL, SQLite, SQL Server, MongoDB

Herramientas del sistema

nexus_exec_command - Ejecutar comandos de shell
nexus_system_info - Obtener información del sistema
nexus_process_list - Listar procesos en ejecución
nexus_service_start/stop - Gestionar servicios

Herramientas de IA

nexus_llm_chat - Chatear con LLMs (Anthropic, OpenAI)
nexus_embedding_create - Crear incrustaciones (embeddings) de texto
nexus_text_summarize - Resumir texto
nexus_code_generate - Generar código

Herramientas de utilidades

nexus_json_parse/stringify - Manipulación de JSON
nexus_yaml_parse/stringify - Manipulación de YAML
nexus_zip_create/extract - Compresión ZIP
nexus_encrypt/decrypt - Cifrado/descifrado

🏗️ Arquitectura

┌─────────────────────────────────────────┐
│         Claude / LLM Client              │
└──────────────┬──────────────────────────┘
               │ MCP Protocol (stdio)
               ▼
┌─────────────────────────────────────────┐
│           Nexus-MCP Server               │
│  ┌───────────────────────────────────┐  │
│  │      MCP Server Core             │  │
│  └───────────────────────────────────┘  │
│         ┌───────┴───────┐                │
│         │               │                │
│    ┌────▼────┐    ┌────▼────┐           │
│    │ Filesys │    │   HTTP  │           │
│    └─────────┘    └─────────┘           │
│    ┌─────────┐    ┌─────────┐           │
│    │   Git   │    │ Database│           │
│    └─────────┘    └─────────┘           │
│    ┌─────────┐    ┌─────────┐           │
│    │  System │    │    AI   │           │
│    └─────────┘    └─────────┘           │
└─────────────────────────────────────────┘

Para una arquitectura detallada, consulta docs/architecture.md

🏛️ Calidad de nivel de producción

Nexus-MCP está construido pensando en la excelencia arquitectónica, diseñado para su uso en producción y adopción por la comunidad. Seguimos principios estrictos:

✅ Seguridad de tipos: Modo estricto de TypeScript + validación Zod
✅ Manejo de errores: Mensajes de error estructurados y procesables
✅ Rendimiento: Operaciones asíncronas, almacenamiento en caché, streaming
✅ Seguridad: Validación de entrada, saneamiento, registros de auditoría
✅ Observabilidad: Registro estructurado, métricas, rastreo
✅ Capacidad de prueba: Cobertura superior al 80%, inyección de dependencias
✅ Documentación: JSDoc, ejemplos, guías completas
✅ Experiencia del desarrollador: Errores claros, soporte para IDE, retroalimentación rápida

Consulta los Principios arquitectónicos para obtener todos los detalles.

⚙️ Mejoras de configuración y registro

Nexus-MCP incluye funciones avanzadas de configuración y registro inspiradas en sistemas de producción:

Sustitución de variables de entorno

Usa la sintaxis ${VAR_NAME} en archivos YAML para sustituir variables de entorno:

server:
  log_level: "${NEXUS_LOG_LEVEL:-info}"  # Uses env var, defaults to "info"
database:
  postgresql:
    password: "${DB_PASSWORD}"  # Required - warns if not set

Beneficios:

Mantener datos confidenciales (claves API, contraseñas) en variables de entorno
Usar configuraciones diferentes para entornos diferentes
Sobrescribir valores específicos sin editar archivos YAML

Registrador contextual

Registro específico del flujo de trabajo con archivos de registro separados por contexto:

import { ContextualLogger } from './logger.js';

const logger = ContextualLogger.create(workDir, 'migration-123');
logger.info('workflow.started', { step: 1 });
logger.info('extract.completed', { schemaPath: '/path/to/schema.json' });
logger.close();

Beneficios:

Rastrear flujos de trabajo de extremo a extremo (migraciones, tareas, trabajos por lotes)
Depurar operaciones complejas de varios pasos
Mantener los registros organizados por flujo de trabajo/ID de correlación
Análisis histórico de flujos de trabajo específicos

Documentación: Consulta la Guía de mejoras de configuración para obtener todos los detalles.

📖 Documentación

Guía de primeros pasos - Inicio rápido y uso básico
Documentación de arquitectura - Arquitectura y diseño del sistema
Principios arquitectónicos - Principios de diseño y mejores prácticas
Mejoras de configuración - Sustitución de variables de entorno y registro contextual
Referencia de API - Documentación completa de la API
Referencia de herramientas - Documentación detallada de las herramientas
Hoja de ruta - Hoja de ruta de desarrollo y progreso

🛠️ Desarrollo

# Clone repository
git clone https://github.com/your-org/Nexus-MCP.git
cd Nexus-MCP

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Lint code
npm run lint

📊 Estado del proyecto

Versión actual: 1.0.0-alpha
Estado de desarrollo: Desarrollo activo
Progreso principal: 36% (9/12 fases completadas)
Herramientas implementadas: 57 listas para producción, 8 implementadas en código (pendiente de configuración)
Herramientas objetivo: 50+ ✅ (superado)
Integración de IA: Ollama + Gemini + OpenAI + Anthropic Claude ✅ (8 herramientas)
CLI mejorada: CLI de herramientas de IA interactiva con colores y métricas ✅
Cobertura de pruebas: 49 pruebas implementadas (35 unitarias + 1 de integración + 13 E2E)
Estado de las pruebas: ✅ Todas superadas (49/49)
Documentación: 85% completa (Instalación, Configuración, API, Ejemplos, Guía de IA)
Estado de compilación: ✅ Superado
Ejecutable: ✅ Listo para despliegue
CLI: ✅ Funcional

Consulta ROADMAP.md para ver el progreso detallado.

🤖 Integración de herramientas de IA

Nexus-MCP incluye integración con 4 proveedores principales de IA:

Ollama (2 herramientas): LLMs locales - Chat + Listar modelos
Gemini (2 herramientas): Google AI - Chat + Listar modelos
OpenAI (2 herramientas): Modelos GPT - Chat + Listar modelos
Anthropic (2 herramientas): Modelos Claude - Chat + Listar modelos

Inicio rápido con herramientas de IA

# Configure API keys
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export OLLAMA_HOST="http://localhost:11434"

# Run the interactive AI CLI
node examples/ai-interactive-cli.js

# Or run the enhanced demo
node examples/ai-enhanced-demo.js

Consulta la Guía de herramientas de IA para obtener documentación detallada.

🔌 Integración MCP

Nexus-MCP es un servidor MCP (Protocolo de Contexto de Modelo) que permite a asistentes de IA como Claude Code utilizar sus 57 herramientas.

Inicio rápido con MCP

Iniciar el servidor:

npm start

Configurar Claude Desktop para conectarse a Nexus-MCP

Consulta la Guía de configuración de MCP para obtener instrucciones de configuración detalladas.

Categorías de herramientas disponibles

Sistema de archivos (18 herramientas): Leer, escribir, listar, buscar archivos
HTTP (16 herramientas): Solicitudes, extracción, APIs
Git (15 herramientas): Clonar, confirmar, ramas, PRs
Sistema (8 herramientas): Comandos, procesos, información del sistema
IA (8 herramientas): Chatear con Ollama, Gemini, OpenAI, Anthropic
Utilidades (8 herramientas): JSON, YAML, compresión, cifrado

🤝 Contribución

¡Las contribuciones son bienvenidas! Por favor, lee nuestras pautas de contribución antes de enviar PRs.

Haz un fork del repositorio
Crea tu rama de funciones (git checkout -b feature/amazing-feature)
Confirma tus cambios (git commit -m 'Add amazing feature')
Envía a la rama (git push origin feature/amazing-feature)
Abre una solicitud de extracción (Pull Request)

📄 Licencia

Este proyecto está bajo la Licencia MIT - consulta el archivo LICENSE para obtener más detalles.

🙏 Reconocimientos

Protocolo de Contexto de Modelo
Anthropic Claude
SDK de MCP para TypeScript
App Migración SOUL - Patrones de configuración e inspiración de registro contextual

📞 Soporte

📖 Documentación
🐛 Rastreador de problemas
💬 Comunidad de Discord
✉️ Correo electrónico: support@nexus-mcp.dev

Construido con ❤️ por el equipo de Nexus

Nexus-MCP