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)

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

🔑 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)

Option 2: Using local installation

Cline/Continue Integration

OpenAI Integration

📊 Data Models

Project

Task

Document

🔒 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

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

Connection Issues

Permission Errors

• Check API key permissions in Helios-9 admin panel

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

Log Analysis

🤝 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

• 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

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:

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