npm package: @robyates/mcp-aha
Description: MCP (Model Context Protocol) server for Aha! integration - enables AI assistants to query and interact with Aha! product management data
Author: Rob Yates
Latest version: 1.0.2

# 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`

```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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
npm run build
npm test
```

4. Publish to npm:

```bash
# 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 🤖