Metadata-Version: 2.4
Name: aha-mcp
Version: 1.2.0
Summary: Model Context Protocol (MCP) server for the Aha! product management API
License-Expression: MIT
Project-URL: Homepage, https://github.com/DLTKFrancescoCarbone/aha_mcp
Project-URL: Repository, https://github.com/DLTKFrancescoCarbone/aha_mcp.git
Project-URL: Issues, https://github.com/DLTKFrancescoCarbone/aha_mcp/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27.0
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: python-dotenv<2,>=1.0.0

# fpcm-aha-mcp

Model Context Protocol (MCP) server for the [Aha!](https://www.aha.io) product management API. Lets AI assistants read and write ideas, features, epics, releases, initiatives, and products directly in your Aha! workspace.

Built with TypeScript — requires **Node.js 18+**, no Python needed.

## Quick start

```bash
npx -y fpcm-aha-mcp
```

Or install globally:

```bash
npm install -g fpcm-aha-mcp
```

## Configuration

The server reads credentials from environment variables (pass them via your MCP client config or a `.env` file in the working directory):

| Variable | Required | Description |
|---|---|---|
| `AHA_ACCOUNT_DOMAIN` | Yes | Your Aha! subdomain — the part before `.aha.io` (e.g. `mycompany`) |
| `AHA_API_KEY` | Yes | Your Aha! API key — Aha! → Settings → Account → API |
| `AHA_PRODUCT_ID` | No | Default product ID used when `product_id` is omitted from a tool call |

**Getting your API key:** log in to Aha!, go to **Settings → Account → API**, and generate or copy your key.

## Available tools

### Products
| Tool | Description |
|---|---|
| `list_products` | List all products (workspaces) in the account |
| `get_product` | Get a specific product by ID or reference prefix |

### Ideas
| Tool | Description |
|---|---|
| `search_ideas` | Search ideas in a product, with optional filters for release, epic, initiative, or workflow status. Supports fuzzy name matching. |
| `get_idea` | Get a specific idea by ID or reference number (e.g. `PRJ1-I-1`) |
| `create_idea` | Create a new idea in a product |
| `update_idea` | Update an existing idea |

### Features
| Tool | Description |
|---|---|
| `search_features` | Search features in a product, with optional filters for release, epic, or initiative. Supports fuzzy name matching. |
| `get_feature` | Get a specific feature by ID or reference number (e.g. `PRJ1-1`) |
| `create_feature` | Create a new feature in a release |
| `update_feature` | Update an existing feature |

### Epics
| Tool | Description |
|---|---|
| `search_epics` | Search epics in a product or release |
| `get_epic` | Get a specific epic by ID or reference number (e.g. `PRJ1-E-1`) |
| `create_epic` | Create a new epic in a release or product |
| `update_epic` | Update an existing epic |

### Releases
| Tool | Description |
|---|---|
| `search_releases` | Search releases in a product |
| `get_release` | Get a specific release by ID or reference number (e.g. `PRJ1-R-1`) |
| `create_release` | Create a new release in a product |
| `update_release` | Update an existing release |

### Initiatives
| Tool | Description |
|---|---|
| `list_initiatives` | List initiatives in a product |
| `get_initiative` | Get a specific initiative by ID or reference number (e.g. `PRJ1-S-1`) |

## Setup guide

See [SETUP.md](SETUP.md) for step-by-step instructions to add this MCP server to Claude Desktop or Claude Code.

## Publishing

Releases are published to [npmjs.com/package/fpcm-aha-mcp](https://www.npmjs.com/package/fpcm-aha-mcp) via GitHub Actions on every `v*` tag push using OIDC Trusted Publishing — no token secrets required. To publish a new version:

```bash
# bump version in package.json, then:
git tag v1.2.1
git push origin main --tags
```
