MCP Aha! Server

A Model Context Protocol (MCP) server that provides integration with Aha! for product management and roadmapping.

Overview

This MCP server enables AI assistants like Claude to query and interact with Aha! data, providing seamless access to product roadmaps, epics, features, and more through the Model Context Protocol.

Features

• 🔍 Aha! Integration: Access product management data from Aha!
• 🛠️ MCP Integration: Full Model Context Protocol support
• 📊 Epic Management: List and search epics with advanced filtering
• 📝 TypeScript: Written in TypeScript with strict type checking
• ✅ Testing: Comprehensive test suite with Jest
• 🎨 Code Quality: ESLint and Prettier for consistent code style

Prerequisites

• Node.js 20.x or higher
• Aha! account with API access
• Claude Desktop or another MCP-compatible client

Installation

For Claude Desktop Users

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "aha": {
      "command": "npx",
      "args": ["-y", "@robyates/mcp-aha"],
      "env": {
        "AHA_API_TOKEN": "your_token_here",
        "AHA_API_BASE_URL": "https://yourcompany.aha.io",
        "AHA_PRODUCT_ID": "YOUR_PRODUCT_ID"
      }
    }
  }
}

For Development

# Clone the repository
git clone https://github.com/your-org/mcp-aha.git
cd mcp-aha

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

The server requires three environment variables:

• AHA_API_TOKEN: Your Aha! API token
• AHA_API_BASE_URL: Your Aha! domain base URL (e.g., https://yourcompany.aha.io)
• AHA_PRODUCT_ID: Your Aha! product ID (e.g., PRODUCT)

Getting Your Aha! API Token

1. Log in to your Aha! account
2. Go to Settings → Personal → Developer
3. Click Generate API key
4. Copy the generated token

Finding Your Product ID

1. Navigate to your product in Aha!
2. The product ID is in the URL: https://yourcompany.aha.io/products/PRODUCT_ID
3. Or find it in Settings → Product → Overview

Development

# Run in development mode with auto-reload
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run integration tests
npm run test:integration

# Generate test coverage report
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code with Prettier
npm run prettier:fix

Usage

Available Tools

aha_list_master_epics

List and search master epics from your configured Aha! product.

Note on Terminology: In IBM terminology, "master epics" contain "epics". In Aha! terminology, these are called "epics" and "features" respectively.

Parameters:

• q (optional): Search term to match against master epic name
• updated_since (optional): ISO8601 UTC timestamp (e.g., "2024-01-01T00:00:00Z")
• tag (optional): Tag value to filter master epics
• assigned_to_user (optional): User ID or email address

Example:

List all master epics updated since January 1, 2024

Returns:

• Complete master epic details including custom fields
• Workflow status, assignments, releases
• Features (epics in IBM terminology), goals, and tags
• Custom fields like roadmap inclusion, personas, owners, etc.

aha_list_epics

List and search epics (called features in Aha! API) from your configured Aha! product.

Note on Terminology: In IBM terminology, these are "epics". In Aha! terminology, these are "features". This tool retrieves what Aha! calls "features" but presents them as "epics" to match IBM terminology.

Important: Due to the large volume of features, queries are limited to the last 90 days. If no updated_since is provided, it defaults to 90 days ago. The tool uses parallel fetching to retrieve all pages efficiently.

Parameters:

• q (optional): Search term to match against epic name
• updated_since (optional): ISO8601 UTC timestamp (e.g., "2024-01-01T00:00:00Z"). Must be within the last 90 days. Defaults to 90 days ago if not provided.
• tag (optional): Tag value to filter epics
• assigned_to_user (optional): User ID or email address

Example:

List all epics updated in the last 30 days

Returns:

• Complete epic details including custom fields
• Workflow status, workflow kind, assignments, releases
• Initiative (master epic) reference
• Project information, goals, and tags
• Custom fields like roadmap inclusion, personas, owners, etc.

Running the Server Locally

# Set environment variables
export AHA_API_TOKEN="your_token_here"
export AHA_API_BASE_URL="https://yourcompany.aha.io"
export AHA_PRODUCT_ID="YOUR_PRODUCT_ID"

# Start the compiled server
npm start

# Or run directly with ts-node for development
npm run dev

Project Structure

mcp-aha/
├── src/                    # Source TypeScript files
│   └── index.ts           # Main MCP server entry point
├── tests/                 # Test files
│   └── integration/       # Integration tests
├── dist/                  # Compiled JavaScript (generated)
├── coverage/              # Test coverage reports (generated)
├── node_modules/          # Dependencies (generated)
├── .env                   # Environment variables (not in git)
├── .gitignore            # Git ignore rules
├── .prettierrc.yaml      # Prettier configuration
├── eslint.config.mjs     # ESLint configuration
├── jest.config.ts        # Jest test configuration
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript compiler configuration
├── tsconfig.lint.json    # TypeScript configuration for linting
└── README.md             # This file

Configuration

TypeScript

The project uses strict TypeScript configuration with:

• Target: ES2017
• Module: CommonJS
• Strict type checking enabled
• Source maps for debugging
• Declaration files generated

Linting

ESLint is configured with:

• TypeScript ESLint plugin
• Prettier integration
• Comprehensive rule set for code quality
• Naming conventions enforcement

Testing

Jest is configured with:

• ts-jest preset for TypeScript support
• Coverage reporting with v8 provider
• Parallel test execution (50% CPU cores)
• Dedicated cache directory for faster runs

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (npm test && npm run lint)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Quality Standards

• All code must pass TypeScript compilation with no errors
• ESLint rules must be satisfied
• Code must be formatted with Prettier
• All tests must pass
• Maintain or improve test coverage

Publishing to npm

Before publishing, make sure to:

1. Build and test the package:

npm run build
npm test

4. Publish to npm:

# For first-time publish
npm publish --access public

# For updates
npm version patch  # or minor, or major
npm publish

Security Notes

• Never commit your .env file - it contains sensitive API tokens
• The .env file is excluded from the npm package via the files field in package.json
• Users configure their credentials via environment variables in their MCP client configuration
• The .env.example file provides a template without actual credentials

Troubleshooting

Server not connecting

• Verify your environment variables are set correctly
• Check that your Aha! API token is valid
• Ensure your product ID matches your Aha! product

API errors

• Verify your API token has the necessary permissions
• Check that the base URL is correct (no trailing slash)
• Ensure the product ID exists and you have access to it

License

MIT

TODO

• [ ] Implement Aha! API tools for features
• [ ] Implement Aha! API tools for ideas
• [ ] Implement Aha! API tools for releases
• [ ] Implement Aha! API tools for goals
• [ ] Implement caching for API responses
• [ ] Add more comprehensive error handling
• [ ] Expand test coverage
• [ ] Add API rate limiting

Made with Bob 🤖