NWO Robotics

Controle robôs reais e dispositivos IoT através de agentes de IA. Faça auto-registro com autenticação por carteira, pague com ETH para upgrades de nível e execute comandos Visão-Linguagem-Ação. Oferece controle de robôs, monitoramento de sensores, coordenação multi-agente e pagamentos autônomos.

GitHub

Documentação

Servidor MCP NWO Robotics v2.0

Servidor Model Context Protocol (MCP) completo para a API NWO Robotics com 77 ferramentas integradas cobrindo SLAM, aprendizado por reforço, sensores avançados e controle completo de sistemas robóticos.

📋 Visão Geral

Este servidor MCP fornece acesso abrangente a todos os endpoints da API NWO Robotics por meio de uma interface unificada com 77 ferramentas organizadas por prioridade e função.

✨ Principais Recursos

77 Ferramentas Integradas - Cobertura completa da API
SLAM e Localização - Mapeamento e navegação persistente de robôs
Aprendizado por Reforço - Treinamento RL em nuvem (PPO, SAC, DDPG, TD3)
Sensores Avançados - Térmico, MMWave, gás, acústico, magnético
Visão e Fundamentação - Detecção de objetos com vocabulário aberto
Sensação Tátil - Feedback ORCA Hand 576-taxel
Planejamento de Movimento - Integração MoveIt2 com prevenção de colisões
Planejamento de Tarefas - Execução hierárquica de tarefas com árvores de comportamento
Integração ROS2 - Ponte em nuvem para robôs reais (UR5e, Panda, Spot)
Monitoramento de Segurança - Validação de segurança em tempo real e parada de emergência
MQTT IoT - Suporte a mais de 1000 agentes com computação de borda
Agentes Autônomos - Autorregistro e pagamentos baseados em ETH

🚀 Início Rápido

1. Clonar Repositório

git clone https://github.com/RedCiprianPater/mcp-server-robotics.git
cd mcp-server-robotics

2. Instalar Dependências

npm install

3. Configurar Ambiente

cp .env.example .env
# Edit .env and add your NWO_API_KEY
nano .env

4. Compilar e Executar

npm run build
npm start

5. Testar em Ação

# The server will start and display available tools
# You can now use any of the 77 tools through Claude

📦 O que Está Incluído

Arquivos

src/index.ts - Implementação completa do servidor MCP (77 ferramentas)
package.json - Dependências e scripts de compilação
tsconfig.json - Configuração do TypeScript
Dockerfile - Implantação em contêiner
docker-compose.yml - Pilha completa com broker MQTT
.env.example - Modelo de variáveis de ambiente
INTEGRATION_GUIDE.md - Instruções detalhadas de integração
README.md - Este arquivo

Categorias de Ferramentas

Prioridade 1 - Recursos Exclusivos (5 ferramentas)

✅ nwo_initialize_slam              - Persistent robot mapping
✅ nwo_localize                     - Landmark-based localization
✅ nwo_create_rl_env                - Cloud RL training environments
✅ nwo_train_policy                 - Policy training (SB3)
✅ nwo_detect_objects_grounding     - Open-vocabulary detection

Prioridade 2 - Sensores Inovadores (5 ferramentas)

✅ nwo_query_thermal                - Heat detection
✅ nwo_query_mmwave                 - Millimeter-wave radar
✅ nwo_query_gas                    - Air quality sensors
✅ nwo_query_acoustic               - Sound localization
✅ nwo_query_magnetic               - Metal detection

Prioridade 3 - Recursos Avançados (4 ferramentas)

✅ nwo_read_tactile                 - ORCA Hand 576 taxels
✅ nwo_identify_material            - Material recognition
✅ nwo_plan_motion                  - MoveIt2 motion planning
✅ nwo_execute_behavior_tree        - Hierarchical task execution

Operações Padrão (58 ferramentas)

Inference & Models (6)              Robot Control (3)
Task Planning & Learning (4)        Agent Management (3)
Voice & Gesture (2)                 Simulation & Physics (3)
ROS2 & Hardware (3)                 MQTT & IoT (2)
Safety & Monitoring (3)             Embodiment & Calibration (3)
Autonomous Agents (4)               Dataset & Export (2)
Demo & Testing (2)

🔧 Configuração

Chave de API

Obtenha sua chave de API gratuita em https://nwo.capital/webapp/api-key.php

export NWO_API_KEY="sk_live_your_key_here"

Endpoints da API

# Standard API (full features)
NWO_API_BASE=https://nwo.capital/webapp/api-key.php

# Edge API (ultra-low latency, 200+ locations)
NWO_EDGE_API=https://nwo-robotics-api-edge.ciprianpater.workers.dev/api

# ROS2 Bridge (for physical robots)
NWO_ROS2_BRIDGE=https://nwo-ros2-bridge.onrender.com

# MQTT Broker (IoT sensors)
MQTT_BROKER=mqtt.nwo.capital
MQTT_PORT=8883

📖 Exemplos de Uso

Exemplo 1: SLAM e Navegação

// Initialize SLAM mapping
const slam = await client.messages.create({
  tools: [{name: "nwo_initialize_slam", input: {
    agent_id: "robot_001",
    map_name: "warehouse",
    slam_type: "hybrid",
    loop_closure: true
  }}]
});

// Later: Localize in the map
const localize = await client.messages.create({
  tools: [{name: "nwo_localize", input: {
    agent_id: "robot_001",
    map_id: "map_123",
    image: "base64_encoded_image"
  }}]
});

Exemplo 2: Tarefa Baseada em Visão

// Detect objects with natural language
const detect = await client.messages.create({
  tools: [{name: "nwo_detect_objects_grounding", input: {
    agent_id: "robot_001",
    image: "base64_image",
    object_description: "red cylinder on the left",
    threshold: 0.85,
    return_mask: true
  }}]
});

// Execute action based on detection
const execute = await client.messages.create({
  tools: [{name: "nwo_inference", input: {
    instruction: "Pick up the detected object",
    images: ["base64_image"]
  }}]
});

Exemplo 3: Planejamento de Tarefas Complexas

// Break down high-level instruction
const plan = await client.messages.create({
  tools: [{name: "nwo_task_planner", input: {
    instruction: "Clean the warehouse floor",
    agent_id: "robot_001",
    context: {
      location: "warehouse",
      known_objects: ["shelves", "boxes"]
    }
  }}]
});

// Execute subtasks
for (let i = 1; i <= 5; i++) {
  await client.messages.create({
    tools: [{name: "nwo_execute_subtask", input: {
      plan_id: "plan_123",
      subtask_order: i,
      agent_id: "robot_001"
    }}]
  });
}

Exemplo 4: Fusão de Sensores

const fusion = await client.messages.create({
  tools: [{name: "nwo_sensor_fusion", input: {
    agent_id: "robot_001",
    instruction: "Pick up the hot object carefully",
    images: ["base64_camera"],
    sensors: {
      temperature: {value: 85.5, unit: "celsius"},
      proximity: {distance: 0.15, unit: "meters"},
      force: {grip_pressure: 2.5},
      gps: {lat: 51.5074, lng: -0.1278}
    }
  }}]
});

Exemplo 5: Treinamento de Política RL

// Create RL environment
const env = await client.messages.create({
  tools: [{name: "nwo_create_rl_env", input: {
    agent_id: "robot_001",
    task_name: "pick_place",
    reward_function: "success",
    sim_platform: "mujoco"
  }}]
});

// Train policy
const train = await client.messages.create({
  tools: [{name: "nwo_train_policy", input: {
    agent_id: "robot_001",
    env_id: "env_456",
    algorithm: "PPO",
    num_steps: 100000,
    learning_rate: 0.0003
  }}]
});

📊 Métricas de Desempenho

Operação	Latência	Observações
Inferência Padrão	100-120ms	Datacenter na UE
Inferência de Borda	25-50ms	Mais de 200 locais globais
Inicialização SLAM	200-500ms	Depende da qualidade da imagem
Localização SLAM	100-300ms	Em mapa existente
Treinamento RL (por etapa)	50-100ms	Simulação MuJoCo
Planejamento de Tarefas	500-1000ms	Decomposição complexa
Fusão de Sensores	150-300ms	Processamento multisensor
Parada de Emergência	<10ms	Resposta garantida

🐳 Implantação Docker

Execução Simples com Docker

docker build -t mcp-nwo-robotics .
docker run -e NWO_API_KEY=sk_xxx mcp-nwo-robotics

Docker Compose (Recomendado)

# Start full stack with MQTT broker
docker-compose up -d

# View logs
docker-compose logs -f mcp-nwo-robotics

# Stop
docker-compose down

Implantação em Produção

# Build for production
docker build -t mcp-nwo-robotics:prod .

# Push to registry
docker tag mcp-nwo-robotics:prod myregistry/mcp-nwo-robotics:latest
docker push myregistry/mcp-nwo-robotics:latest

# Deploy on Kubernetes
kubectl apply -f k8s-deployment.yaml

🔐 Segurança

Gerenciamento de Chave de API

# Never commit API keys
echo "NWO_API_KEY=*" >> .gitignore
echo ".env" >> .gitignore

# Use environment variables or .env (in .gitignore)

Limitação de Taxa

Nível Gratuito: 100.000 chamadas/mês
Protótipo: 500.000 chamadas/mês (~16.666/dia)
Produção: Chamadas ilimitadas

Monitore o uso:

const balance = await client.messages.create({
  tools: [{name: "nwo_agent_check_balance", input: {
    agent_id: "agent_123"
  }}]
});

Recursos de Segurança

Detecção de colisão em tempo real
Aviso de proximidade humana (1,5m padrão)
Parada de emergência (resposta <10ms)
Aplicação de limites de força/torque
Registro de auditoria para conformidade

🧪 Testes

Executar Testes

npm test
npm run test:watch

Testar Ferramentas Individuais

# Test SLAM
npm run dev -- --test nwo_initialize_slam

# Test inference
npm run dev -- --test nwo_inference

# Test sensor fusion
npm run dev -- --test nwo_sensor_fusion

📚 Documentação

Referência da API: https://nwo.capital/webapp/nwo-robotics.html
GitHub: https://github.com/RedCiprianPater/mcp-server-robotics
Whitepaper: https://www.researchgate.net/publication/401902987_NWO_Robotics_API_WHITEPAPER
Demonstração: https://huggingface.co/spaces/PUBLICAE/nwo-robotics-api-demo
Documentação: https://nworobotics.cloud

🔗 Guias de Integração

Com a API Claude

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 4096,
  tools: tools, // All 77 NWO tools
  messages: [{
    role: "user",
    content: "Initialize SLAM mapping on robot_001"
  }]
});

Com LangChain

from langchain.chat_models import ChatAnthropic
from langchain.tools import StructuredTool

llm = ChatAnthropic(model_name="claude-3-sonnet-20240229")
tools = load_nwo_tools()
agent = initialize_agent(tools, llm, agent="tool-using-agent")

Com CrewAI

from crewai import Agent, Task, Crew
from nwo_tools import get_robotics_tools

tools = get_robotics_tools()
robot_agent = Agent(
    role="Robot Controller",
    goal="Control robots autonomously",
    tools=tools
)

🐛 Solução de Problemas

Problema: "Chave de API inválida ou ausente"

# Solution: Check API key
echo $NWO_API_KEY

# If empty, set it:
export NWO_API_KEY="sk_your_actual_key"

# Or in .env:
NWO_API_KEY=sk_your_actual_key

Problema: "Erro de API 504: Gateway Timeout"

# Solution: Use edge API for faster response
# Set: NWO_EDGE_API endpoint
# Tool: nwo_edge_inference instead of nwo_inference

Problema: "Colisão detectada"

# Solution: Validate trajectory before execution
# Use: nwo_simulate_trajectory to check collision
# Use: nwo_check_collision for detailed analysis

Problema: "Falha no mapeamento SLAM"

# Solution: Ensure good image quality
# - Well-lit environment
# - Distinct visual features
# - Slow movement during initialization
# - Try visual instead of hybrid SLAM

📈 Monitoramento e Análises

Logs

# View real-time logs
npm run dev

# With custom log level
LOG_LEVEL=debug npm start

# Save to file
npm start > logs/server.log 2>&1

Métricas

# Monitor API usage
nwo_agent_check_balance

# Export dataset for analysis
nwo_export_dataset

# Check system health
GET /health (if enabled)

🎯 Próximos Passos

✅ Configuração: npm install && npm run build
✅ Configurar: Adicione NWO_API_KEY ao .env
✅ Testar: npm start e verifique se as ferramentas carregam
✅ Integrar: Use com a API Claude ou seu framework
✅ Implantar: Docker Compose ou Kubernetes
✅ Monitorar: Verifique logs e métricas de uso
✅ Escalar: Atualize o nível conforme necessário

📞 Suporte

Problemas: https://github.com/RedCiprianPater/mcp-server-robotics/issues
Discussões: https://github.com/RedCiprianPater/mcp-server-robotics/discussions
Ajuda com Chave de API: https://nwo.capital/webapp/api-key.php
Documentação NWO: https://nwo.capital/nwo-robotics.html

📝 Histórico de Versões

v2.0.0 (Atual - Abril 2026)

✅ 77 ferramentas totais implementadas
✅ Prioridade 1: SLAM, RL, Fundamentação (5)
✅ Prioridade 2: Sensores Avançados (5)
✅ Prioridade 3: Recursos Avançados (4)
✅ Operações Padrão (58)
✅ Suporte completo ao TypeScript
✅ Pronto para Docker e Kubernetes
✅ Tratamento de erros de nível de produção
✅ Cobertura completa de testes

v1.0.0 (Anterior)

Conjunto básico de ferramentas (20 ferramentas)
Apenas inferência padrão
Configuração manual

📄 Licença

Licença MIT - Consulte o arquivo LICENSE para obter detalhes

🙏 Agradecimentos

NWO Robotics - API e infraestrutura
Anthropic - Claude e protocolo MCP
Comunidade de Código Aberto - Contribuições e feedback

Última Atualização: Abril 2026
Status: ✅ Pronto para Produção
Mantenedor: @RedCiprianPater