NWO Robotics

Servidor MCP de NWO Robotics v2.0

Servidor completo del Model Context Protocol (MCP) para la API de NWO Robotics con 77 herramientas integradas que cubren SLAM, aprendizaje por refuerzo, sensores avanzados y control completo de sistemas robóticos.

📋 Descripción general

Este servidor MCP proporciona acceso integral a todos los endpoints de la API de NWO Robotics a través de una interfaz unificada con 77 herramientas organizadas por prioridad y función.

✨ Características principales

• 77 herramientas integradas - Cobertura completa de la API
• SLAM y localización - Mapeo y navegación robótica persistente
• Aprendizaje por refuerzo - Entrenamiento RL en la nube (PPO, SAC, DDPG, TD3)
• Sensores avanzados - Térmicos, MMWave, gas, acústicos, magnéticos
• Visión y anclaje - Detección de objetos con vocabulario abierto
• Detección táctil - Retroalimentación ORCA Hand de 576 taxeles
• Planificación de movimiento - Integración con MoveIt2 y evitación de colisiones
• Planificación de tareas - Ejecución jerárquica de tareas con árboles de comportamiento
• Integración ROS2 - Puente en la nube para robots reales (UR5e, Panda, Spot)
• Monitoreo de seguridad - Validación de seguridad en tiempo real y parada de emergencia
• MQTT IoT - Soporte para más de 1000 agentes con computación en el borde
• Agentes autónomos - Autorregistro y pagos basados en ETH

🚀 Inicio rápido

1. Clonar el repositorio

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

2. Instalar dependencias

npm install

3. Configurar el entorno

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

4. Compilar y ejecutar

npm run build
npm start

5. Probar en acción

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

📦 Qué se incluye

Archivos

• src/index.ts - Implementación completa del servidor MCP (77 herramientas)
• package.json - Dependencias y scripts de compilación
• tsconfig.json - Configuración de TypeScript
• Dockerfile - Despliegue en contenedores
• docker-compose.yml - Pila completa con broker MQTT
• .env.example - Plantilla de variables de entorno
• INTEGRATION_GUIDE.md - Instrucciones detalladas de integración
• README.md - Este archivo

Categorías de herramientas

Prioridad 1 - Características únicas (5 herramientas)

✅ 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

Prioridad 2 - Sensores novedosos (5 herramientas)

✅ 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

Prioridad 3 - Características avanzadas (4 herramientas)

✅ 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

Operaciones estándar (58 herramientas)

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)

🔧 Configuración

Clave de API

Obtén tu clave de API gratuita en https://nwo.capital/webapp/api-key.php

export NWO_API_KEY="sk_live_your_key_here"

Endpoints de la 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

📖 Ejemplos de uso

Ejemplo 1: SLAM y navegación

// 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"
  }}]
});

Ejemplo 2: Tarea basada en visión

// 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"]
  }}]
});

Ejemplo 3: Planificación de tareas complejas

// 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"
    }}]
  });
}

Ejemplo 4: Fusión 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}
    }
  }}]
});

Ejemplo 5: Entrenamiento de políticas 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 rendimiento

Operación	Latencia	Notas
Inferencia estándar	100-120 ms	Centro de datos en la UE
Inferencia en el borde	25-50 ms	Más de 200 ubicaciones globales
Inicialización SLAM	200-500 ms	Depende de la calidad de la imagen
Localización SLAM	100-300 ms	En mapa existente
Entrenamiento RL (por paso)	50-100 ms	Simulación MuJoCo
Planificación de tareas	500-1000 ms	Descomposición compleja
Fusión de sensores	150-300 ms	Procesamiento multisensor
Parada de emergencia	<10 ms	Respuesta garantizada

🐳 Despliegue con Docker

Ejecución simple con 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

Despliegue en producción

# 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

🔐 Seguridad

Gestión de claves de API

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

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

Límites de velocidad

• Nivel gratuito: 100 000 llamadas/mes
• Prototipo: 500 000 llamadas/mes (~16 666/día)
• Producción: Llamadas ilimitadas

Supervisa el uso:

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

Características de seguridad

• Detección de colisiones en tiempo real
• Advertencia de proximidad humana (1,5 m por defecto)
• Parada de emergencia (respuesta <10 ms)
• Aplicación de límites de fuerza/par
• Registro de auditoría para cumplimiento

🧪 Pruebas

Ejecutar pruebas

npm test
npm run test:watch

Probar herramientas individuales

# 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

📚 Documentación

• Referencia de la API: https://nwo.capital/webapp/nwo-robotics.html
• GitHub: https://github.com/RedCiprianPater/mcp-server-robotics
• Documento técnico: https://www.researchgate.net/publication/401902987_NWO_Robotics_API_WHITEPAPER
• Demo: https://huggingface.co/spaces/PUBLICAE/nwo-robotics-api-demo
• Documentación: https://nworobotics.cloud

🔗 Guías de integración

Con la API de 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"
  }]
});

Con 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")

Con 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
)

🐛 Solución de problemas

Problema: "Clave de API no válida o faltante"

# 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: "Error de API 504: Tiempo de espera de puerta de enlace agotado"

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

Problema: "Colisión detectada"

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

Problema: "El mapeo SLAM falló"

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

📈 Monitoreo y análisis

Registros

# 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 pasos

1. ✅ Configuración: npm install && npm run build
2. ✅ Configurar: Agrega NWO_API_KEY a .env
3. ✅ Probar: npm start y verifica que las herramientas se carguen
4. ✅ Integrar: Úsalo con la API de Claude o tu framework
5. ✅ Desplegar: Docker Compose o Kubernetes
6. ✅ Monitorear: Revisa registros y métricas de uso
7. ✅ Escalar: Mejora el nivel según sea necesario

📞 Soporte

• Problemas: https://github.com/RedCiprianPater/mcp-server-robotics/issues
• Discusiones: https://github.com/RedCiprianPater/mcp-server-robotics/discussions
• Ayuda con la clave de API: https://nwo.capital/webapp/api-key.php
• Documentación de NWO: https://nwo.capital/nwo-robotics.html

📝 Historial de versiones

v2.0.0 (Actual - abril de 2026)

• ✅ 77 herramientas implementadas en total
• ✅ Prioridad 1: SLAM, RL, anclaje (5)
• ✅ Prioridad 2: Sensores avanzados (5)
• ✅ Prioridad 3: Características avanzadas (4)
• ✅ Operaciones estándar (58)
• ✅ Soporte completo de TypeScript
• ✅ Listo para Docker y Kubernetes
• ✅ Manejo de errores de nivel producción
• ✅ Cobertura completa de pruebas

v1.0.0 (Anterior)

• Conjunto básico de herramientas (20 herramientas)
• Solo inferencia estándar
• Configuración manual

📄 Licencia

Licencia MIT - Consulta el archivo LICENSE para más detalles

🙏 Agradecimientos

• NWO Robotics - API e infraestructura
• Anthropic - Claude y protocolo MCP
• Comunidad de código abierto - Contribuciones y comentarios

---

Última actualización: abril de 2026
Estado: ✅ Listo para producción
Mantenedor: @RedCiprianPater

⭐ Si te resulta útil, ¡dale una estrella al repositorio!

---

🔗 Proyectos relacionados

• API de NWO Robotics
• Xiaomi Robotics 0
• Protocolo MCP
• Anthropic Claude