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

Install dependencies:
```
npm install
```

Configure environment:

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

Build the server:
```
npm run build
```
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

Login to your Helios-9 application
Navigate to Settings > API Keys
Click "Generate New API Key"
Copy the generated key (it will only be shown once)
Set permissions for the key (read/write access to projects, tasks, documents)
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

Fork the repository
Create feature branch
Make changes with tests
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

MCP Protocol Specification

Community

GitHub Issues for bugs and features
Discussions for questions and ideas
Discord for real-time chat

📦 Publishing to npm

For Maintainers

Login to npm:
```
npm login
# Enter your npm credentials
```

Verify package before publishing:

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

# Check package size
npm pack --dry-run

Publish to npm:

# For initial publish or updates
npm publish

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

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

Server	Summary	Actions
Zapier	Beta	View
Yandex Browser Tabs	MCP (Model Context Protocol) сервер для управления вкладками Яндекс Браузера с расширенной функциона...	View
Xero	This is a Model Context Protocol (MCP) server implementation for Xero. It provides a bridge between...	View
Attio MCP Server		View
MCP Client Configuration Server	This MCP server helps manage configurations for different MCP clients. It provides tools to retrieve...	View
Garmin Workouts MCP	Create Garmin Connect workouts using natural language descriptions. Built as an MCP (Model Context P...	View

Helios-9