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