Metadata-Version: 2.4
Name: aha-mcp
Version: 1.4.2
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, products, **pages (notes)**, **record links**, and custom-field metadata directly in your Aha! workspace.

**Runtimes:** the published [npm](https://www.npmjs.com/package/fpcm-aha-mcp) package is **Node.js 18+** (TypeScript compiled to `dist/`). This repository also ships a **Python** server (`aha_mcp`) with the same tool surface — use either one. See [SETUP.md](SETUP.md) for Node vs Python and local clone paths.

## 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. Optional **`sort`**: `recent`, `trending`, or `popular` (for “top voted” style lists, combine with **`fields`** such as `endorsements_count`). Pass-through filters: **`created_since`**, **`created_before`**, **`updated_since`**, **`tag`**, **`user_id`**, **`idea_user_id`**. **`limit`** is per page and capped at **200** (Aha! maximum). |
| `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`) |

### Custom fields and layout

| Tool | Description |
|---|---|
| `list_custom_field_definitions` | List account-wide custom field definitions (optional filters; paginate for full scans) |
| `list_custom_field_options` | List allowed values for a picklist-style custom field |
| `get_custom_layout_for_product_record` | Get the custom layout / fields for a record type in a product |
| `export_product_seed_bundle` | Export a structured seed bundle for a product (for backups or migrations) |
| `invalidate_metadata_cache` | Clear the server-side metadata cache after Aha! configuration changes |

### Pages (Notes)

In the Aha! REST API, workspace **Notes** are **`pages`**.

| Tool | Description |
|---|---|
| `list_pages` | List or search pages for a product |
| `get_page` | Get one page by id or reference key |
| `create_page` | Create a page under a product |
| `update_page` | Update a page (partial updates supported) |
| `delete_page` | Delete a page |

### Record links

| Tool | Description |
|---|---|
| `list_page_record_links` | List links attached to a page (optionally include parent/child direction) |
| `create_page_record_link` | Link a page to another record (feature, idea, epic, release, etc.) with an Aha! `link_type` |
| `delete_record_link` | Remove a link by its **record link id** (from `list_page_record_links`), not by page or feature id |

## Setup guide

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

## Developing from a clone

- **Node:** `npm install` and `npm run build` (required before `npm start` or pointing MCP at `dist/index.js`).
- **Python:** install the package in editable mode (`pip install -e .` from the repo root), then run `python -m aha_mcp` (or the `aha-mcp` console script). Dependencies are listed in `pyproject.toml`.
- **Tests:** `python -m unittest discover -s tests -p "test_*.py"` covers shared API behavior (e.g. idea search query parameters). **`scripts/verify_step0_popular_sort.py`** is an optional live check against your Aha! account (`AHA_API_KEY`, `AHA_ACCOUNT_DOMAIN`) to sanity-check `sort=popular` ordering.

## 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. The published version is always the `version` field in `package.json` (keep it in sync with the tag, e.g. `1.4.2` → tag `v1.4.2`). To publish a new version:

```bash
# bump version in package.json and package-lock.json (root), then:
git tag v1.4.2
git push origin main --tags
```
