Content
# 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 SSE mode
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)
bun start
# Or start the HTTP server
bun run start:http
```
5. For development with auto-reload:
```bash
# Development mode with stdio
bun run dev
# Development mode with HTTP
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` or `sse`)
- `MCP_PORT`: Port number for SSE mode (default: 3001)
- `MCP_HOST`: Host address for SSE mode (default: 0.0.0.0)
- `MCP_AUTH_TOKEN`: Authentication token for SSE mode (optional)
#### 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.
Connection Info
You Might Also Like
MarkItDown MCP
Converting files and office documents to Markdown.
semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
opik
Debug, evaluate, and monitor your LLM applications, RAG systems, and agentic...
open-skills
OpenSkills: Run Claude Skills Locally using any LLM
SmartDB_MCP
Universal database MCP server connecting to MySQL, PostgreSQL, SQL Server,...
neurolink
Universal AI Development Platform with MCP server integration,...