Nexus

---

O que é o Nexus?

O Nexus é um servidor de Protocolo de Contexto de Modelo (MCP) que fornece funcionalidade de busca com tecnologia de IA através da API OpenRouter. Ele se integra a clientes compatíveis com MCP, incluindo Claude Desktop e Cursor, fornecendo recursos de busca por meio de múltiplas famílias de modelos, incluindo Perplexity Sonar (busca web em tempo real) e Grok 4 (conhecimento de dados de treinamento).

Características Principais

• Implantação sem instalação: Executável via bunx (ou npx) sem requisitos de compilação
• Integração OpenRouter: Múltiplos modelos de IA, incluindo Perplexity Sonar (busca web) e Grok 4 (dados de treinamento)
• Conformidade com o protocolo MCP: Implementa interfaces padrão de ferramentas e recursos MCP
• Arquitetura de produção: Inclui cache de requisições, deduplicação, lógica de repetição e tratamento de erros
• Implementação type-safe: Cobertura completa em TypeScript com verificação estrita de tipos

Recursos

Implantação

• Execução baseada em Bunx/NPX com zero instalação local
• Compatibilidade multiplataforma (macOS, Linux, Windows)
• Requisito de runtime Bun 1.0+ ou Node.js 18+
• Atualizações automáticas de versão via registro npm

Capacidades de Busca

• Múltiplos níveis de modelos com diferentes capacidades:
  • sonar - Perguntas e respostas rápidas, busca web em tempo real (timeout de 30s, nível padrão)
  • sonar-pro - Consultas de múltiplas etapas, busca web em tempo real (timeout de 60s, nível premium)
  • sonar-reasoning-pro - Raciocínio em cadeia de pensamento, busca web em tempo real (timeout de 120s, nível premium)
  • sonar-deep-research - Relatórios de pesquisa exaustivos, busca web em tempo real (timeout de 300s, nível premium)
  • grok-4 - Conhecimento de dados de treinamento, sem busca em tempo real (timeout de 60s, nível premium)
• Busca web em tempo real com informações atuais (modelos Perplexity)
• Respostas com conhecimento de dados de treinamento (Grok 4)
• Extração estruturada de citações das respostas
• Parâmetros de modelo configuráveis (temperatura, tokens máximos, substituição de timeout)

Arquitetura

• Tratamento abrangente de erros com classes de erro tipadas
• Cache de requisições com TTL configurável
• Deduplicação de requisições para consultas idênticas simultâneas
• Lógica automática de repetição com backoff exponencial
• Registro estruturado baseado em Winston
• Implementação em modo estrito TypeScript com cobertura completa de tipos

Início Rápido

Pré-requisitos

• Bun 1.0+ (recomendado) ou Node.js 18+
• Chave de API OpenRouter (registre-se em openrouter.ai)

Instalação Rápida

Execute o servidor sem instalação local:

# Set your OpenRouter API key
export OPENROUTER_API_KEY=your-api-key-here

# Run the server via bunx (recommended)
bunx nexus-mcp

# Or via npx
npx nexus-mcp

O servidor inicia e escuta conexões de clientes MCP via transporte STDIO.

Testando a Instalação

# Test the CLI help
bunx nexus-mcp --help

# Test the version
bunx nexus-mcp --version

# Run with your API key
OPENROUTER_API_KEY=your-key bunx nexus-mcp

Alternativa: Instalação Local para Desenvolvimento

Para desenvolvimento local ou personalização:

1. Clone o repositório:

git clone https://github.com/adawalli/nexus.git
cd nexus

2. Instale as dependências:

bun install

3. Compile o servidor:

bun run build

4. Configure sua chave de API OpenRouter:

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

# Edit .env and add your actual API key
# OPENROUTER_API_KEY=your-api-key-here

5. Teste o servidor:

bun run start

Integração com Clientes MCP

Integração Baseada em Bunx (Recomendado)

Configure clientes MCP para executar o servidor via bunx:

Claude Code

Configuração em ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "nexus": {
      "command": "bunx",
      "args": ["nexus-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Reinicie o Claude Code após alterações de configuração.

Cursor

Adicione a configuração do servidor nas configurações MCP do Cursor:

• Nome: nexus
• Comando: bunx
• Argumentos: ["nexus-mcp"]
• Variáveis de Ambiente: OPENROUTER_API_KEY=your-api-key-here

Reinicie o Cursor após alterações de configuração.

Configuração Genérica de Cliente MCP

Parâmetros padrão de conexão de cliente MCP:

• Transporte: stdio
• Comando: bunx
• Argumentos: ["nexus-mcp"]
• Ambiente: OPENROUTER_API_KEY=your-api-key-here

Alternativa: npx ou Instalação Local

Se você não tiver o Bun instalado, use npx no lugar de bunx em qualquer uma das configurações acima.

Para uma instalação local (após seguir a configuração de desenvolvimento local):

{
  "mcpServers": {
    "nexus": {
      "command": "bun",
      "args": ["run", "/path/to/nexus-mcp/dist/cli.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Uso

Uma vez integrado, você pode usar a ferramenta de busca no seu cliente MCP:

Busca Básica

Use the search tool to find information about "latest developments in AI"

Busca Avançada com Parâmetros

Search for "climate change solutions" using:
- Model: sonar-pro
- Max tokens: 2000
- Temperature: 0.3

Usando Diferentes Modelos

# Fast Q&A with real-time web search (default)
Search for "latest news" with model: sonar

# Deep research with comprehensive analysis
Search for "AI safety research" with model: sonar-deep-research

# Knowledge from training data (no web search)
Search for "explain quantum computing" with model: grok-4

Ferramentas Disponíveis

search

A principal ferramenta de busca que fornece capacidades de busca com tecnologia de IA.

Parâmetros:

• query (obrigatório): Consulta de busca (1-2000 caracteres)
• model (opcional): Modelo a ser usado (padrão: sonar)
  • sonar - Perguntas e respostas rápidas com busca web em tempo real (timeout de 30s)
  • sonar-pro - Consultas de múltiplas etapas com busca web em tempo real (timeout de 60s, premium)
  • sonar-reasoning-pro - Raciocínio em cadeia de pensamento com busca web em tempo real (timeout de 120s, premium)
  • sonar-deep-research - Relatórios de pesquisa exaustivos com busca web em tempo real (timeout de 300s, premium)
  • grok-4 - Conhecimento de dados de treinamento, sem busca em tempo real (timeout de 60s, premium)
• maxTokens (opcional): Tokens máximos de resposta (1-4000, padrão: 1000)
• temperature (opcional): Aleatoriedade da resposta (0-2, padrão: 0.3)
• timeout (opcional): Substituir timeout padrão em milissegundos (5000-600000)

Exemplo de Resposta (modelo Perplexity):

Based on current information, here are the latest developments in AI...

[Detailed AI-generated response with current information]

---
**Search Metadata:**
- Model: perplexity/sonar
- Response time: 1250ms
- Tokens used: 850
- Timeout: 30000ms
- Search type: realtime
- Sources: 5 found

Exemplo de Resposta (modelo Grok 4):

Quantum computing is a type of computation that harnesses quantum mechanics...

[Response based on training data knowledge]

---
**Search Metadata:**
- Model: x-ai/grok-4
- Response time: 3500ms
- Tokens used: 650
- Timeout: 60000ms
- Search type: training-data
- Cost tier: premium

Configuração

Variáveis de Ambiente

• OPENROUTER_API_KEY (obrigatório): Sua chave de API OpenRouter
• NODE_ENV (opcional): Configuração de ambiente (development, production, test)
• LOG_LEVEL (opcional): Nível de registro (debug, info, warn, error)

Configuração Avançada

O servidor suporta configuração adicional através de variáveis de ambiente:

• OPENROUTER_TIMEOUT_MS: Timeout de requisição em milissegundos (padrão: 30000)
• OPENROUTER_MAX_RETRIES: Número máximo de tentativas de repetição (padrão: 3)
• OPENROUTER_BASE_URL: URL base personalizada da API OpenRouter

Recursos

O servidor fornece um recurso de status de configuração em config://status que mostra:

• Status de saúde do servidor
• Informações de configuração (com chave de API mascarada)
• Disponibilidade da ferramenta de busca
• Tempo de atividade e versão do servidor

Solução de Problemas

Problemas Específicos do Bunx/NPX

"bunx: comando não encontrado"

• Instale o Bun: curl -fsSL https://bun.sh/install | bash
• Ou use npx como alternativa se você tiver Node.js 18+ instalado

"npx: comando não encontrado"

• Certifique-se de que Node.js 18+ está instalado: node --version
• Atualize o npm: npm install -g npm@latest

"Não foi possível encontrar o pacote 'nexus-mcp'"

• O pacote pode ainda não ter sido publicado. Use a instalação local como alternativa
• Verifique a conectividade de rede para acesso ao registro npm

Inicialização lenta na primeira execução

• Isso é normal na primeira execução, pois o pacote é baixado
• Execuções subsequentes serão mais rápidas devido ao cache
• Para inicialização mais rápida, use a instalação local

Erros de "Permissão negada" com npx

• Tente: npx --yes nexus-mcp --stdio
• Ou defina permissões do npm: npm config set user 0 && npm config set unsafe-perm true

Problemas Comuns

"A funcionalidade de busca não está disponível"

• Certifique-se de que a variável de ambiente OPENROUTER_API_KEY está definida
• Verifique se sua chave de API é válida em OpenRouter
• Verifique os logs do servidor para erros de inicialização

"Falha na autenticação: Chave de API inválida"

• Verifique novamente o formato e a validade da sua chave de API
• Certifique-se de que a chave tem créditos/permissões suficientes
• Teste a chave diretamente no painel do OpenRouter

"Limite de taxa excedido"

• Aguarde o limite de taxa ser redefinido (geralmente 1 minuto)
• Considere atualizar seu plano OpenRouter para limites mais altos
• Monitore o uso no seu painel do OpenRouter

Timeouts de conexão

• Verifique sua conexão com a internet
• O servidor tentará automaticamente repetir requisições com falha
• Aumente o timeout se necessário: OPENROUTER_TIMEOUT_MS=60000

O cliente MCP não consegue se conectar ao servidor

• Verifique se sua configuração MCP usa o comando e os argumentos corretos
• Verifique se Bun 1.0+ ou Node.js 18+ está disponível no ambiente do seu cliente MCP
• Certifique-se de que a chave de API está definida corretamente nas variáveis de ambiente

Registro de Depuração

Ative o registro de depuração:

Para desenvolvimento local: Adicione LOG_LEVEL=debug ao seu arquivo .env

Para clientes MCP: Adicione LOG_LEVEL: "debug" à seção env da sua configuração MCP

Isso fornecerá informações detalhadas sobre:

• Carregamento de configuração
• Requisições e respostas da API
• Detalhes de erros e rastreamentos de pilha
• Métricas de desempenho

Testando a Conexão

Você pode testar se o servidor está funcionando verificando o recurso de status de configuração no seu cliente MCP, ou executando uma consulta de busca simples.

Desenvolvimento

Para desenvolvedores que trabalham neste servidor:

# Development with hot reload
bun run dev

# Run tests
bun run test

# Run tests with coverage
bun run test:coverage

# Lint code
bun run lint

# Format code
bun run format

Custos da API

O OpenRouter cobra pelo uso da API com base no consumo de tokens:

• Preços: Consulte as taxas atuais em Modelos OpenRouter
• Monitoramento: Rastreamento de uso disponível no painel do OpenRouter
• Limites: Configure limites de gastos nas configurações da conta OpenRouter
• Otimização: O servidor implementa cache de respostas e deduplicação de requisições para minimizar chamadas redundantes à API

📚 Documentação

🤝 Contribuição

Aceitamos contribuições de desenvolvedores de todos os níveis de experiência!

🚀 Comece Aqui Faça um fork do repositório Leia nosso Guia de Contribuição Confira boas primeiras issues

🐛 Reporte Problemas Relatórios de Bugs Solicitações de Recursos Faça Perguntas

💬 Junte-se à Comunidade Discussões no GitHub Código de Conduta Roadmap e Quadro do Projeto

🌟 Reconhecimento

Os contribuidores são reconhecidos em:

• Lista de contribuidores
• Notas de versão para contribuições significativas
• Destaques da comunidade e depoimentos

🔗 Projetos Relacionados

• Model Context Protocol - O padrão que implementamos
• OpenRouter - Nosso provedor de modelos de IA
• Claude Desktop - Cliente MCP principal
• Cursor - Editor de código com tecnologia de IA com suporte MCP

📞 Suporte e Comunidade

📄 Licença

Licença MIT — veja o arquivo LICENSE para detalhes.

---