aha-mcp

# Aha MCP Server    A Model Context Protocol (MCP) server that provides seamless integration with Aha.io's product management platform. Features offline database synchronization, vector embeddings for semantic search, and comprehensive workflow automation. ## 🔧 Client Configuration ### Claude Desktop Configuration To use this MCP server with Claude Desktop, add the following to your `claude_desktop_config.json`: **Using npx:** ```json { "mcpServers": { "aha": { "command": "npx", "args": ["@cedricziel/aha-mcp"], "env": { "AHA_COMPANY": "your-company", "AHA_TOKEN": "your-api-token" } } } } ``` **Using Docker:** ```json { "mcpServers": { "aha": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "AHA_COMPANY=your-company", "-e", "AHA_TOKEN=your-api-token", "ghcr.io/cedricziel/aha-mcp" ] } } } ``` > **Note:** Replace `your-company` and `your-api-token` with your actual Aha.io subdomain and API token. ## 🚀 Getting Started ### Quick Start with npx You can run the MCP server directly using npx without installing it globally: ```bash # Set environment variables export AHA_COMPANY="your-company" # Your Aha.io subdomain export AHA_TOKEN="your-api-token" # Your Aha.io API token # Run the server npx @cedricziel/aha-mcp ``` ### Quick Start with Docker You can also run the MCP server using Docker: ```bash # Set environment variables export AHA_COMPANY="your-company" # Your Aha.io subdomain export AHA_TOKEN="your-api-token" # Your Aha.io API token # Run in stdio mode (default) docker run --rm -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp # Run in Streamable HTTP mode (recommended for remote access) docker run --rm -p 3001:3001 -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp --mode streamable-http # Run in SSE mode (deprecated) docker run --rm -p 3001:3001 -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp --mode sse ``` ### Development Setup 1. Install [Bun](https://bun.sh/) if you haven't already: ```bash curl -fsSL https://bun.sh/install | bash ``` 2. Install dependencies: ```bash bun install ``` 3. Configure environment variables: ```bash export AHA_COMPANY="your-company" # Your Aha.io subdomain export AHA_TOKEN="your-api-token" # Your Aha.io API token ``` 4. Start the server: ```bash # Start the stdio server (for MCP clients - default) bun start # Or start with Streamable HTTP (recommended for remote access) bun start -- --mode streamable-http # Or start the HTTP server (legacy entry point) bun run start:http ``` 5. For development with auto-reload: ```bash # Development mode with stdio bun run dev # Development mode with Streamable HTTP bun run dev -- --mode streamable-http # Development mode with HTTP (legacy) bun run dev:http ``` ## 🔌 Aha.io Integration This MCP server provides hybrid integration with Aha.io through both live API access and offline database synchronization. The server automatically maintains a local SQLite database with your Aha.io data, enabling faster queries, offline access, and advanced semantic search capabilities. ### Architecture Overview - **Hybrid Data Access**: Live API calls for real-time data + offline SQLite database for performance - **Background Sync**: Automatic synchronization of Aha.io entities to local database - **Vector Embeddings**: Semantic search using sentence transformers and SQLite vector extensions - **Real-time Progress**: Background job monitoring with detailed progress tracking - **Configuration Management**: Runtime configuration without server restarts ### Configuration The Aha.io integration can be configured using multiple methods, with the following priority order: 1. **Environment Variables** (highest priority) 2. **Configuration File** (`~/.aha-mcp-config.json`) 3. **Default Values** (lowest priority) #### Environment Variables - `AHA_COMPANY`: Your Aha.io subdomain (e.g., `mycompany` for `mycompany.aha.io`) - `AHA_TOKEN`: Your Aha.io API token (for API token authentication) - `AHA_ACCESS_TOKEN`: Your OAuth 2.0 access token (for OAuth authentication) - `MCP_TRANSPORT_MODE`: Transport mode (`stdio`, `streamable-http`, or `sse`) - `MCP_PORT`: Port number for HTTP-based modes (default: 3001) - `MCP_HOST`: Host address for HTTP-based modes (default: 0.0.0.0) - `MCP_AUTH_TOKEN`: Authentication token for HTTP-based modes (optional) #### Transport Modes The server supports three transport modes: 1. **stdio** (default) - Standard input/output for local MCP clients ```bash aha-mcp --mode stdio ``` 2. **streamable-http** (recommended for remote access) - Modern HTTP transport ```bash aha-mcp --mode streamable-http --port 3001 --host localhost ``` - Protocol version: 2025-06-18 - Single `/mcp` endpoint for all communication - Better scalability and performance - Origin validation for security 3. **sse** (deprecated) - Legacy SSE transport - Deprecated as of MCP spec 2025-03-26 - Will be removed in a future version - Use `streamable-http` instead #### Authentication Methods The Aha MCP Server supports two authentication methods: 1. **API Token Authentication** (Recommended for server-to-server integrations) - Set `AHA_TOKEN` environment variable - Most secure for automated applications - Generate tokens at: Settings → Personal → API Access 2. **OAuth 2.0 Authentication** (For web applications) - Set `AHA_ACCESS_TOKEN` environment variable - Best for user-authorized applications - Requires OAuth flow implementation **Configuration Examples:** ```bash # API Token Authentication (Recommended) export AHA_COMPANY="mycompany" export AHA_TOKEN="your-api-token" # OAuth 2.0 Authentication export AHA_COMPANY="mycompany" export AHA_ACCESS_TOKEN="your-oauth-access-token" ``` #### Runtime Configuration The server supports runtime configuration through MCP tools, allowing you to set up credentials without restarting: ```bash # Configure server settings aha_mcp --mode stdio > Use the `configure_server` tool to set: > - company: "your-company-subdomain" > - token: "your-api-token" > - mode: "stdio" or "sse" > - port: 3001 (for SSE mode) > - host: "0.0.0.0" (for SSE mode) # Check current configuration > Use the `get_server_config` tool to view current settings # Test your configuration > Use the `test_configuration` tool to verify API connectivity ``` #### Command Line Arguments You can override configuration settings using command line arguments: ```bash # Force stdio mode aha-mcp --mode stdio # Force SSE mode with custom port aha-mcp --mode sse --port 3000 --host localhost # Get help aha-mcp --help ``` #### Configuration File The server automatically creates and manages a configuration file at `~/.aha-mcp-config.json`. This file stores your settings with basic token obfuscation for security. Example configuration file: ```json { "company": "your-company", "token": "base64-encoded-token", "mode": "stdio", "port": 3001, "host": "0.0.0.0" } ``` #### Transport Modes The server supports two transport modes: 1. **stdio**: Standard input/output mode for MCP client integration (default) 2. **sse**: Server-Sent Events mode for HTTP-based integration Example usage: ```bash # Stdio mode (default) aha-mcp # SSE mode aha-mcp --mode sse --port 3001 ``` #### Authentication (SSE Mode) The SSE mode supports optional Bearer token authentication for enhanced security: ##### Environment Variable Configuration ```bash # Set authentication token export MCP_AUTH_TOKEN="your-secure-token-here" # Start server with authentication aha-mcp --mode sse --port 3001 ``` ##### Client Authentication When authentication is enabled, clients must include a Bearer token in the Authorization header: ```bash # SSE connection with authentication curl -H "Authorization: Bearer your-secure-token-here" \ http://localhost:3001/sse # Messages endpoint with authentication curl -X POST \ -H "Authorization: Bearer your-secure-token-here" \ -H "Content-Type: application/json" \ -d '{"method": "tools/list", "params": {}}' \ http://localhost:3001/messages ``` ##### JavaScript Client Example ```javascript // SSE connection with authentication const eventSource = new EventSource('http://localhost:3001/sse', { headers: { 'Authorization': 'Bearer your-secure-token-here' } }); // Fetch with authentication fetch('http://localhost:3001/messages', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-secure-token-here' }, body: JSON.stringify({ method: 'tools/list', params: {} }) }); ``` ##### Security Notes - **Backward Compatibility**: Authentication is optional. If `MCP_AUTH_TOKEN` is not set, all requests are allowed. - **Token Security**: Use strong, randomly generated tokens (minimum 8 characters). - **HTTPS**: In production, always use HTTPS to protect tokens in transit. - **Token Storage**: Tokens are obfuscated (base64 encoded) in the configuration file but should be treated as sensitive data. ##### Checking Authentication Status You can check if authentication is enabled by visiting the server info endpoint: ```bash curl http://localhost:3001/ # Response includes: # { # "authentication": { # "enabled": true, # "type": "Bearer token", # "note": "Authentication required for SSE and messages endpoints" # } # } ``` #### Configuration Management Tools The server provides three MCP tools for configuration management: 1. **configure_server**: Update server settings at runtime 2. **get_server_config**: View current configuration and validation status 3. **test_configuration**: Test API connectivity with current settings These tools allow you to manage configuration without restarting the server, making it easy to switch between different Aha.io accounts or update credentials. ### Database Synchronization The server maintains a local SQLite database with your Aha.io data for improved performance and offline access. #### Sync Management Tools - `aha_sync_start`: Start background synchronization of specified entity types - `aha_sync_status`: Check the status and progress of sync jobs - `aha_sync_stop`: Stop a running sync job - `aha_sync_pause`: Pause a sync job (can be resumed later) - `aha_sync_resume`: Resume a paused sync job - `aha_sync_history`: View detailed history of sync operations - `aha_sync_health`: Get overall sync service health status - `aha_database_health`: Check database connectivity and statistics - `aha_database_cleanup`: Clean up old sync jobs and optimize database #### Sync Features - **Entity Types**: Sync features, products, ideas, epics, initiatives, releases, goals, users, comments - **Progress Tracking**: Real-time progress updates with detailed statistics - **Error Handling**: Comprehensive error logging and recovery mechanisms - **Batch Processing**: Configurable batch sizes for optimal performance - **Incremental Updates**: Support for `updatedSince` filtering to sync only recent changes - **Concurrent Operations**: Multiple sync jobs can run simultaneously #### Example Sync Workflow ```bash # Start syncing features and products aha_sync_start --entities features,products --batchSize 50 # Check progress aha_sync_status --jobId sync-abc123 # View sync history aha_sync_history --jobId sync-abc123 --limit 20 # Check overall health aha_sync_health ``` ### Semantic Search & Embeddings The server includes advanced semantic search capabilities using vector embeddings. #### Embedding Management Tools - `aha_generate_embeddings`: Generate vector embeddings for entity text content - `aha_embedding_status`: Check the status of embedding generation jobs - `aha_semantic_search`: Search entities using natural language queries - `aha_generate_entity_embedding`: Generate embedding for a specific entity - `aha_find_similar`: Find entities similar to a given entity - `aha_pause_embeddings`: Pause embedding generation jobs - `aha_stop_embeddings`: Stop embedding generation jobs #### Semantic Search Features - **Vector Storage**: Embeddings stored in SQLite with sqlite-vec extension - **Multiple Models**: Support for different embedding models (default: all-MiniLM-L6-v2) - **Similarity Search**: Cosine similarity search with configurable thresholds - **Cross-Entity Search**: Find similar content across different entity types - **Real-time Generation**: Background embedding generation with progress tracking #### Example Embedding Workflow ```bash # Generate embeddings for features and ideas aha_generate_embeddings --entities features,ideas --batchSize 25 # Search for similar content aha_semantic_search --query "user authentication security" --threshold 0.7 # Find similar features to a specific feature aha_find_similar --entityType features --entityId FEAT-123 --limit 5 # Check embedding job progress aha_embedding_status --jobId embed-xyz789 ``` ### Available Resources #### Individual Entity Resources - `aha_idea`: Access individual ideas using `aha://idea/{id}` - `aha_feature`: Access individual features using `aha://feature/{id}` - `aha_user`: Access individual users using `aha://user/{id}` - `aha_epic`: Access individual epics using `aha://epic/{id}` - `aha_product`: Access individual products using `aha://product/{id}` - `aha_initiative`: Access individual initiatives using `aha://initiative/{id}` - `aha_requirement`: Access individual requirements using `aha://requirement/{id}` - `aha_competitor`: Access individual competitors using `aha://competitor/{id}` - `aha_todo`: Access individual todos using `aha://todo/{id}` #### Collection Resources - `aha_features`: List features with optional filtering using `aha://features?query=...&tag=...` - `aha_users`: List all users using `aha://users` - `aha_epics`: List epics for a product using `aha://epics/{product_id}` - `aha_products`: List all products using `aha://products?updatedSince=...` - `aha_initiatives`: List all initiatives using `aha://initiatives?query=...&onlyActive=true` - `aha_ideas`: List all ideas globally using `aha://ideas?query=...&status=...&category=...` - `aha_ideas_by_product`: List ideas for a product using `aha://ideas/{product_id}?query=...&spam=false&sort=recent` - `aha_competitors`: List competitors for a product using `aha://competitors/{product_id}` - `aha_product_releases`: List releases for a product using `aha://releases/{product_id}?query=...&status=...` - `aha_initiative_epics`: List epics for an initiative using `aha://initiative/{initiative_id}/epics` #### Comment Resources - `aha_epic_comments`: Access comments for an epic using `aha://comments/epic/{epic_id}` - `aha_idea_comments`: Access comments for an idea using `aha://comments/idea/{idea_id}` - `aha_initiative_comments`: Access comments for an initiative using `aha://comments/initiative/{initiative_id}` - `aha_product_comments`: Access comments for a product using `aha://comments/product/{product_id}` - `aha_goal_comments`: Access comments for a goal using `aha://comments/goal/{goal_id}` - `aha_release_comments`: Access comments for a release using `aha://comments/release/{release_id}` - `aha_release_phase_comments`: Access comments for a release phase using `aha://comments/release-phase/{release_phase_id}` - `aha_requirement_comments`: Access comments for a requirement using `aha://comments/requirement/{requirement_id}` - `aha_todo_comments`: Access comments for a todo using `aha://comments/todo/{todo_id}` #### Goal Resources - `aha_goal`: Access individual goals using `aha://goal/{goal_id}` - `aha_goals`: List all goals using `aha://goals` - `aha_goal_epics`: Access epics associated with a goal using `aha://goal/{goal_id}/epics` #### Release Resources - `aha_release`: Access individual releases using `aha://release/{release_id}` - `aha_releases`: List all releases using `aha://releases` - `aha_release_features`: Access features associated with a release using `aha://release/{release_id}/features` - `aha_release_epics`: Access epics associated with a release using `aha://release/{release_id}/epics` - `aha_release_phase`: Access individual release phases using `aha://release-phase/{release_phase_id}` - `aha_release_phases`: List all release phases using `aha://release-phases` #### Custom Fields Resources - `aha_custom_fields`: List all custom field definitions using `aha://custom-fields` - `aha_custom_field_options`: Access options for a custom field using `aha://custom-field/{custom_field_id}/options` #### Resource URI Examples ``` # Individual Entity Resources aha://idea/IDEA-123 # Get specific idea aha://feature/PROJ-456 # Get specific feature aha://user/USER-789 # Get specific user aha://epic/EPIC-101 # Get specific epic aha://product/PROD-001 # Get specific product aha://initiative/INIT-202 # Get specific initiative aha://requirement/REQ-666 # Get specific requirement aha://competitor/COMP-444 # Get specific competitor aha://todo/TODO-777 # Get specific todo # Collection Resources (enhanced with filtering) aha://features?query=auth&tag=api&assignedToUser=user@example.com # Search features aha://users # List all users aha://epics/PROJ-001 # List epics for product aha://products?updatedSince=2024-01-01T00:00:00Z # List products with filter aha://initiatives?query=mobile&onlyActive=true&assignedToUser=user@example.com # Search initiatives aha://ideas?query=nodejs&status=new&category=enhancement # List ideas globally with filters aha://ideas/PROJ-001?query=search&spam=false&sort=recent&tag=enhancement # List ideas with filters aha://competitors/PROJ-001 # List competitors for product aha://releases/PROJ-001?query=mobile&status=shipped # List releases for product aha://initiative/INIT-123/epics # List epics for initiative # Comment Resources aha://comments/epic/EPIC-123 # Get comments for epic aha://comments/idea/IDEA-456 # Get comments for idea aha://comments/initiative/INIT-789 # Get comments for initiative aha://comments/product/PROD-001 # Get comments for product aha://comments/goal/GOAL-555 # Get comments for goal aha://comments/release/REL-333 # Get comments for release aha://comments/release-phase/RP-444 # Get comments for release phase aha://comments/requirement/REQ-666 # Get comments for requirement aha://comments/todo/TODO-777 # Get comments for todo # Goal Resources aha://goal/GOAL-123 # Get specific goal aha://goals # List all goals aha://goal/GOAL-456/epics # Get epics for goal # Release Resources aha://release/REL-123 # Get specific release aha://releases # List all releases aha://release/REL-456/features # Get features for release aha://release/REL-456/epics # Get epics for release aha://release-phase/RP-123 # Get specific release phase aha://release-phases # List all release phases # Custom Fields Resources aha://custom-fields # List all custom field definitions aha://custom-field/CF-123/options # Get options for custom field ``` ### Available Tools **Note**: Read operations (list/get) are handled through MCP resources. Tools are focused on write operations and relationship management. #### Write Operation Tools - `aha_create_feature_comment`: Create a comment on a feature - `aha_create_initiative_in_product`: Create an initiative within a specific product #### Feature CRUD Tools - `aha_create_feature`: Create a feature within a specific release - `aha_update_feature`: Update a feature - `aha_delete_feature`: Delete a feature - `aha_update_feature_progress`: Update a feature's progress - `aha_update_feature_score`: Update a feature's score - `aha_update_feature_custom_fields`: Update a feature's custom fields #### Epic CRUD Tools - `aha_update_epic`: Update an epic - `aha_delete_epic`: Delete an epic - `aha_create_epic_in_product`: Create an epic within a specific product - `aha_create_epic_in_release`: Create an epic within a specific release #### Idea CRUD Tools - `aha_create_idea`: Create an idea in a product - `aha_create_idea_with_category`: Create an idea with a category - `aha_create_idea_with_score`: Create an idea with a score - `aha_delete_idea`: Delete an idea #### Competitor Management Tools - `aha_create_competitor`: Create a competitor in a product - `aha_update_competitor`: Update a competitor - `aha_delete_competitor`: Delete a competitor #### Portal Integration Tools - `aha_create_idea_by_portal_user`: Create an idea by a portal user - `aha_create_idea_with_portal_settings`: Create an idea with enhanced portal settings #### Relationship Management Tools - `aha_associate_feature_with_epic`: Associate a feature with an epic - `aha_move_feature_to_release`: Move a feature to a different release - `aha_associate_feature_with_goals`: Associate a feature with multiple goals - `aha_update_feature_tags`: Update tags for a feature **Note**: The MCP server follows best practices by separating read and write operations: - **Resources** are used for all read operations (list/get) and provide comprehensive access to Aha.io entities with advanced filtering capabilities through URI parameters - **Tools** are reserved for write operations (create/update/delete) and relationship management (associate/move) that modify data in Aha.io This separation ensures a clean architecture where resources handle data retrieval and tools handle data modification. ### 🚀 Phase 8 - Complete CRUD Operations & Advanced Features The MCP server now provides comprehensive lifecycle management for Aha.io entities with complete CRUD operations, portal integration, and advanced workflow features: #### Phase 8A - Core CRUD Operations (18 Tools) **Feature Management (6 Tools)** - `aha_create_feature`: Create features within releases - `aha_update_feature`: Update existing features - `aha_delete_feature`: Delete features - `aha_update_feature_progress`: Update feature progress (0-100%) - `aha_update_feature_score`: Update feature scores - `aha_update_feature_custom_fields`: Update feature custom fields **Epic Management (2 Tools)** - `aha_update_epic`: Update existing epics - `aha_delete_epic`: Delete epics **Idea Management (4 Tools)** - `aha_create_idea`: Create ideas in products - `aha_create_idea_with_category`: Create ideas with categories - `aha_create_idea_with_score`: Create ideas with scores - `aha_delete_idea`: Delete ideas #### Phase 8B - Competitor Management (3 Tools) **Competitor Management (3 Tools)** - `aha_create_competitor`: Create competitors in products - `aha_update_competitor`: Update existing competitors - `aha_delete_competitor`: Delete competitors **Note**: Initiative data access is now handled through MCP resources (`aha_initiative`, `aha_initiatives`, `aha_initiative_comments`, `aha_initiative_epics`) for a cleaner separation between read and write operations. #### Phase 8C - Portal Integration & Advanced Features (2 Tools) **Portal Integration** - `aha_create_idea_by_portal_user`: Create ideas by portal users - `aha_create_idea_with_portal_settings`: Create ideas with portal settings #### Enhanced Filtering & Resources - **Initiative Filtering**: Enhanced with `query`, `updatedSince`, `assignedToUser`, `onlyActive` parameters - **Portal Configuration**: Support for `skip_portal` and `submitted_idea_portal_id` settings - **Comprehensive Entity Coverage**: Full CRUD operations for features, epics, ideas, and competitors #### Technical Achievements - **49 total MCP tools** (comprehensive Aha.io integration + sync + embeddings + config) - **50 total MCP resources** (complete entity coverage) - **13 domain-specific prompts** (workflow automation) - **25 core CRUD and write operation tools** for complete lifecycle management - **9 sync & database tools** for offline data management - **10 embedding & semantic search tools** for AI-powered content discovery - **5 server configuration tools** for runtime configuration - **209 tests passing** with comprehensive service coverage - **SQLite database with vector extensions** for high-performance local storage - **Background job processing** with real-time progress tracking - **Semantic search capabilities** using transformer models - **Comprehensive error handling** with proper Zod schema validation - **Professional-grade implementation** following MCP best practices ## 🛠️ Adding Custom Tools and Resources When adding custom tools, resources, or prompts to your MCP server: 1. Use underscores (`_`) instead of hyphens (`-`) in all resource, tool, and prompt names ```typescript // Good: Uses underscores server.tool( "my_custom_tool", "Description of my custom tool", { param_name: z.string().describe("Parameter description") }, async (params) => { // Tool implementation } ); // Bad: Uses hyphens, may cause issues with Cursor server.tool( "my-custom-tool", "Description of my custom tool", { param-name: z.string().describe("Parameter description") }, async (params) => { // Tool implementation } ); ``` 2. This naming convention ensures compatibility with Cursor and other AI tools that interact with your MCP server ## 🐳 Docker Usage ### Docker Images The Aha MCP server is available as Docker images on GitHub Container Registry: - **GitHub Container Registry**: `ghcr.io/cedricziel/aha-mcp` ### Running with Docker #### Basic Usage ```bash # Run in stdio mode (default) docker run --rm \ -e AHA_COMPANY="your-company" \ -e AHA_TOKEN="your-api-token" \ ghcr.io/cedricziel/aha-mcp # Run in SSE mode docker run --rm \ -p 3001:3001 \ -e AHA_COMPANY="your-company" \ -e AHA_TOKEN="your-api-token" \ ghcr.io/cedricziel/aha-mcp --mode sse # Run in SSE mode with authentication docker run --rm \ -p 3001:3001 \ -e AHA_COMPANY="your-company" \ -e AHA_TOKEN="your-api-token" \ -e MCP_AUTH_TOKEN="your-secure-token" \ ghcr.io/cedricziel/aha-mcp --mode sse ``` #### Persistent Configuration To persist configuration between runs: ```bash # Create a named volume for configuration docker volume create aha-mcp-config # Run with persistent configuration docker run --rm \ -v aha-mcp-config:/home/mcp/.config \ -e AHA_COMPANY="your-company" \ -e AHA_TOKEN="your-api-token" \ ghcr.io/cedricziel/aha-mcp ``` #### Using Docker Compose The repository includes a `docker-compose.yml` file for easy setup: ```bash # Copy the example environment file cp .env.example .env # Edit .env with your credentials AHA_COMPANY=your-company AHA_TOKEN=your-api-token # Run in stdio mode docker-compose --profile stdio up # Run in SSE mode docker-compose --profile sse up # Run in detached mode docker-compose --profile sse up -d ``` Example `.env` file: ```env AHA_COMPANY=mycompany AHA_TOKEN=your-api-token-here MCP_AUTH_TOKEN=your-secure-token-here ``` ### Docker Environment Variables The Docker image supports all the same environment variables as the npm package: | Variable | Description | Default | |----------|-------------|---------| | `AHA_COMPANY` | Aha.io company subdomain | - | | `AHA_TOKEN` | Aha.io API token | - | | `MCP_TRANSPORT_MODE` | Transport mode (`stdio` or `sse`) | `stdio` | | `MCP_PORT` | Port for SSE mode | `3001` | | `MCP_HOST` | Host for SSE mode | `0.0.0.0` | | `MCP_AUTH_TOKEN` | Authentication token for SSE mode | - | | `MCP_CONFIG_DIR` | Configuration directory | `/home/mcp/.config` | ### Health Checks The Docker image includes health checks for SSE mode: ```bash # Check if the SSE server is healthy curl http://localhost:3001/health # Get detailed server status curl http://localhost:3001/status ``` ### Building from Source To build the Docker image locally: ```bash # Build the image npm run docker:build # Test the image npm run docker:test # Run the image npm run docker:run # Run in SSE mode npm run docker:run:sse ``` ### Multi-Architecture Support The Docker images are built for multiple architectures: - `linux/amd64` (x86_64) - `linux/arm64` (Apple Silicon, ARM64) Docker will automatically pull the correct image for your platform. ### Docker Security The Docker image follows security best practices: - Runs as non-root user (`mcp`) - Uses minimal Alpine Linux base image - Includes tini for proper signal handling - Configuration directory has proper permissions - Uses multi-stage builds to reduce attack surface ## 🏗️ Development ### Commit Guidelines This project uses [Conventional Commits](https://www.conventionalcommits.org/) to ensure consistent commit messages and enable automated versioning. **Commit Message Format:** ``` <type>(<scope>): <subject> <body> <footer> ``` **Types:** - `feat`: A new feature - `fix`: A bug fix - `docs`: Documentation only changes - `style`: Changes that do not affect the meaning of the code - `refactor`: A code change that neither fixes a bug nor adds a feature - `perf`: A code change that improves performance - `test`: Adding missing tests or correcting existing tests - `build`: Changes that affect the build system or external dependencies - `ci`: Changes to CI configuration files and scripts - `chore`: Other changes that don't modify src or test files **Examples:** ```bash feat: add new MCP tool for listing projects fix: resolve authentication issue with API tokens docs: update README with installation instructions feat!: change API response format (breaking change) ``` Commit messages are validated using commitlint on every commit and in CI. ### Testing #### Local Testing Run the test suite: ```bash # Run all tests bun test # Run tests in watch mode bun run test:watch # Run tests with coverage bun test --coverage ``` #### Docker Testing The Docker environment includes all necessary dependencies for testing: ```bash # Test the Docker build docker build -t aha-mcp-test . # Run tests inside Docker container docker run --rm aha-mcp-test bun test # Test with environment variables docker run --rm \ -e AHA_COMPANY="test-company" \ -e AHA_TOKEN="test-token" \ aha-mcp-test bun test # Verify all dependencies are available docker run --rm aha-mcp-test bun install --dry-run # Test database functionality (SQLite) docker run --rm aha-mcp-test node -e " const sqlite3 = require('sqlite3'); const db = new sqlite3.Database(':memory:'); console.log('SQLite available:', !!db); db.close(); " # Test if sqlite-vec extension loads (graceful fallback if not available) docker run --rm aha-mcp-test bun run start --help ``` #### Testing Database Features The Docker environment includes: - **SQLite3**: Core database functionality - **Node.js sqlite packages**: Database drivers and utilities - **Graceful fallback**: sqlite-vec extension warnings are suppressed in test environments - **Temporary databases**: Each test uses isolated temporary database files - **Proper cleanup**: Database connections and files are cleaned up after tests #### Verifying Docker Environment ```bash # Check all key components are available docker run --rm aha-mcp-test sh -c " echo 'Checking Bun...'; bun --version echo 'Checking Node.js...'; node --version echo 'Checking SQLite...'; node -e 'console.log(require(\"sqlite3\"))' echo 'Checking dependencies...'; bun install --dry-run echo 'Running basic tests...'; bun test --reporter=dot " # Test MCP server startup docker run --rm -d --name aha-test \ -e AHA_COMPANY="test" \ -e AHA_TOKEN="test" \ aha-mcp-test # Check if server started successfully docker logs aha-test # Cleanup docker stop aha-test ``` The Docker environment supports the full test suite including: - **194+ test cases** across all services - **Database service tests** (25 test cases) - **Background sync service tests** (16 test cases) - **MCP accessibility tests** (172 test cases) - **SQLite extension warnings** are automatically suppressed in test mode ### Building To build for production: ```bash # Build stdio server bun run build # Build HTTP server bun run build:http ``` ### Publishing #### Automated Release Process (Recommended) This project uses [release-please](https://github.com/googleapis/release-please-action) for automated versioning and publishing: 1. **Make changes** using [Conventional Commits](https://www.conventionalcommits.org/) format: - `feat:` for new features (minor version bump) - `fix:` for bug fixes (patch version bump) - `feat!:` or `fix!:` for breaking changes (major version bump) 2. **Push to main** - release-please will automatically: - Create a release PR with updated version and changelog - Once the release PR is merged, it will create a GitHub release - The release will trigger automatic publication to npm #### Manual Publishing To publish the package manually: ```bash # 1. Ensure you're logged in to npm npm login # 2. Build the package bun run build # 3. Publish to npm npm publish --access public ``` **Note**: Make sure to set the `NPM_TOKEN` secret in your repository settings for automated publishing. ## 📚 Documentation - [CLAUDE.md](CLAUDE.md) - Development guidance for Claude Code when working with this repository - [MCP Documentation](https://modelcontextprotocol.io/introduction) - Official Model Context Protocol documentation ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.