Skip to main content
Glama
jakedx6

Helios-9 MCP Server

by jakedx6
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Helios-9 MCP Server

An AI-native Model Context Protocol (MCP) server that provides comprehensive project management context to AI agents. Built for seamless integration with Claude, OpenAI, and other AI systems via the Helios-9 API.

📌 Current Status

Stability: Ready for Core Features
Active Tools: 21 (Projects, Initiatives, Tasks, Documents - full hierarchy support)
API Integration: ✅ Fully integrated with Helios-9 SaaS API

🌟 Features

Core Capabilities

  • Project Management: Create, read, update projects with full context

  • Task Operations: Kanban boards, task creation, status tracking

  • Document Management: Markdown documents with frontmatter metadata

  • AI Integration: Structured metadata for optimal AI collaboration

  • Real-time Context: Live project statistics and activity feeds

MCP Protocol Support

  • Tools: 21 tools for projects, initiatives, tasks, and documents

  • Resources: Dynamic project and document resources

  • Prompts: 9 AI-optimized prompt templates for project workflows

AI-First Design

  • Frontmatter Support: YAML metadata for AI instructions

  • Link Analysis: Internal document linking with [[document-name]] syntax

  • Basic Search: Keyword search across projects, tasks, and documents

  • Semantic Search: Coming soon with Supabase pgvector integration

🚀 Quick Start

Prerequisites

  • Node.js 16+

  • Access to Helios-9 main application with API key generation

  • MCP-compatible AI client (Claude Desktop, OpenAI, etc.)

Installation Options

Option 1: Run directly with npx (Recommended)

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

Option 2: Clone and build locally

  1. Install dependencies:

    npm install

  2. Configure environment:

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

  3. Build the server:

    npm run build

  4. Start the server:

    npm start

Environment Variables

# 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

🔑 API Key Generation

From Helios-9 Main Application

  1. Login to your Helios-9 application

  2. Navigate to Settings > API Keys

  3. Click "Generate New API Key"

  4. Copy the generated key (it will only be shown once)

  5. Set permissions for the key (read/write access to projects, tasks, documents)

  6. Add the key to your MCP server environment

API Key Permissions

Your API key controls access to:

  • Projects: Create, read, update, delete projects

  • Tasks: Manage tasks within your projects

  • Documents: Create and manage project documentation

  • Analytics: Access project insights and metrics

📋 Available Tools

✅ Project Tools

  • list_projects - List all projects with filtering

  • get_project - Get detailed project information

  • create_project - Create new project

  • update_project - Update existing project

✅ Task Tools

  • list_tasks - List tasks with filtering

  • get_task - Get specific task details

  • create_task - Create new task

  • update_task - Update task status/details

✅ Document Tools

  • list_documents - List documents with filtering

  • get_document - Get specific document

  • create_document - Create markdown document (requires project_id)

  • update_document - Update document content

Note: All tools require proper API key authentication and respect user-level data isolation.

🚧 Coming Soon

  • Semantic search across all content

  • Task dependencies and workflows

  • AI conversation tracking

  • Advanced analytics and insights

  • Document collaboration features

🔗 Resources & Prompts

Available Resources (24 total)

Projects: /projects, /project/{id}/context, /project/{id}/health, /project/{id}/timeline
Initiatives: /initiatives, /initiatives?project_id={id}, /initiative/{id}, /initiative/{id}/context
Tasks: /tasks, /tasks?project_id={id}, /tasks?initiative_id={id}, /task/{id}
Documents: /documents, /documents?project_id={id}, /document/{id}
Workspace: /workspace/overview, /workspace/analytics
Search: /search?q={query}, /search/semantic?q={query}
Conversations: /conversations?project_id={id}, /conversation/{id}
Workflows: /workflows, /workflow/{id}

Available Prompts

Planning & Strategy:

  • project_planning - Generate full project plans with initiatives

  • initiative_strategy - Strategic planning for initiatives

  • task_breakdown - Break features into actionable tasks

  • sprint_planning - Plan sprints with current context

Analysis & Review:

  • project_health_check - Analyze project health

  • document_review - Review and improve documentation

  • daily_standup - Generate standup reports

  • project_kickoff - Initial project structuring

Special Features:

  • helios9_personality - HELIOS-9's sardonic AI insights

🔧 Integration Examples

Claude Desktop Configuration

Add to your claude_desktop_config.json:

Option 1: Using npx (Recommended)

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

Option 2: Using local installation

{
  "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"
      }
    }
  }
}

Cline/Continue Integration

{
  "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"
      }
    }
  }
}

OpenAI Integration

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

📊 Data Models

Project

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

Task

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
}

Document

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
}

🔒 Security

Authentication

  • API Key Authentication: Generated from your Helios-9 application

  • Secure Storage: API keys are securely stored and managed in Helios-9

  • User Context: All operations are performed in the context of the API key owner

Data Access

  • User Isolation: API enforces user-level data access controls

  • Permission-based: API keys can have granular permissions

  • Audit Logging: All API calls are logged for security and debugging

Rate Limiting

  • API-level: Rate limiting is enforced by the Helios-9 API

  • Per-key Limits: Different limits can be set per API key

  • Configurable: Limits can be adjusted in the Helios-9 admin panel

🏗️ Architecture

API-First Design

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

Benefits of API Integration

  • Centralized Auth: Authentication handled by main application

  • Consistent Data: Single source of truth for all data

  • Security: API-level security controls and monitoring

  • Scalability: Can serve multiple MCP clients

  • Maintainability: Single codebase for data operations

📈 Monitoring

Health Checks

The server provides health information through logging:

  • API connection status

  • Authentication state

  • Tool execution metrics

  • Error rates and types

Metrics Available

  • Tool call frequency

  • Response times

  • Authentication success/failure

  • API endpoint usage patterns

🛠️ Troubleshooting

Common Issues

Authentication Failed

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

Connection Issues

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

Permission Errors

  • Check API key permissions in Helios-9 admin panel

  • Ensure key has access to required resources (projects, tasks, documents)

Log Analysis

# Enable debug logging
LOG_LEVEL=debug npm start

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

🤝 Contributing

Development Setup

  1. Fork the repository

  2. Create feature branch

  3. Make changes with tests

  4. Submit pull request

Code Style

  • TypeScript strict mode

  • ESLint configuration

  • Prettier formatting

  • Conventional commits

📝 License

This project is part of the Helios-9 platform. See the main project LICENSE for details.

🆘 Support

Documentation

Community

  • GitHub Issues for bugs and features

  • Discussions for questions and ideas

  • Discord for real-time chat

📦 Publishing to npm

For Maintainers

  1. Login to npm:

    npm login
# Enter your npm credentials

  2. Verify package before publishing:

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

# Check package size
npm pack --dry-run

  3. Publish to npm:

    # For initial publish or updates
npm publish

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

  4. Verify publication:

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

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

Version Management

Update version before publishing:

# 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

Built with ❤️ for the AI-native future of project management

🚀 Roadmap

Coming Soon

  • Semantic Search: AI-powered search using OpenAI embeddings and Supabase pgvector

  • Task Dependencies: Link related tasks and track workflows

  • AI Conversations: Save and analyze AI agent interactions

  • Advanced Analytics: Project insights and productivity metrics

  • Bulk Operations: Update multiple items at once

  • Workflow Automation: Trigger-based task creation and updates

Future Vision

  • Multi-agent collaboration support

  • Custom tool creation framework

  • Integration with popular project management tools

  • Real-time collaboration features

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jakedx6/helios9-MCP-Server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server