Helios-9

Fornece contexto abrangente de gerenciamento de projetos para agentes de IA usando a API Helios-9.

Documentação

Servidor MCP Helios-9

Um servidor Model Context Protocol (MCP) nativo para IA que fornece contexto abrangente de gerenciamento de projetos para agentes de IA. Construído para integração perfeita com Claude, OpenAI e outros sistemas de IA por meio da API Helios-9.

📌 Status Atual

Estabilidade: Pronto para Recursos Principais
Ferramentas Ativas: 21 (Projetos, Iniciativas, Tarefas, Documentos - suporte completo a hierarquia)
Integração com API: ✅ Totalmente integrado com a API SaaS Helios-9

🌟 Recursos

Recursos Principais

Gerenciamento de Projetos: Crie, leia e atualize projetos com contexto completo
Operações de Tarefas: Quadros Kanban, criação de tarefas, acompanhamento de status
Gerenciamento de Documentos: Documentos Markdown com metadados frontmatter
Integração com IA: Metadados estruturados para colaboração ideal com IA
Contexto em Tempo Real: Estatísticas de projetos ao vivo e feeds de atividade

Suporte ao Protocolo MCP

Ferramentas: 21 ferramentas para projetos, iniciativas, tarefas e documentos
Recursos: Recursos dinâmicos de projetos e documentos
Prompts: 9 modelos de prompt otimizados para IA para fluxos de trabalho de projetos

Design Focado em IA

Suporte a Frontmatter: Metadados YAML para instruções de IA
Análise de Links: Vinculação interna de documentos com sintaxe [[document-name]]
Busca Básica: Busca por palavras-chave em projetos, tarefas e documentos
Busca Semântica: Em breve com integração Supabase pgvector

🚀 Início Rápido

Pré-requisitos

Node.js 16+
Acesso ao aplicativo principal Helios-9 com geração de chave de API
Cliente de IA compatível com MCP (Claude Desktop, OpenAI, etc.)

Opções de Instalação

Opção 1: Executar diretamente com npx (Recomendado)

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

Opção 2: Clonar e compilar localmente

Instalar dependências:
```
npm install
```

Configurar ambiente:

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

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

Variáveis de Ambiente

# 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

🔑 Geração de Chave de API

No Aplicativo Principal Helios-9

Faça login no seu aplicativo Helios-9
Navegue até Configurações > Chaves de API
Clique em "Gerar Nova Chave de API"
Copie a chave gerada (ela será exibida apenas uma vez)
Defina as permissões da chave (acesso de leitura/gravação a projetos, tarefas, documentos)
Adicione a chave ao ambiente do seu servidor MCP

Permissões da Chave de API

Sua chave de API controla o acesso a:

Projetos: Criar, ler, atualizar e excluir projetos
Tarefas: Gerenciar tarefas dentro dos seus projetos
Documentos: Criar e gerenciar documentação de projetos
Análises: Acessar insights e métricas de projetos

📋 Ferramentas Disponíveis

✅ Ferramentas de Projetos

list_projects - Listar todos os projetos com filtros
get_project - Obter informações detalhadas do projeto
create_project - Criar novo projeto
update_project - Atualizar projeto existente

✅ Ferramentas de Tarefas

list_tasks - Listar tarefas com filtros
get_task - Obter detalhes de uma tarefa específica
create_task - Criar nova tarefa
update_task - Atualizar status/detalhes da tarefa

✅ Ferramentas de Documentos

list_documents - Listar documentos com filtros
get_document - Obter documento específico
create_document - Criar documento markdown (requer project_id)
update_document - Atualizar conteúdo do documento

Nota: Todas as ferramentas exigem autenticação adequada com chave de API e respeitam o isolamento de dados em nível de usuário.

🚧 Em Breve

Busca semântica em todo o conteúdo
Dependências de tarefas e fluxos de trabalho
Rastreamento de conversas de IA
Análises avançadas e insights
Recursos de colaboração em documentos

🔗 Recursos e Prompts

Recursos Disponíveis (24 no total)

Projetos: /projects, /project/{id}/context, /project/{id}/health, /project/{id}/timeline
Iniciativas: /initiatives, /initiatives?project_id={id}, /initiative/{id}, /initiative/{id}/context
Tarefas: /tasks, /tasks?project_id={id}, /tasks?initiative_id={id}, /task/{id}
Documentos: /documents, /documents?project_id={id}, /document/{id}
Espaço de Trabalho: /workspace/overview, /workspace/analytics
Busca: /search?q={query}, /search/semantic?q={query}
Conversas: /conversations?project_id={id}, /conversation/{id}
Fluxos de Trabalho: /workflows, /workflow/{id}

Prompts Disponíveis

Planejamento e Estratégia:

project_planning - Gerar planos completos de projetos com iniciativas
initiative_strategy - Planejamento estratégico para iniciativas
task_breakdown - Dividir recursos em tarefas acionáveis
sprint_planning - Planejar sprints com contexto atual

Análise e Revisão:

project_health_check - Analisar a saúde do projeto
document_review - Revisar e melhorar a documentação
daily_standup - Gerar relatórios de standup
project_kickoff - Estruturação inicial do projeto

Recursos Especiais:

helios9_personality - Insights de IA sarcásticos do HELIOS-9

🔧 Exemplos de Integração

Configuração do Claude Desktop

Adicione ao seu claude_desktop_config.json:

Opção 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"
      }
    }
  }
}

Opção 2: Usando instalação 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"
      }
    }
  }
}

Integração com 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"
      }
    }
  }
}

Integração com 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 Dados

Projeto

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

Tarefa

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
}

🔒 Segurança

Autenticação

Autenticação com Chave de API: Gerada a partir do seu aplicativo Helios-9
Armazenamento Seguro: As chaves de API são armazenadas e gerenciadas com segurança no Helios-9
Contexto do Usuário: Todas as operações são realizadas no contexto do proprietário da chave de API

Acesso a Dados

Isolamento de Usuário: A API aplica controles de acesso a dados em nível de usuário
Baseado em Permissões: As chaves de API podem ter permissões granulares
Registro de Auditoria: Todas as chamadas de API são registradas para segurança e depuração

Limitação de Taxa

Nível de API: A limitação de taxa é aplicada pela API Helios-9
Limites por Chave: Limites diferentes podem ser definidos por chave de API
Configurável: Os limites podem ser ajustados no painel administrativo do Helios-9

🏗️ Arquitetura

Design API-First

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

Benefícios da Integração com API

Autenticação Centralizada: Autenticação gerenciada pelo aplicativo principal
Dados Consistentes: Fonte única de verdade para todos os dados
Segurança: Controles de segurança e monitoramento em nível de API
Escalabilidade: Pode atender a vários clientes MCP
Facilidade de Manutenção: Base de código única para operações de dados

📈 Monitoramento

Verificações de Saúde

O servidor fornece informações de saúde por meio de registros:

Status da conexão com a API
Estado da autenticação
Métricas de execução de ferramentas
Taxas e tipos de erros

Métricas Disponíveis

Frequência de chamadas de ferramentas
Tempos de resposta
Sucesso/falha de autenticação
Padrões de uso de endpoints da API

🛠️ Solução de Problemas

Problemas Comuns

Falha na Autenticação

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

Problemas de Conexão

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

Erros de Permissão

Verifique as permissões da chave de API no painel administrativo do Helios-9
Garanta que a chave tenha acesso aos recursos necessários (projetos, tarefas, documentos)

Análise de Registros

# Enable debug logging
LOG_LEVEL=debug npm start

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

🤝 Contribuindo

Configuração de Desenvolvimento

Faça um fork do repositório
Crie uma branch de recurso
Faça alterações com testes
Envie um pull request

Estilo de Código

Modo estrito do TypeScript
Configuração do ESLint
Formatação Prettier
Commits convencionais

📝 Licença

Este projeto faz parte da plataforma Helios-9. Consulte a LICENÇA do projeto principal para obter detalhes.

🆘 Suporte

Documentação

Especificação do Protocolo MCP

Comunidade

GitHub Issues para bugs e recursos
Discussions para perguntas e ideias
Discord para chat em tempo real

📦 Publicação no npm

Para Mantenedores

Faça login no npm:
```
npm login
# Enter your npm credentials
```

Verifique o pacote antes de publicar:

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

# Check package size
npm pack --dry-run

Publique no npm:

# For initial publish or updates
npm publish

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

Verifique a publicação:

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

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

Gerenciamento de Versão

Atualize a versão 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

Construído com ❤️ para o futuro nativo em IA do gerenciamento de projetos

🚀 Roteiro

Em Breve

Busca Semântica: Busca com tecnologia de IA usando embeddings OpenAI e Supabase pgvector
Dependências de Tarefas: Vincular tarefas relacionadas e acompanhar fluxos de trabalho
Conversas de IA: Salvar e analisar interações de agentes de IA
Análises Avançadas: Insights de projetos e métricas de produtividade
Operações em Lote: Atualizar vários itens de uma vez
Automação de Fluxos de Trabalho: Criação e atualização de tarefas baseadas em gatilhos

Visão Futura

Suporte a colaboração multiagente
Framework de criação de ferramentas personalizadas
Integração com ferramentas populares de gerenciamento de projetos
Recursos de colaboração em tempo real