JSTEC RAG MCP Server

Um servidor MCP (Model Context Protocol) que integra o sistema JSTEC RAG com agentes de IA como Claude Code e Junie.

⚡ Instalação Rápida

# Instalação global via NPM
npm install -g jstec-mcp-server

# Verificar instalação
jstec-mcp-server --version

# Configurar Claude Desktop
jstec-mcp-server config

# Testar conexão com servidor RAG
jstec-mcp-server health

# Iniciar servidor MCP
jstec-mcp-server start

🚀 Funcionalidades

Ferramentas (Tools)

• rag_query: Busca semântica por documentos
• rag_context: Constrói contexto otimizado para prompts de IA
• rag_ingest_file: Ingere arquivos no sistema RAG
• rag_ingest_text: Ingere texto diretamente
• rag_create_application: Cria novas aplicações
• rag_list_applications: Lista aplicações com estatísticas
• rag_health: Verifica status do sistema

Recursos (Resources)

• applications: Lista JSON de todas as aplicações
• health-status: Status de saúde do sistema RAG

Prompts

• rag-context-prompt: Prompt otimizado para usar contexto RAG

📦 Instalação Detalhada

Opção 1: Instalação Global (Recomendada)

npm install -g jstec-mcp-server

Opção 2: Instalação Local

# Para desenvolvimento ou uso específico
npm install jstec-mcp-server
# Linux/macOS
npx jstec-mcp-server start
# Windows (evite npx):
# use o binário instalado ou o Node diretamente
jstec-mcp-server start
# ou
node ./node_modules/jstec-mcp-server/cli.cjs start

Opção 3: Desenvolvimento

git clone https://github.com/JS-Nascimento/jstec-mcp-server.git
cd jstec-mcp-server
npm install
npm run dev

🔧 Configuração

1. Configurar Servidor RAG

# Definir URL do servidor RAG (padrão: http://localhost:8000)
export RAG_BASE_URL=http://your-rag-server:8000

# Ou passar como parâmetro
jstec-mcp-server start --rag-url http://your-rag-server:8000

2. Testar Conexão

jstec-mcp-server health --rag-url http://localhost:8000

🔌 Integração com Claude Code

Para integrar este servidor MCP com Claude Code, adicione a seguinte configuração ao arquivo de configuração do Claude Desktop:

Windows

Arquivo: %APPDATA%/Claude/claude_desktop_config.json

macOS

Arquivo: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux

Arquivo: ~/.config/Claude/claude_desktop_config.json

Configuração Automática (Recomendada)

# Gerar configuração automaticamente (Claude Desktop e Junie)
jstec-mcp-server config

# Se você usa Junie e o pacote está instalado globalmente via npm:
# (usa o binário jstec-mcp-server)
jstec-mcp-server config --junie --use-bin

# Alternativa mais robusta no Windows (não depende do PATH do npm):
# (usa o executável do Node + caminho absoluto do cli.cjs)
jstec-mcp-server config --junie

Configuração Manual

{
  "mcpServers": {
    "jstec-rag": {
      "command": "jstec-mcp-server",
      "args": ["start"],
      "env": {
        "RAG_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

Para Instalação Local

{
  "mcpServers": {
    "jstec-rag": {
      "command": "npx",
      "args": ["jstec-mcp-server", "start"],
      "env": {
        "RAG_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

📚 Comandos Disponíveis

CLI Commands

# Iniciar servidor MCP
jstec-mcp-server start [--rag-url URL]

# Verificar configuração
jstec-mcp-server config

# Testar conexão
jstec-mcp-server health [--rag-url URL]

# Ajuda
jstec-mcp-server help

# Versão
jstec-mcp-server --version

Exemplos de Uso no Claude

1. Busca Semântica

Use a ferramenta rag_query para buscar "como implementar autenticação" na aplicação "user-service"

2. Construir Contexto

Use a ferramenta rag_context para construir contexto sobre "API de pagamentos" com máximo de 3000 tokens

3. Ingerir Arquivo

Use rag_ingest_file para adicionar o arquivo "/path/to/README.md" na aplicação "docs-service"

4. Listar Aplicações

Use rag_list_applications para ver todas as aplicações disponíveis

🔧 Desenvolvimento

Estrutura do Projeto

mcp-server/
├── src/
│   ├── index.ts          # Servidor MCP principal
│   ├── rag-client.ts     # Cliente HTTP para API RAG
│   └── types.ts          # Tipos e schemas
├── package.json
├── tsconfig.json
└── README.md

Scripts Disponíveis

• npm run build: Compila TypeScript para JavaScript
• npm run dev: Executa em modo desenvolvimento com watch
• npm start: Executa versão compilada
• npm run clean: Remove arquivos compilados

🌐 API RAG Suportada

Este MCP server integra com as seguintes APIs do sistema JSTEC RAG:

• POST /query - Busca semântica
• POST /context - Construção de contexto
• POST /ingest/file - Ingestão de arquivo
• POST /ingest/text - Ingestão de texto
• POST /applications - Criação de aplicação
• GET /applications - Listagem de aplicações
• GET /health - Status do sistema

📝 Licença

MIT License

Desenvolvido para integração com Claude Code, Junie e outros agentes de IA compatíveis com MCP.

❗ Importante: stdout em MCP/stdio

Em conexões MCP por stdio, o stdout deve ser usado exclusivamente pelo protocolo JSON‑RPC. Qualquer saída fora do protocolo no stdout corrompe o stream e provoca falhas como EPIPE/broken pipe no servidor e cancelamentos no cliente (ex.: Junie/Claude).

Para evitar isso, este pacote agora:

• Não escreve no stdout ao iniciar com start (logs vão para stderr por padrão).
• Oferece a flag --allow-stdout para habilitar logs no stdout quando você estiver fora do modo MCP/stdio. Exemplo:
  • jstec-mcp-server start --allow-stdout
• O processo do servidor respeita a variável de ambiente LOG_STDOUT ('1'/'true' habilitam logs no stdout).

Recomendação: ao integrar com Junie/Claude (stdio), não habilite logs no stdout. Use stderr ou um arquivo de log.