Onyx MCP Server

Pesquise e consulte a documentação da linguagem de programação Onyx e exemplos de código do GitHub.

Documentação

Servidor Onyx MCP

Um servidor Model Context Protocol (MCP) que fornece acesso de busca e consulta à documentação da linguagem de programação Onyx e exemplos de código do GitHub. O servidor inclui recursos abrangentes de rastreamento para popular dados, mas o rastreamento NÃO é acessível através da interface MCP — garantindo uma separação clara entre coleta de dados e funcionalidade de consulta.

🚀 Início Rápido

⚡ Acesso Instantâneo com NPX (Sem Instalação Necessária!)

Configure o Claude Desktop (ou outro LLM compatível com MCP):

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

🎆 É isso! Sem instalação, sem configuração, sem necessidade de rastreamento de dados. Você obtém acesso instantâneo à documentação e exemplos mais recentes do Onyx.

Instalação

Opção 1: Instalar via npm (Recomendado)

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

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

Opção 2: Instalar a partir do código-fonte

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

Se instalado 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

Se instalado localmente ou a partir do código-fonte:

# 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

🎯 Interface do Servidor

O sistema fornece tanto a funcionalidade de consulta MCP quanto o rastreamento baseado em 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

📁 Estrutura do Projeto

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

🛠️ Ferramentas MCP Disponíveis

O servidor fornece estas ferramentas de busca e consulta somente leitura para o Claude:

📚 Documentação

search_onyx_docs - Pesquisar documentação oficial

🐙 Integração com GitHub

search_github_examples - Pesquisar código por tópico
get_onyx_functions - Definições de funções do GitHub
get_onyx_structs - Definições de structs do GitHub
list_github_repos - Listar repositórios disponíveis

🔍 Busca Unificada

search_all_sources - Pesquisar em todas as fontes de dados

🚀 Execução de Código

run_onyx_code - Executar código Onyx e retornar saída/erros para teste e depuração
run_wasm - Executar código WebAssembly e retornar saída/erros para teste e depuração
build_onyx_code - Compilar arquivo de código Onyx usando "onyx build" em um diretório especificado
onyx_pkg_build - Compilar um pacote Onyx usando "onyx pkg build" em um diretório especificado

⚠️ Nota Importante

As ferramentas de rastreamento estão disponíveis através do CLI, mas intencionalmente NÃO são acessíveis através da interface MCP. Isso garante uma separação clara entre coleta de dados e funcionalidade de consulta.

🔧 Configuração

Variáveis de Ambiente (.env)

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

# Optional settings
DEBUG=false
MAX_CRAWL_LIMIT=50

🌐 Integração com Claude Desktop

Você pode conectar-se ao Onyx MCP de várias maneiras:

⚡ Opção 1: Ponte NPX (Instalação Zero)

Para servidor hospedado (sempre atualizado):

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

Opção 2: Servidor MCP Local (Para Desenvolvimento)

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

Opção 3: Conectar a Servidor Hospedado Personalizado via Ponte

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

Opção 4: Servidor HTTP Local + Ponte

Para testar a ponte localmente:

Inicie o servidor HTTP:
```
npm run http --port 3002
```

Configure o Claude Desktop para usar a ponte:

{
  "mcpServers": {
    "onyx": {
      "command": "node",
      "args": ["/path/to/onyx_mcp/src/index.js", "bridge", "--url", "http://localhost:3002"]
    }
  }
}

Para Desenvolvimento (Configuração Local)

Clone e configure:

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

Popule os dados:
```
npm run crawl:all
```
Inicie o servidor MCP:
```
npm start
```
Configure o Claude Desktop com o servidor local (veja a seção de integração acima)

Para Produção (Servidor Hospedado)

Clone e configure:

git clone <repository>
cd onyx_mcp
npm install

Inicie o servidor HTTP:
```
npm run http 
```
Configure o Claude Desktop com a ponte (veja a seção de integração acima)

Arquitetura da Ponte

A ponte permite conectar o protocolo MCP a servidores HTTP:

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

Benefícios:

✅ Conecte-se ao Onyx MCP hospedado em mcp.onyxlang.io
✅ Sem necessidade de executar servidor local ou popular dados
✅ Sempre atualizado com as informações mais recentes do Onyx
✅ Mesma interface MCP, backend diferente
✅ Alternância fácil entre servidores locais e remotos

🔄 Teste de Código e Ciclo de Feedback

As ferramentas de execução de código permitem que o Claude teste, compile e refine código Onyx através de feedback iterativo:

Ferramentas Disponíveis:

run_onyx_code - Executar código em sandbox para testes rápidos
build_onyx_code - Compilar arquivos de código no diretório especificado pelo usuário
onyx_pkg_build - Compilar pacotes Onyx completos no diretório do projeto do usuário

Como Funciona:

Claude escreve código Onyx com base nos seus requisitos
Testa com run_onyx_code para validação rápida (sandbox)
Compila com build_onyx_code no diretório do seu projeto
Lê erros de compilação da saída
Analisa e corrige problemas - sintaxe, imports, dependências
Compila pacotes com onyx_pkg_build no diretório do seu projeto
Repete até obter sucesso - código compilado e funcional no seu diretório!

Exemplos de Fluxos de Trabalho:

Teste Rápido:

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

Compilação de Projeto:

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

Desenvolvimento de Pacotes:

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

Benefícios:

✅ Código autocorretivo - Claude pode corrigir seus próprios erros
✅ Validação real - Executa o código de fato, não apenas verificação de sintaxe
✅ Aprendizado com erros - Melhora sugestões com base no feedback do compilador Onyx
✅ Refinamento iterativo - Continua melhorando até o código funcionar perfeitamente
✅ Confiança nos resultados - Você sabe que o código realmente compila e executa

Requisitos:

Compilador Onyx deve estar instalado e disponível no PATH
Instale a partir de: https://onyxlang.io/
A ferramenta executa código em um diretório temporário em sandbox
Timeout padrão de 10 segundos (configurável) previne loops infinitos

📊 Fontes de Dados e Rastreamento

O sistema inclui recursos abrangentes de rastreamento para popular dados:

📚 Fontes de Documentação

Documentação oficial do Onyx
Arquivos de tutoriais e guias
Documentação de API
Materiais de referência da linguagem

🐙 Fontes do GitHub

Repositórios da linguagem Onyx
Exemplos de código e tutoriais
Documentação de pacotes e bibliotecas
Arquivos de configuração e configurações de projeto

📁 Tipos de Arquivo Suportados

Arquivos-fonte .onyx
Arquivos de configuração .kdl
README, documentação e arquivos de guia
Páginas de documentação HTML
Configurações de pacotes (onyx.pkg, etc.)

🔄 Processo de População de Dados

Use comandos de rastreamento CLI para popular o diretório data/
O servidor MCP pesquisa os dados pré-rastreados
Nenhum gatilho de rastreamento está disponível através da interface MCP

📡 Rastreamento Aprimorado do GitHub

O rastreador do GitHub extrai conteúdo abrangente:

📚 Documentação:

README.md, LICENSE, CHANGELOG.md
Toda a documentação nas pastas docs/
Documentação HTML e páginas web
Arquivos de tutoriais e guias

🔧 Configuração:

Arquivos .kdl (gerenciamento de projetos Onyx)
onyx.pkg e configurações de pacotes
Configurações TOML, YAML, JSON

💻 Código-Fonte:

Todos os arquivos-fonte .onyx
Arquivos de exemplo e tutoriais
Exemplos HTML e interfaces web

🌐 Conteúdo Web:

Páginas de documentação HTML
Exemplos interativos e demonstrações
Tutoriais e guias baseados na web
Documentação de API em formato HTML

Gerenciamento de Repositórios

# 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

🧪 Testes e Validação

# Quick validation
npm run validate

# Full test suite  
npm test

# Expected results: 100% pass rate

Os testes validam:

✅ Integridade da estrutura de arquivos
✅ Funcionalidade de importação de módulos
✅ Operações do diretório de dados
✅ Configurações do rastreador
✅ Tratamento de erros do mecanismo de busca

💡 Exemplos de Uso

Uma vez conectado ao 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 Configurável

Mensagem de Contexto Global

Todas as respostas das ferramentas MCP incluem uma mensagem de contexto configurável que pode ser facilmente modificada no topo 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...`;

Isso permite que você:

Personalize o contexto do assistente para consultas Onyx
Forneça orientação consistente em todas as respostas das ferramentas
Atualize facilmente as instruções sem modificar ferramentas individuais
Mantenha a coerência do contexto ao longo das conversas

🚀 Princípios de Design Principais

Segurança e Separação de Preocupações

Interface MCP é somente leitura - não pode acionar rastreamento ou modificação de dados
Rastreamento disponível via CLI - controle total sobre a coleta de dados
Arquitetura limpa - coleta de dados separada da funcionalidade de consulta
Nenhuma chamada de API externa através das ferramentas MCP

Experiência do Usuário Aprimorada

Contexto consistente em todas as respostas
Mensagens específicas por ferramenta para clareza
Tratamento abrangente de erros com contexto
Compatibilidade legada para fluxos de trabalho existentes

🔍 Fluxo de Dados

Comandos de Rastreamento CLI populam fontes de dados no diretório data/
Mecanismo de Busca indexa e fornece capacidades de busca unificada
Servidor MCP expõe ferramentas de busca somente leitura ao Claude
Claude recebe respostas contextuais com mensagens configuráveis
Sistema de Contexto garante orientação consistente e útil em todas as respostas
Nenhum gatilho de rastreamento disponível através da interface MCP

📈 Desempenho

Cache eficiente previne re-rastreamento desnecessário
Limitação de taxa respeita os limites da API
Processamento paralelo para múltiplos repositórios
Tratamento abrangente de erros para confiabilidade

Este servidor MCP fornece ao Claude acesso seguro e somente leitura ao conhecimento da linguagem de programação Onyx através de um sistema de contexto configurável. Recursos abrangentes de rastreamento estão disponíveis através de comandos CLI, mas intencionalmente não são acessíveis através da interface MCP, garantindo uma separação clara entre coleta de dados e funcionalidade de consulta.