# 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)
```bash
npx -y helios9-mcp-server@latest --api-key YOUR_HELIOS9_API_KEY
```

#### Option 2: Clone and build locally
1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Configure environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your Helios-9 API configuration
   ```

3. **Build the server:**
   ```bash
   npm run build
   ```

4. **Start the server:**
   ```bash
   npm start
   ```

### Environment Variables

```bash
# 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)
```json
{
  "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
```json
{
  "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

```json
{
  "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

```python
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
```typescript
interface Project {
  id: string
  user_id: string
  name: string
  description?: string
  status: 'active' | 'completed' | 'archived'
  created_at: string
  updated_at: string
}
```

### Task
```typescript
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
```typescript
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**
```bash
# Check API key validity
curl -H "Authorization: Bearer YOUR_API_KEY" https://www.helios9.app/api/auth/validate
```

**Connection Issues**
```bash
# 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
```bash
# 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
- [MCP Protocol Specification](https://modelcontextprotocol.io/)

### 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:**
   ```bash
   npm login
   # Enter your npm credentials
   ```

2. **Verify package before publishing:**
   ```bash
   # Dry run to see what will be published
   npm publish --dry-run
   
   # Check package size
   npm pack --dry-run
   ```

3. **Publish to npm:**
   ```bash
   # For initial publish or updates
   npm publish
   
   # For beta/alpha releases
   npm publish --tag beta
   ```

4. **Verify publication:**
   ```bash
   # 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:
```bash
# 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