Onyx MCP Server

Busca y consulta la documentación del lenguaje de programación Onyx y ejemplos de código en GitHub.

GitHubPrueba este MCPPatrocinado

Documentación

Onyx MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona acceso de búsqueda y consulta a la documentación del lenguaje de programación Onyx y a ejemplos de código de GitHub. El servidor incluye capacidades integrales de rastreo para poblar datos, pero el rastreo NO es accesible a través de la interfaz MCP, lo que garantiza una separación limpia entre la recopilación de datos y la funcionalidad de consulta.

🚀 Inicio Rápido

⚡ Acceso Instantáneo con NPX (¡Sin Instalación Requerida!)

Configura Claude Desktop (u otro LLM compatible con MCP):

{
  "mcpServers": {
    "onyx": {
      "command": "npx",
      "args": ["@onyxlang/mcp-server", "bridge", "--url", "https://mcp.onyxlang.io"]
    }
  }
}

🎆 ¡Eso es todo! Sin instalación, sin configuración, sin necesidad de rastreo de datos. Obtienes acceso instantáneo a la documentación y ejemplos más recientes de Onyx.

Instalación

Opción 1: Instalar desde npm (Recomendado)

# Install globally
npm install -g @onyxlang/mcp-server

# Or install locally in your project
npm install @onyxlang/mcp-server

Opción 2: Instalar desde el código fuente

git clone https://github.com/onyx-lang/onyx-mcp-server.git
cd onyx-mcp-server
npm install
cp .env.example .env
# Edit .env and add your GitHub token (optional but recommended)

Uso

Si se instala globalmente:

# Start MCP server
onyx-mcp server

# Start HTTP server
onyx-mcp http

# Start bridge to hosted server
onyx-mcp bridge --url https://mcp.onyxlang.io

# Crawl data (if running locally)
onyx-mcp crawl all

Si se instala localmente o desde el código fuente:

# Use npm scripts with arguments
npm start              # MCP server
npm run http           # HTTP server on default port (3001)
npm run http -- --port 3002  # HTTP server on custom port
npm run bridge         # Bridge to default (localhost:3001)
npm run bridge -- --url https://mcp.onyxlang.io  # Bridge to hosted server
npm run crawl:all      # Crawl all data

# Or run directly
node src/index.js server
node src/index.js http --port 3002
node src/index.js bridge --url https://mcp.onyxlang.io

Uso Básico

# Start the MCP server (default)
npm start

# Start the HTTP server for REST API access
npm run http
npm run http -- --port 3002  # Custom port

# Start the MCP-to-HTTP bridge (connects to local or remote HTTP server)
npm run bridge
npm run bridge -- --url https://mcp.onyxlang.io  # Connect to hosted server

# Run with development mode
npm run dev        # MCP server
npm run http:dev   # HTTP server

# Run tests
npm test

# Crawl data to populate the MCP (CLI only, not through MCP interface)
npm run crawl:all

🎯 Interfaz del Servidor

El sistema proporciona tanto funcionalidad de consulta MCP como rastreo basado en CLI:

# MCP Server operations (query/search only)
node src/index.js server          # Start MCP server  
node src/index.js server --dev    # Development mode
node src/index.js http            # Start HTTP server
node src/index.js http --port 3002 # HTTP server on custom port
node src/index.js bridge          # Start MCP-to-HTTP bridge
node src/index.js bridge --url https://mcp.onyxlang.io # Connect to hosted server

# Using npm scripts (with argument passing)
npm start                         # MCP server
npm run http                      # HTTP server (port 3001)
npm run http -- --port 3002       # HTTP server on custom port
npm run bridge                    # Bridge to localhost:3001
npm run bridge -- --url https://mcp.onyxlang.io  # Bridge to hosted server

# Data crawling (CLI only - NOT accessible through MCP)
node src/index.js crawl docs                    # Documentation only
node src/index.js crawl github repo1 repo2     # Specific repositories  
node src/index.js crawl url https://...        # Single URL
node src/index.js crawl all                     # Everything

# Utilities
node src/index.js test       # Run test suite
node src/index.js validate  # Validate setup

📁 Estructura del Proyecto

onyx_mcp/
├── src/
│   ├── bridge.js          # 🌉 MCP-to-HTTP bridge for remote access
│   ├── index.js           # 🎯 Unified entry point
│   ├── mcp-server.js      # 🌐 MCP server implementation
│   ├── mcp-http.js        # 🌐 MCP over HTTP server implementation 
│   ├── test.js            # 🧪 Test suite
│   ├── validate.js        # ✅ Setup validation
│   ├── crawlers/          # 📡 Data crawlers
│   │   ├── docs.js        #   - Documentation crawler
│   │   ├── github.js      #   - GitHub repository crawler  
│   │   └── urls.js        #   - URL content crawler
│   └── core/              # 🔧 Core functionality
│       └── search-engine.js #   - Search and indexing
├── data/                  # 📊 Crawled data (auto-generated)
├── .env.example          # 🔐 Environment template
└── package.json          # 📦 Dependencies & scripts

🛠️ Herramientas MCP Disponibles

El servidor proporciona estas herramientas de búsqueda y consulta de solo lectura a Claude:

📚 Documentación

  • search_onyx_docs - Buscar documentación oficial

🐙 Integración con GitHub

  • search_github_examples - Buscar código por tema
  • get_onyx_functions - Definiciones de funciones desde GitHub
  • get_onyx_structs - Definiciones de estructuras desde GitHub
  • list_github_repos - Listar repositorios disponibles

🔍 Búsqueda Unificada

  • search_all_sources - Buscar en todas las fuentes de datos

🚀 Ejecución de Código

  • run_onyx_code - Ejecutar código Onyx y devolver salida/errores para pruebas y depuración
  • run_wasm - Ejecutar código WebAssembly y devolver salida/errores para pruebas y depuración
  • build_onyx_code - Compilar archivo de código Onyx usando "onyx build" en un directorio especificado
  • onyx_pkg_build - Compilar un paquete Onyx usando "onyx pkg build" en un directorio especificado

⚠️ Nota Importante

Las herramientas de rastreo están disponibles a través del CLI pero intencionalmente NO son accesibles a través de la interfaz MCP. Esto garantiza una separación limpia entre la recopilación de datos y la funcionalidad de consulta.

🔧 Configuración

Variables de Entorno (.env)

# GitHub token (recommended for higher rate limits)
GITHUB_TOKEN=your_github_token_here

# Optional settings
DEBUG=false
MAX_CRAWL_LIMIT=50

🌐 Integración con Claude Desktop

Puedes conectarte al Onyx MCP de múltiples maneras:

⚡ Opción 1: Puente NPX (Instalación Cero)

Para servidor alojado (siempre actualizado):

{
  "mcpServers": {
    "onyx": {
      "command": "npx",
      "args": ["@onyxlang/mcp-server", "bridge", "--url", "https://mcp.onyxlang.io"]
    }
  }
}

Opción 2: Servidor MCP Local (Para Desarrollo)

{
 "mcpServers": {
   "onyx": {
     "command": "node",
     "args": ["/path/to/onyx_mcp/src/index.js", "server"]
   }
 }
}

Opción 3: Conectar a Servidor Alojado Personalizado mediante Puente

{
 "mcpServers": {
   "onyx": {
     "command": "node",
     "args": ["/path/to/onyx_mcp/src/index.js", "bridge", "--url", "https://mcp.onyxlang.io"],
   }
 }
}

Opción 4: Servidor HTTP Local + Puente

Para probar el puente localmente:

  1. Inicia el servidor HTTP: 
    npm run http --port 3002
  2. Configura Claude Desktop para usar el puente: 
    {
  "mcpServers": {
    "onyx": {
      "command": "node",
      "args": ["/path/to/onyx_mcp/src/index.js", "bridge", "--url", "http://localhost:3002"]
    }
  }
}

Para Desarrollo (Configuración Local)

  1. Clona y configura:

    git clone <repository>
cd onyx_mcp
npm install
cp .env.example .env

  2. Puebla los datos:

    npm run crawl:all

  3. Inicia el servidor MCP:

    npm start

  4. Configura Claude Desktop con el servidor local (consulta la sección de integración arriba)

Para Producción (Servidor Alojado)

  1. Clona y configura:

    git clone <repository>
cd onyx_mcp
npm install

  2. Inicia el servidor HTTP:

    npm run http

  3. Configura Claude Desktop con el puente (consulta la sección de integración arriba)

Arquitectura del Puente

El puente te permite conectar el protocolo MCP a servidores HTTP:

Claude Desktop → MCP Bridge → HTTP Server (Local or Remote)

Beneficios:

  • ✅ Conectar al Onyx MCP alojado en mcp.onyxlang.io
  • ✅ Sin necesidad de ejecutar un servidor local ni poblar datos
  • ✅ Siempre actualizado con la información más reciente de Onyx
  • ✅ Misma interfaz MCP, diferente backend
  • ✅ Cambio fácil entre servidores locales y remotos

🔄 Bucle de Pruebas y Retroalimentación de Código

Las herramientas de ejecución de código permiten a Claude probar, compilar y refinar código Onyx mediante retroalimentación iterativa:

Herramientas Disponibles:

  • run_onyx_code - Ejecutar código en sandbox para pruebas rápidas
  • build_onyx_code - Compilar archivos de código en el directorio especificado por el usuario
  • onyx_pkg_build - Compilar paquetes Onyx completos en el directorio del proyecto del usuario

Cómo Funciona:

  1. Claude escribe código Onyx basado en tus requisitos
  2. Prueba con run_onyx_code para validación rápida (sandbox)
  3. Compila con build_onyx_code en tu directorio de proyecto
  4. Lee los errores de compilación de la salida
  5. Analiza y corrige problemas - sintaxis, importaciones, dependencias
  6. Compila paquetes con onyx_pkg_build en tu directorio de proyecto
  7. Repite hasta el éxito - ¡código compilado y funcional en tu directorio!

Flujos de Trabajo de Ejemplo:

Pruebas Rápidas:

User: "Write a function to calculate fibonacci numbers"

1. Claude writes initial code
2. Tests with run_onyx_code (sandbox)
3. Sees errors and fixes them
4. Code runs successfully

Compilación de Proyectos:

User: "Build this code in my project at /home/user/myproject"

1. Claude uses build_onyx_code with directory: "/home/user/myproject"
2. Sees build errors and fixes imports
3. Creates working executable in user's directory
4. User can run the built program directly

Desarrollo de Paquetes:

User: "Build my Onyx package in /home/user/onyx-lib"

1. Claude uses onyx_pkg_build with directory: "/home/user/onyx-lib"
2. Fixes package configuration issues
3. Creates complete built package in user's directory
4. User can distribute/use the package

Beneficios:

  • ✅ Código autocorrectivo - Claude puede corregir sus propios errores
  • ✅ Validación real - Realmente ejecuta el código, no solo verifica sintaxis
  • ✅ Aprendizaje de errores - Mejora las sugerencias basándose en la retroalimentación del compilador de Onyx
  • ✅ Refinamiento iterativo - Sigue mejorando hasta que el código funcione perfectamente
  • ✅ Confianza en los resultados - Sabes que el código realmente compila y se ejecuta

Requisitos:

  • El compilador de Onyx debe estar instalado y disponible en PATH
  • Instalar desde: https://onyxlang.io/
  • La herramienta ejecuta código en un directorio temporal aislado (sandbox)
  • El tiempo de espera predeterminado de 10 segundos (configurable) previene bucles infinitos

📊 Fuentes de Datos y Rastreo

El sistema incluye capacidades integrales de rastreo para poblar datos:

📚 Fuentes de Documentación

  • Documentación oficial de Onyx
  • Archivos de tutoriales y guías
  • Documentación de API
  • Materiales de referencia del lenguaje

🐙 Fuentes de GitHub

  • Repositorios del lenguaje Onyx
  • Ejemplos de código y tutoriales
  • Documentación de paquetes y bibliotecas
  • Archivos de configuración y configuraciones de proyectos

📁 Tipos de Archivo Soportados

  • Archivos fuente .onyx
  • Archivos de configuración .kdl
  • Archivos README, documentación y guías
  • Páginas de documentación HTML
  • Configuraciones de paquetes (onyx.pkg, etc.)

🔄 Proceso de Población de Datos

  1. Usa comandos de rastreo CLI para poblar el directorio data/
  2. El servidor MCP busca en los datos pre-rastreados
  3. No hay disparadores de rastreo disponibles a través de la interfaz MCP

📡 Rastreo Mejorado de GitHub

El rastreador de GitHub extrae contenido integral:

📚 Documentación:

  • README.md, LICENSE, CHANGELOG.md
  • Toda la documentación en carpetas docs/
  • Documentación HTML y páginas web
  • Archivos de tutoriales y guías

🔧 Configuración:

  • Archivos .kdl (gestión de proyectos Onyx)
  • onyx.pkg y configuraciones de paquetes
  • Configuraciones TOML, YAML, JSON

💻 Código Fuente:

  • Todos los archivos fuente .onyx
  • Archivos de ejemplo y tutoriales
  • Ejemplos HTML e interfaces web

🌐 Contenido Web:

  • Páginas de documentación HTML
  • Ejemplos y demostraciones interactivas
  • Tutoriales y guías basados en web
  • Documentación de API en formato HTML

Gestión de Repositorios

# Crawl specific repositories
node src/index.js crawl github onyx-lang/onyx user/project

# With various URL formats
node src/index.js crawl github \
  https://github.com/onyx-lang/onyx \
  github.com/user/repo \
  owner/project

🧪 Pruebas y Validación

# Quick validation
npm run validate

# Full test suite  
npm test

# Expected results: 100% pass rate

Las pruebas validan:

  • ✅ Integridad de la estructura de archivos
  • ✅ Funcionalidad de importación de módulos
  • ✅ Operaciones del directorio de datos
  • ✅ Configuraciones del rastreador
  • ✅ Manejo de errores del motor de búsqueda

💡 Ejemplos de Uso

Una vez conectado a Claude Desktop:

"Show me examples of HTTP requests in Onyx"
"How do I define a struct with KDL configuration?"
"What are the available string manipulation functions?"
"Find PostgreSQL ORM examples in Onyx repositories"

🔧 Sistema de Contexto Configurable

Mensaje de Contexto Global

Todas las respuestas de las herramientas MCP incluyen un mensaje de contexto configurable que se puede modificar fácilmente en la parte superior de src/mcp-server.js:

// =============================================================================
// CONFIGURABLE CONTEXT MESSAGE
// =============================================================================
// This message will be prepended to all MCP tool responses.
// Modify this section to customize the context provided to the assistant.
const GLOBAL_CONTEXT_MESSAGE = `You are assisting with Onyx programming language queries...`;

Esto te permite:

  • Personalizar el contexto del asistente para consultas de Onyx
  • Proporcionar orientación consistente en todas las respuestas de las herramientas
  • Actualizar instrucciones fácilmente sin modificar herramientas individuales
  • Mantener coherencia de contexto a lo largo de las conversaciones

🚀 Principios Clave de Diseño

Seguridad y Separación de Preocupaciones

  • La interfaz MCP es de solo lectura - no puede disparar rastreo ni modificación de datos
  • Rastreo disponible a través del CLI - control total sobre la recopilación de datos
  • Arquitectura limpia - recopilación de datos separada de la funcionalidad de consulta
  • Sin llamadas API externas a través de las herramientas MCP

Experiencia de Usuario Mejorada

  • Contexto consistente en todas las respuestas
  • Mensajería específica por herramienta para mayor claridad
  • Manejo integral de errores con contexto
  • Compatibilidad heredada para flujos de trabajo existentes

🔍 Flujo de Datos

  1. Los comandos de rastreo CLI pueblan las fuentes de datos en el directorio data/
  2. El motor de búsqueda indexa y proporciona capacidades de búsqueda unificada
  3. El servidor MCP expone herramientas de búsqueda de solo lectura a Claude
  4. Claude recibe respuestas contextuales con mensajería configurable
  5. El sistema de contexto garantiza orientación consistente y útil en todas las respuestas
  6. No hay disparadores de rastreo disponibles a través de la interfaz MCP

📈 Rendimiento

  • Caché eficiente previene re-rastreos innecesarios
  • Limitación de velocidad respeta los límites de API
  • Procesamiento paralelo para múltiples repositorios
  • Manejo integral de errores para confiabilidad

Este servidor MCP proporciona a Claude acceso seguro y de solo lectura al conocimiento del lenguaje de programación Onyx a través de un sistema de contexto configurable. Las capacidades integrales de rastreo están disponibles mediante comandos CLI pero intencionalmente no son accesibles a través de la interfaz MCP, lo que garantiza una separación limpia entre la recopilación de datos y la funcionalidad de consulta.