Herramientas de IA Nexus

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

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

1. Iniciar el servidor:

npm start

2. 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.

1. Haz un fork del repositorio

2. Crea tu rama de funciones (git checkout -b feature/amazing-feature)

3. Confirma tus cambios (git commit -m 'Add amazing feature')

4. Envía a la rama (git push origin feature/amazing-feature)

5. 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