Helios-9

Proporciona contexto integral de gestión de proyectos a agentes de IA utilizando la API de Helios-9.

Documentación

Helios-9 MCP Server

Un servidor Model Context Protocol (MCP) nativo para IA que proporciona contexto integral de gestión de proyectos a agentes de IA. Construido para una integración perfecta con Claude, OpenAI y otros sistemas de IA mediante la API de Helios-9.

📌 Estado Actual

Estabilidad: Listo para funciones principales
Herramientas activas: 21 (Proyectos, Iniciativas, Tareas, Documentos: soporte completo de jerarquía)
Integración de API: ✅ Totalmente integrado con la API SaaS de Helios-9

🌟 Características

Capacidades principales

Gestión de proyectos: Crear, leer y actualizar proyectos con contexto completo
Operaciones de tareas: Tableros Kanban, creación de tareas, seguimiento de estado
Gestión de documentos: Documentos Markdown con metadatos frontmatter
Integración con IA: Metadatos estructurados para una colaboración óptima con IA
Contexto en tiempo real: Estadísticas de proyectos en vivo y fuentes de actividad

Soporte del protocolo MCP

Herramientas: 21 herramientas para proyectos, iniciativas, tareas y documentos
Recursos: Recursos dinámicos de proyectos y documentos
Prompts: 9 plantillas de prompts optimizadas para IA para flujos de trabajo de proyectos

Diseño centrado en IA

Soporte de frontmatter: Metadatos YAML para instrucciones de IA
Análisis de enlaces: Enlaces internos de documentos con sintaxis [[document-name]]
Búsqueda básica: Búsqueda por palabras clave en proyectos, tareas y documentos
Búsqueda semántica: Próximamente con integración de Supabase pgvector

🚀 Inicio rápido

Requisitos previos

Node.js 16+
Acceso a la aplicación principal de Helios-9 con generación de claves API
Cliente de IA compatible con MCP (Claude Desktop, OpenAI, etc.)

Opciones de instalación

Opción 1: Ejecutar directamente con npx (Recomendado)

npx -y helios9-mcp-server@latest --api-key YOUR_HELIOS9_API_KEY

Opción 2: Clonar y compilar localmente

Instalar dependencias:
```
npm install
```

Configurar el entorno:

cp .env.example .env
# Edit .env with your Helios-9 API configuration

Compilar el servidor:
```
npm run build
```
Iniciar el servidor:
```
npm start
```

Variables de entorno

# Required - Helios-9 API Configuration
HELIOS_API_URL=https://www.helios9.app
HELIOS_API_KEY=your_generated_api_key

# Optional
LOG_LEVEL=info
NODE_ENV=development

🔑 Generación de claves API

Desde la aplicación principal de Helios-9

Inicie sesión en su aplicación Helios-9
Navegue a Configuración > Claves API
Haga clic en "Generar nueva clave API"
Copie la clave generada (solo se mostrará una vez)
Configure los permisos de la clave (acceso de lectura/escritura a proyectos, tareas y documentos)
Agregue la clave al entorno de su servidor MCP

Permisos de claves API

Su clave API controla el acceso a:

Proyectos: Crear, leer, actualizar y eliminar proyectos
Tareas: Gestionar tareas dentro de sus proyectos
Documentos: Crear y gestionar documentación de proyectos
Analíticas: Acceder a información y métricas de proyectos

📋 Herramientas disponibles

✅ Herramientas de proyectos

list_projects - Listar todos los proyectos con filtrado
get_project - Obtener información detallada del proyecto
create_project - Crear nuevo proyecto
update_project - Actualizar proyecto existente

✅ Herramientas de tareas

list_tasks - Listar tareas con filtrado
get_task - Obtener detalles de una tarea específica
create_task - Crear nueva tarea
update_task - Actualizar estado/detalles de la tarea

✅ Herramientas de documentos

list_documents - Listar documentos con filtrado
get_document - Obtener documento específico
create_document - Crear documento markdown (requiere project_id)
update_document - Actualizar contenido del documento

Nota: Todas las herramientas requieren autenticación adecuada con clave API y respetan el aislamiento de datos a nivel de usuario.

🚧 Próximamente

Búsqueda semántica en todo el contenido
Dependencias de tareas y flujos de trabajo
Seguimiento de conversaciones de IA
Analíticas e información avanzada
Funciones de colaboración en documentos

🔗 Recursos y prompts

Recursos disponibles (24 en total)

Proyectos: /projects, /project/{id}/context, /project/{id}/health, /project/{id}/timeline
Iniciativas: /initiatives, /initiatives?project_id={id}, /initiative/{id}, /initiative/{id}/context
Tareas: /tasks, /tasks?project_id={id}, /tasks?initiative_id={id}, /task/{id}
Documentos: /documents, /documents?project_id={id}, /document/{id}
Espacio de trabajo: /workspace/overview, /workspace/analytics
Búsqueda: /search?q={query}, /search/semantic?q={query}
Conversaciones: /conversations?project_id={id}, /conversation/{id}
Flujos de trabajo: /workflows, /workflow/{id}

Prompts disponibles

Planificación y estrategia:

project_planning - Generar planes de proyecto completos con iniciativas
initiative_strategy - Planificación estratégica para iniciativas
task_breakdown - Dividir funciones en tareas accionables
sprint_planning - Planificar sprints con contexto actual

Análisis y revisión:

project_health_check - Analizar la salud del proyecto
document_review - Revisar y mejorar la documentación
daily_standup - Generar informes de standup
project_kickoff - Estructuración inicial del proyecto

Funciones especiales:

helios9_personality - Información de IA sardónica de HELIOS-9

🔧 Ejemplos de integración

Configuración de Claude Desktop

Agregue a su claude_desktop_config.json:

Opción 1: Usando npx (Recomendado)

{
  "mcpServers": {
    "helios9": {
      "command": "npx",
      "args": ["-y", "helios9-mcp-server@latest"],
      "env": {
        "HELIOS_API_URL": "https://helios9.app",
        "HELIOS_API_KEY": "your_generated_api_key"
      }
    }
  }
}

Opción 2: Usando instalación local

{
  "mcpServers": {
    "helios9": {
      "command": "node",
      "args": ["/path/to/helios9-MCP-Server/dist/index.js"],
      "env": {
        "HELIOS_API_URL": "https://helios9.app",
        "HELIOS_API_KEY": "your_generated_api_key"
      }
    }
  }
}

Integración con Cline/Continue

{
  "mcpServers": {
    "helios9": {
      "command": "node",
      "args": ["/path/to/helios9-MCP-Server/dist/index.js"],
      "env": {
        "HELIOS_API_URL": "https://www.helios9.app", 
        "HELIOS_API_KEY": "your_generated_api_key"
      }
    }
  }
}

Integración con OpenAI

from mcp import MCPClient
import os

# Set environment variables
os.environ["HELIOS_API_URL"] = "https://www.helios9.app"
os.environ["HELIOS_API_KEY"] = "your_generated_api_key"

client = MCPClient()
client.connect_stdio("node", ["/path/to/dist/index.js"])

# List projects
projects = client.call_tool("list_projects", {})

# Create task
task = client.call_tool("create_task", {
    "project_id": "uuid",
    "title": "Implement user authentication",
    "priority": "high"
})

📊 Modelos de datos

Proyecto

interface Project {
  id: string
  user_id: string
  name: string
  description?: string
  status: 'active' | 'completed' | 'archived'
  created_at: string
  updated_at: string
}

Tarea

interface Task {
  id: string
  title: string
  description?: string
  status: 'todo' | 'in_progress' | 'done'
  priority: 'low' | 'medium' | 'high'
  project_id: string
  assignee_id?: string
  due_date?: string
  created_at: string
  updated_at: string
  created_by: string
}

Documento

interface Document {
  id: string
  title: string
  content: string  // Markdown with frontmatter
  document_type: 'requirement' | 'design' | 'technical' | 'meeting_notes' | 'note' | 'other'
  project_id: string  // Required
  created_at: string
  updated_at: string
  created_by: string
}

🔒 Seguridad

Autenticación

Autenticación con clave API: Generada desde su aplicación Helios-9
Almacenamiento seguro: Las claves API se almacenan y gestionan de forma segura en Helios-9
Contexto de usuario: Todas las operaciones se realizan en el contexto del propietario de la clave API

Acceso a datos

Aislamiento de usuario: La API aplica controles de acceso a datos a nivel de usuario
Basado en permisos: Las claves API pueden tener permisos granulares
Registro de auditoría: Todas las llamadas a la API se registran por seguridad y depuración

Límite de velocidad

A nivel de API: El límite de velocidad lo aplica la API de Helios-9
Límites por clave: Se pueden establecer diferentes límites por clave API
Configurable: Los límites se pueden ajustar en el panel de administración de Helios-9

🏗️ Arquitectura

Diseño API-first

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Client     │────│  Helios-9 MCP    │────│  Helios-9 API   │
│  (Claude, etc.) │    │     Server       │    │   Application   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                               │                          │
                       ┌───────▼──────────┐              │
                       │  Authentication  │              │
                       │   (API Key)      │              │
                       └──────────────────┘              │
                                                         │
                                                ┌────────▼────────┐
                                                │    Database     │
                                                └─────────────────┘

Beneficios de la integración de API

Autenticación centralizada: La autenticación la gestiona la aplicación principal
Datos consistentes: Fuente única de verdad para todos los datos
Seguridad: Controles de seguridad y monitoreo a nivel de API
Escalabilidad: Puede atender a múltiples clientes MCP
Mantenibilidad: Código base único para operaciones de datos

📈 Monitoreo

Comprobaciones de salud

El servidor proporciona información de salud mediante registros:

Estado de conexión a la API
Estado de autenticación
Métricas de ejecución de herramientas
Tasas y tipos de errores

Métricas disponibles

Frecuencia de llamadas a herramientas
Tiempos de respuesta
Éxito/fallo de autenticación
Patrones de uso de endpoints de API

🛠️ Solución de problemas

Problemas comunes

Error de autenticación

# Check API key validity
curl -H "Authorization: Bearer YOUR_API_KEY" https://www.helios9.app/api/auth/validate

Problemas de conexión

# Verify API URL is accessible
curl https://www.helios9.app/api/health

Errores de permisos

Verifique los permisos de la clave API en el panel de administración de Helios-9
Asegúrese de que la clave tenga acceso a los recursos requeridos (proyectos, tareas, documentos)

Análisis de registros

# Enable debug logging
LOG_LEVEL=debug npm start

# Look for API-specific errors
grep "API Error" logs/*.log

🤝 Contribuciones

Configuración de desarrollo

Haga un fork del repositorio
Cree una rama de funciones
Realice cambios con pruebas
Envíe una solicitud de extracción (pull request)

Estilo de código

Modo estricto de TypeScript
Configuración de ESLint
Formato Prettier
Commits convencionales

📝 Licencia

Este proyecto forma parte de la plataforma Helios-9. Consulte la LICENCIA del proyecto principal para obtener más detalles.

🆘 Soporte

Documentación

Especificación del protocolo MCP

Comunidad

GitHub Issues para errores y funciones
Discussions para preguntas e ideas
Discord para chat en tiempo real

📦 Publicación en npm

Para mantenedores

Inicie sesión en npm:
```
npm login
# Enter your npm credentials
```

Verifique el paquete antes de publicar:

# Dry run to see what will be published
npm publish --dry-run

# Check package size
npm pack --dry-run

Publique en npm:

# For initial publish or updates
npm publish

# For beta/alpha releases
npm publish --tag beta

Verifique la publicación:

# Check if package is available
npm view helios9-mcp-server

# Test installation
npx -y helios9-mcp-server@latest --help

Gestión de versiones

Actualice la versión antes de publicar:

# Patch release (1.0.0 -> 1.0.1)
npm version patch

# Minor release (1.0.0 -> 1.1.0)
npm version minor

# Major release (1.0.0 -> 2.0.0)
npm version major

Construido con ❤️ para el futuro nativo de IA de la gestión de proyectos

🚀 Hoja de ruta

Próximamente

Búsqueda semántica: Búsqueda impulsada por IA usando embeddings de OpenAI y Supabase pgvector
Dependencias de tareas: Vincular tareas relacionadas y rastrear flujos de trabajo
Conversaciones de IA: Guardar y analizar interacciones de agentes de IA
Analíticas avanzadas: Información de proyectos y métricas de productividad
Operaciones masivas: Actualizar múltiples elementos a la vez
Automatización de flujos de trabajo: Creación y actualización de tareas basada en disparadores

Visión futura

Soporte de colaboración multiagente
Marco de creación de herramientas personalizadas
Integración con herramientas populares de gestión de proyectos
Funciones de colaboración en tiempo real