mcpField
A
Aha.io

Aha.io

ローカル
github.com生産性61 日前に更新
リポジトリ公式サイト

Aha.io について

Aha MCP Serverは、MCPクライアントをAha.ioのプロダクト管理データやワークフローに接続します。APIへのライブアクセスに加え、任意のローカルSQLite同期、セマンティック検索、同期やサーバー設定の管理機能を備えています。

主な機能

  1. 01Aha.ioレコードの検索と管理
  2. 02ライブAPIアクセスとSQLite同期
  3. 03埋め込みによるセマンティック検索
  4. 04バックグラウンド同期の制御
  5. 05実行時のサーバー設定ツール

活用シーン

  1. 01アイデアや製品レコードの検索
  2. 02セマンティック検索で関連レコードを発見
  3. 03オフライン利用に向けたAha.ioデータの同期
  4. 04同期ジョブの監視と管理

MCP 対応

ツールとリソースを通じてAha.ioのレコードやワークフロー操作をMCPクライアントに公開し、stdioとStreamable HTTPに対応します。同期、セマンティック検索、実行時設定のツールも提供します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

インストール方法は未掲載です

このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。

リポジトリ
パッケージ
npm@cedricziel/aha-mcp5.2.0
ocighcr.io/cedricziel/aha-mcp:5.2.0
mcpbaha-mcp-v5.2.0.mcpb5.2.0

ツール

50

掲載時のツール一覧 · 2 週間前に更新

このツールにパラメーターはありません。

詳細

Aha MCP サーバー

ライセンス：MIT TypeScript MCP

Aha.io のプロダクト管理プラットフォームとシームレスに連携する Model Context Protocol（MCP）サーバーです。オフラインでのデータベース同期、セマンティック検索向けのベクトル埋め込み、包括的なワークフロー自動化を備えています。

🔧 クライアントの設定

MCP レジストリ

このサーバーは公式 MCP レジストリに io.github.cedricziel/aha-mcpとして公開されています。そのため、レジストリを閲覧できるクライアントは、 以下の設定をせずにインストールできます。

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.cedricziel/aha-mcp"

レジストリに保存されるのはメタデータのみです。登録情報は、以下で説明する 3 つの成果物 （npm パッケージ、ghcr.io イメージ、.mcpb デスクトップ拡張機能）を参照しており、クライアントは 実行可能なものを選びます。いずれの場合も、サーバーにはAHA_COMPANYとAHA_TOKENが必要です。

Claude デスクトップ拡張機能（最も簡単）

最新リリースからaha-mcp-v<version>.mcpbをダウンロードし、 Claude Desktop で開くと、Aha.io のサブドメインと API トークンの入力を求められます。Node.js や Docker のセットアップ、JSON の手動編集は必要ありません。

この拡張機能は Aha.io に直接クエリを実行する 54 個のツールを提供するため、結果は常に最新で、 データがローカルに保存されることもありません。レコード横断検索には Aha.io 独自のインデックスを使用します。 詳しくは検索をご覧ください。

Claude Desktop の設定

この MCP サーバーを Claude Desktop で使用するには、claude_desktop_config.jsonに以下を追加します。

npx を使用する場合：

{
  "mcpServers": {
    "aha": {
      "command": "npx",
      "args": ["@cedricziel/aha-mcp"],
      "env": {
        "AHA_COMPANY": "your-company",
        "AHA_TOKEN": "your-api-token"
      }
    }
  }
}

Docker を使用する場合：

{
  "mcpServers": {
    "aha": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "AHA_COMPANY=your-company",
        "-e", "AHA_TOKEN=your-api-token",
        "ghcr.io/cedricziel/aha-mcp"
      ]
    }
  }
}

注： your-companyとyour-api-tokenを、実際の Aha.io サブドメインと API トークンに置き換えてください。

🚀 はじめに

npx ですぐに始める

グローバルにインストールせずに、npx を使って MCP サーバーを直接実行できます。

# 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
Docker ですぐに始める

Docker を使って MCP サーバーを実行することもできます。

# 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 Streamable HTTP mode (recommended for remote access)
docker run --rm -p 3001:3001 -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp --mode streamable-http
開発環境のセットアップ

  1. まだインストールしていない場合は、Bunをインストールします。

    curl -fsSL https://bun.sh/install | bash

  2. 依存関係をインストールします。

    bun install

  3. 環境変数を設定します。

    export AHA_COMPANY="your-company"  # Your Aha.io subdomain
export AHA_TOKEN="your-api-token"   # Your Aha.io API token

  4. サーバーを起動します。

    # Start the stdio server (for MCP clients - default)
bun start

# Or start with Streamable HTTP (recommended for remote access)
bun start -- --mode streamable-http

# Or start the HTTP server (legacy entry point)
bun run start:http

  5. 自動リロードを有効にして開発する場合：

    # Development mode with stdio
bun run dev

# Development mode with Streamable HTTP
bun run dev -- --mode streamable-http

# Development mode with HTTP (legacy)
bun run dev:http

🔌 Aha.io 連携

この MCP サーバーは、ライブ API アクセスとオフラインでのデータベース同期の両方を通じて、Aha.io とハイブリッド連携します。サーバーは Aha.io のデータを含むローカル SQLite データベースを自動的に維持し、より高速なクエリ、オフラインアクセス、高度なセマンティック検索機能を実現します。

アーキテクチャの概要
  • ハイブリッドデータアクセス：リアルタイムデータにはライブ API 呼び出しを使用し、パフォーマンス向上のためにオフライン SQLite データベースも使用します
  • バックグラウンド同期：Aha.io のエンティティをローカルデータベースに自動同期します
  • ベクトル埋め込み：sentence transformers と SQLite ベクトル拡張機能を使ったセマンティック検索
  • リアルタイムの進捗状況：詳細な進捗追跡機能を備えたバックグラウンドジョブの監視
  • 設定管理：サーバーを再起動せずに実行時設定を変更できます
設定

Aha.io 連携は複数の方法で設定できます。優先順位は次のとおりです。

  1. 環境変数（最優先）
  2. 設定ファイル（~/.aha-mcp-config.json）
  3. デフォルト値（優先順位が最も低い）
環境変数
  • AHA_COMPANY：Aha.io のサブドメイン（例：mycompany.aha.ioの場合はmycompany）
  • AHA_TOKEN：Aha.io の API トークン（API トークン認証用）
  • AHA_ACCESS_TOKEN：OAuth 2.0 アクセストークン（OAuth 認証用）
  • MCP_TRANSPORT_MODE：トランスポートモード（stdioまたはstreamable-http）
  • MCP_PORT：HTTP ベースのモードで使用するポート番号（デフォルト：3001）
  • MCP_HOST：HTTP ベースのモードで使用するホストアドレス（デフォルト：0.0.0.0）
  • MCP_AUTH_TOKEN：HTTP ベースのモードで使用する認証トークン（任意）
  • MCP_TOOL_RATE_LIMIT_PER_MINUTE：1 分あたりに許可されるツール呼び出し数（デフォルト：120、0で無効化）
トランスポートモード

サーバーは、次の2つのトランスポートモードに対応しています。

  1. stdio：MCP クライアント連携用の標準入出力モード（デフォルト）
  2. streamable-http：リモートクライアントおよびウェブクライアント向けの HTTP トランスポート（MCP protocol 2025-06-18）

使用例：

# Stdio mode (default)
aha-mcp

# Streamable HTTP mode
aha-mcp --mode streamable-http --port 3001

削除済み： sse トランスポートは MCP spec 2025-03-26 で非推奨となり、 削除されました。MCP_TRANSPORT_MODE=sse と --mode sse は、警告を表示して streamable-http にフォールバックするため、既存の設定でも引き続き起動できます。

認証（HTTP トランスポート）

streamable-http トランスポートでは、オプションで Bearer トークン認証を利用できます。

環境変数の設定
# Set authentication token
export MCP_AUTH_TOKEN="your-secure-token-here"

# Start server with authentication
aha-mcp --mode streamable-http --port 3001
クライアント認証

認証が有効な場合、クライアントは Authorization ヘッダーに Bearer トークンを含める必要があります。すべての MCP トラフィックは、単一の /mcp エンドポイントに送信されます。

curl -X POST \
     -H "Authorization: Bearer your-secure-token-here" \
     -H "Content-Type: application/json" \
     -H "MCP-Protocol-Version: 2025-06-18" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' \
     http://localhost:3001/mcp

ほとんどの場合、生の HTTP を直接使うのではなく、MCP クライアントライブラリを使用してください。トランスポートの構築時に、トークンを Authorization ヘッダーとして渡します。

セキュリティに関する注意事項
  • オプトイン： 認証は任意です。MCP_AUTH_TOKEN が設定されていない場合、すべてのリクエストが許可されます。
  • トークンのセキュリティ： 強力でランダムに生成されたトークン（8文字以上）を使用してください。
  • HTTPS： 本番環境では、通信中のトークンを保護するため、必ず HTTPS を使用してください。
  • トークンの保存： トークンは設定ファイル内で難読化（Base64 エンコード）されますが、機密データとして扱ってください。
認証状態の確認
curl http://localhost:3001/

# Response includes:
# {
#   "authentication": {
#     "enabled": true,
#     "type": "Bearer token"
#   }
# }
設定管理ツール

サーバーは、設定管理用のMCPツールを3つ提供しています。

  1. configure_server：実行時にサーバー設定を更新します
  2. get_server_config：現在の設定と検証ステータスを確認します
  3. test_configuration：現在の設定で API 接続をテストします

これらのツールを使うと、サーバーを再起動せずに設定を管理できます。Aha.io のアカウントを切り替えたり、認証情報を更新したりするのも簡単です。

データベースの同期

サーバーは、パフォーマンスの向上とオフラインアクセスのため、Aha.io のデータをローカルの SQLite データベースに保持します。

同期管理ツール
  • aha_sync_start：指定したエンティティタイプのバックグラウンド同期を開始します
  • aha_sync_status：同期ジョブの状態と進行状況を確認します
  • aha_sync_stop：実行中の同期ジョブを停止します
  • aha_sync_pause：同期ジョブを一時停止します（後で再開できます）
  • aha_sync_resume：一時停止中の同期ジョブを再開します
  • aha_sync_history：同期処理の詳細な履歴を確認します
  • aha_sync_health：同期サービス全体のヘルスステータスを取得します
  • aha_database_health：データベースの接続状態と統計情報を確認します
  • aha_database_cleanup：古い同期ジョブを整理し、データベースを最適化します
同期機能
  • エンティティタイプ： フィーチャー、製品、アイデア、エピック、イニシアチブ、リリース、目標、ユーザー、コメントを同期します
  • 進行状況の追跡： 詳細な統計情報を含む、リアルタイムの進行状況を更新します
  • エラー処理： 包括的なエラーログ記録と復旧メカニズムを備えています
  • バッチ処理： 最適なパフォーマンスを得るため、バッチサイズを設定できます
  • 差分更新： updatedSince フィルタリングに対応し、最近の変更のみを同期できます
  • 同時操作： 複数の同期ジョブを同時に実行できます
同期ワークフローの例
# 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
セマンティック検索と埋め込み

サーバーには、ベクトル埋め込みを使用した高度なセマンティック検索機能が含まれています。

埋め込み管理ツール
  • aha_generate_embeddings：エンティティのテキストコンテンツからベクトル埋め込みを生成します
  • aha_embedding_status：埋め込み生成ジョブの状態を確認します
  • aha_semantic_search：自然言語のクエリを使ってエンティティを検索します
  • aha_generate_entity_embedding：特定のエンティティの埋め込みを生成します
  • aha_find_similar：指定したエンティティに類似するエンティティを検索します
  • aha_pause_embeddings：埋め込み生成ジョブを一時停止します
  • aha_stop_embeddings：埋め込み生成ジョブを停止します
セマンティック検索機能
  • ベクトルストレージ：sqlite-vec 拡張機能を使用して SQLite に埋め込みを保存します
  • 複数のモデル：さまざまな埋め込みモデルに対応しています（デフォルト：all-MiniLM-L6-v2）
  • 類似度検索：しきい値を設定できるコサイン類似度検索
  • エンティティ横断検索：異なるエンティティタイプ間で類似コンテンツを検索します
  • リアルタイム生成：進捗を追跡しながら、バックグラウンドで埋め込みを生成します
埋め込みワークフローの例
# 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
利用可能なリソース

破壊的変更： 多くのコレクションリソース（aha_features のような簡素なインデックスリストや、aha_ideas のような少数のスカラー列を持つリソース）は、JSON 配列の代わりに text/markdown を返すようになりました。レコードのタイプに応じて、リンクのリストまたはテーブルを返します。これらのコレクションの内容を JSON として解析していた場合は、変更が必要です。より豊富なネストデータを含むコレクション（aha_goals、aha_initiatives、コメントリソースなど）は影響を受けません。また、単一レコードのリソース（aha://feature/{id} など）はすべて、引き続き application/json を返します。

個別エンティティリソース
  • aha_idea：aha://idea/{id} を使用して個別のアイデアにアクセスします
  • aha_feature：aha://feature/{id} を使用して個別の機能にアクセスします
  • aha_user：aha://user/{id} を使用して個別のユーザーにアクセスします
  • aha_epic：aha://epic/{id} を使用して個別のエピックにアクセスします
  • aha_product：aha://product/{id} を使用して個別の製品にアクセスします
  • aha_initiative：aha://initiative/{id} を使用して個別のイニシアチブにアクセスします
  • aha_requirement：aha://requirement/{id} を使用して個別の要件にアクセスします
  • aha_competitor：aha://competitor/{id} を使用して個別の競合他社にアクセスします
  • aha_todo：aha://todo/{id} を使用して個別のToDoにアクセスします
コレクションリソース
  • aha_features：aha://features?query=...&tag=... を使用して、任意の条件で機能を絞り込んで一覧表示します
  • aha_users：aha://users を使用してすべてのユーザーを一覧表示します
  • aha_epics：aha://epics/{product_id} を使用して、製品のエピックを一覧表示します
  • aha_products：aha://products?updatedSince=... を使用してすべての製品を一覧表示します
  • aha_initiatives：aha://initiatives?query=...&onlyActive=true を使用してすべてのイニシアチブを一覧表示します
  • aha_ideas：aha://ideas?query=...&status=...&category=... を使用してすべてのアイデアをグローバルに一覧表示します
  • aha_ideas_by_product：aha://ideas/{product_id}?query=...&spam=false&sort=recent を使用して、製品のアイデアを一覧表示します
  • aha_competitors：aha://competitors/{product_id} を使用して、製品の競合他社を一覧表示します
  • aha_product_releases：aha://releases/{product_id}?query=...&status=... を使用して、製品のリリースを一覧表示します
  • aha_initiative_epics：aha://initiative/{initiative_id}/epics を使用して、イニシアチブのエピックを一覧表示します
コメントリソース
  • aha_feature_comments：aha://comments/feature/{feature_id} を使用して、機能のコメントにアクセスします
  • aha_epic_comments：aha://comments/epic/{epic_id} を使用して、エピックのコメントにアクセスします
  • aha_idea_comments：aha://comments/idea/{idea_id} を使用して、アイデアの内部コメントにアクセスします
  • aha_idea_portal_comments：aha://idea-comments/{idea_id} を使用して、アイデアのideas-portalコメントにアクセスします。上記とは異なるレコードで、顧客が書いたものも含まれます
  • aha_initiative_comments：aha://comments/initiative/{initiative_id} を使用して、イニシアチブのコメントにアクセスします
  • aha_product_comments：aha://comments/product/{product_id} を使用して、製品のコメントにアクセスします
  • aha_goal_comments：aha://comments/goal/{goal_id} を使用して、目標のコメントにアクセスします
  • aha_release_comments：aha://comments/release/{release_id} を使用して、リリースのコメントにアクセスします
  • aha_release_phase_comments：aha://comments/release-phase/{release_phase_id} を使用して、リリースフェーズのコメントにアクセスします
  • aha_requirement_comments：aha://comments/requirement/{requirement_id} を使用して、要件のコメントにアクセスします
  • aha_todo_comments：aha://comments/todo/{todo_id} を使用して、ToDoのコメントにアクセスします
目標リソース
  • aha_goal：aha://goal/{goal_id} を使用して個別の目標にアクセスします
  • aha_goals：aha://goals を使用してすべての目標を一覧表示します
  • aha_goal_epics：aha://goal/{goal_id}/epics を使用して目標に関連付けられたエピックにアクセスします
  • aha_goal_key_results：aha://goal/{goal_id}/key_results を使用して目標の主要な成果にアクセスします
  • aha_key_result：aha://key_result/{id} を使用して個別の主要な成果にアクセスします
リリースリソース
  • aha_release：aha://release/{release_id} を使用して個別のリリースにアクセスします
  • aha_releases：aha://releases を使用してすべてのリリースを一覧表示します
  • aha_release_features：aha://release/{release_id}/features を使用してリリースに関連付けられた機能にアクセスします
  • aha_release_epics：aha://release/{release_id}/epics を使用してリリースに関連付けられたエピックにアクセスします
  • aha_release_phase：aha://release-phase/{release_phase_id} を使用して個別のリリースフェーズにアクセスします
  • aha_release_phases：aha://release-phases を使用してすべてのリリースフェーズを一覧表示します
カスタムフィールドリソース
  • aha_custom_fields：aha://custom-fields を使用してすべてのカスタムフィールド定義を一覧表示します
  • aha_custom_field_options：aha://custom-field/{custom_field_id}/options を使用してカスタムフィールドの選択肢にアクセスします
リソース URI の例
# 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&[email protected] # 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&[email protected] # 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/feature/PRJ1-123   # Get comments for feature
aha://comments/epic/EPIC-123      # Get comments for epic
aha://comments/idea/IDEA-456      # Get an idea's internal comments
aha://idea-comments/IDEA-456      # Get an idea's ideas-portal comments
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
aha://goal/GOAL-456/key_results   # Get key results for goal
aha://key_result/PRJ1-G-3-KR-1    # Get specific key result

# 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
利用可能なツール

注：一覧表示操作は MCP リソースを通じて行います。ツールは、検索、単一レコードの読み取り、書き込み操作、および関連付けの管理を担当します。

レコード読み取りツール
  • aha_get_feature：ワークフローのステータス、リリース、担当者、タグ、スコア、カスタムフィールドの値など、1 件の機能を読み取ります
  • aha_get_epic：1 件のエピックを読み取ります
  • aha_get_idea：1 件のアイデアを読み取ります
  • aha_get_initiative：1 件のイニシアチブを読み取ります
  • aha_get_release：1 件のリリースを読み取ります
  • aha_get_goal：期間、進捗の情報源、成功指標、主要な成果の概要など、1 件の目標を読み取ります
  • aha_get_key_result：ステータス、開始時・現在・目標の指標など、1 件の主要な成果を読み取ります

これらはレコード全体を structuredContent として返します。aha://feature/{id} などですでに提供されている内容と重複しますが、意図的なものです。リソースをモデルに表示するかどうかはクライアントが自由に選べますが、表示しないクライアントもあります。その場合、ここにある読み取り手段がすべて利用できず、書き込みツールは置き換えようとしている内容を確認できません。aha_search はレコードごとのフィールドを返せないため、代わりにはなりません。

コレクション読み取りツール
  • aha_list_release_features：リリースに割り当てられた機能を一覧表示します。各機能へのリンクと、リリースの Aha における合計件数も含みます
  • aha_list_release_epics：リリースに割り当てられたエピックを一覧表示します。各エピックへのリンクと、リリースの Aha における合計件数も含みます
  • aha_list_key_results：目標の主要な成果を、ステータス、進捗、指標とともに一覧表示します
  • aha_list_comments：アイデアの場合は両方のストリームを含め、レコード上のコメントを一覧表示します

リリースを列挙する唯一の方法が、この 2 つのリリースツールです。aha_search は関連度順に結果を返し、ヒットしたレコードがリリースに属するかどうかを返さず、スコープ内のすべてのレコードを要求することもできません。そのため、検索結果から組み立てたリリース一覧は不完全ですが、そのことを示す情報は含まれません。リリースがすべてのワークスペースで同じ方法で編成されているわけではないため、両方の種類を用意しています。エピックで計画されたリリースは、機能ツールには表示されません。各ツールは 1 ページあたり 200 件のレコードを要求します（Aha の既定値は機能が 30 件で、エピックのルートでは測定されていないため、ツールはその値に依存しません）。また、常に Aha のページネーションブロックを返すため、一覧が完全なものか、それともさらに続く一覧の先頭部分かを呼び出し側で判別できます。Aha はこれらのエンドポイントでは識別情報フィールドのみを返すため、個々のレコードの状態を確認するには aha_get_feature または aha_get_epic を使用してください。

書き込み操作ツール
  • aha_create_feature_comment：機能にコメントを作成します
  • aha_create_initiative_in_product：特定の製品内にイニシアチブを作成します
コメントツール
  • aha_list_comments：コメントを読み取ります。アイデアとして、内部用とポータル用のストリームを分ける方法があります
  • aha_create_comment：対応するレコードに内部コメントを追加します
  • aha_update_comment：コメント ID を使って内部コメントの本文を置き換えます
  • aha_delete_comment：コメント ID を使って内部コメントを削除します
  • aha_create_idea_portal_comment：表示設定を明示してポータルコメントを追加します
  • aha_delete_idea_portal_comment：アイデア ID とコメント ID を使ってポータルコメントを削除します

コメントの body には、<p>A <strong>formatted</strong> reply.</p> のような生の HTML、 またはプレーンテキストを指定できます。Markdown は変換されません。タグを &lt;p&gt; のようにエスケープしたり、コードフェンスで囲んだりせず、HTML をそのまま送信してください。 サーバーは Aha に送信された本文を保持します。短いテキストプレビューではタグが削除されますが、 structuredContent には返された本文が保持されます。aha_list_comments のコメントの source を使って、 内部用またはポータル用のツールを選択してください。Aha のドキュメントでは更新エンドポイントが スパムと表示設定の変更にのみ対応しているため、ポータルコメントの本文編集は公開されていません。

フィーチャーの CRUD ツール
  • aha_create_feature：特定のリリース内にフィーチャーを作成します
  • aha_update_feature：フィーチャーを更新します
  • aha_delete_feature：フィーチャーを削除します
  • aha_update_feature_progress：フィーチャーの進捗を更新します
  • aha_update_feature_score：フィーチャーのスコアを更新します
  • aha_update_feature_custom_fields：フィーチャーのカスタムフィールドを更新します
エピックの CRUD ツール
  • aha_update_epic：エピックを更新します
  • aha_delete_epic：エピックを削除します
  • aha_create_epic_in_product：特定のプロダクト内にエピックを作成します
  • aha_create_epic_in_release：特定のリリース内にエピックを作成します
アイデアの CRUD ツール
  • aha_create_idea：プロダクトにアイデアを作成します
  • aha_create_idea_with_category：カテゴリを指定してアイデアを作成します
  • aha_create_idea_with_score：スコアを指定してアイデアを作成します
  • aha_update_idea：アイデアのワークフローのステータスやその他のフィールドを更新します
  • aha_delete_idea：アイデアを削除します

更新する前に、aha_get_idea でアイデアを読み取ってください。ステータス名はワークスペースによって異なるため、 意図したステータスを正確に指定してください。例：

{
  "ideaId": "PRJ1-I-7",
  "ideaData": { "idea": { "workflow_status": "Product Evaluating" } }
}

これを aha_update_idea に渡します。ideaData.idea で省略されたフィールドは変更されません。

ゴールと主要な成果のツール（OKR）
  • aha_create_goal：ワークスペースにゴール（目標）を作成します
  • aha_update_goal：ゴールの名前、説明、成功指標、ステータス、期間、進捗を更新します
  • aha_delete_goal：ゴールと、それに属する主要な成果を削除します
  • aha_list_key_results：ステータス、進捗、指標とともに、ゴールの主要な成果を一覧表示します
  • aha_create_key_result：ゴールの下に主要な成果を作成します
  • aha_update_key_result：主要な成果のステータス、および開始時、現在、目標の指標を更新します
  • aha_delete_key_result：主要な成果を削除します

これらには、実際のアカウントで確認した、API の他の機能とは異なる点が 3 つあります。

  • ゴールの作成と削除はワークスペース単位です。 Aha が提供するルートは POST /products/{id}/goals と DELETE /products/{id}/goals/{id} のみなので、どちらのツールにもワークスペース ID が必要です。 aha_get_goal はこれを product_id として返します。更新には不要です。
  • 主要な成果には url がありません。 他のすべてのレコードタイプと異なり、単独のレコードには url も resource もありません。そのため、各ツールが返す aha://key_result/{id} リソースリンクが、 クライアントがたどれる唯一の参照先です。
  • ゴールにはトップレベルのワークフローステータスがありません。 ステータスは success_metric.workflow_status にあり、 Aha の UI でゴールのステータスとして表示されます。
競合管理ツール
  • aha_create_competitor：プロダクトに競合を作成します
  • aha_update_competitor：競合を更新します
  • aha_delete_competitor：競合を削除します
ポータル連携ツール
  • aha_create_idea_by_portal_user：ポータルユーザーとしてアイデアを作成します
  • aha_create_idea_with_portal_settings：拡張ポータル設定でアイデアを作成します
関係管理ツール
  • aha_associate_feature_with_epic：フィーチャーをエピックに関連付けます
  • aha_move_feature_to_release：フィーチャーを別のリリースに移動します
  • aha_associate_feature_with_goals：フィーチャーを複数の目標に関連付けます
  • aha_update_feature_tags：フィーチャーのタグを更新します

注：設計上、読み取り操作は両方のインターフェースで利用できます。

  • リソースは、URI パラメーターによるフィルタリング、リストおよび単一レコードを含む、あらゆるエンティティタイプの全読み取り機能をカバーします
  • ツールは、書き込み（作成／更新／削除）、関係管理（関連付け／移動）、検索、および書き込みの頻度が最も高い 5 つのタイプを対象とした単一レコードの読み取りをカバーします

この重複は意図的なものです。リソースはより豊富な読み取り機能を提供しますが、MCP 仕様では、モデルにリソースを公開するかどうかは各クライアントに委ねられており、ツールのみを扱うクライアントも一般的です。書き込みツールがあるタイプについて読み取りをツール経由でも可能にしておくことで、エージェントが確認できないフィールドを変更してしまうのを防ぎます。

🚀 フェーズ 8 - 完全な CRUD 操作と高度な機能

MCP サーバーは、完全な CRUD 操作、ポータル統合、高度なワークフロー機能を備え、Aha.io エンティティの包括的なライフサイクル管理を提供するようになりました。

フェーズ 8A - コア CRUD 操作（18 ツール）

フィーチャー管理（6 ツール）

  • aha_create_feature：リリース内にフィーチャーを作成します
  • aha_update_feature：既存のフィーチャーを更新します
  • aha_delete_feature：フィーチャーを削除します
  • aha_update_feature_progress：フィーチャーの進捗状況を更新します（0～100%）
  • aha_update_feature_score：フィーチャーのスコアを更新します
  • aha_update_feature_custom_fields：フィーチャーのカスタムフィールドを更新します

エピック管理（2 ツール）

  • aha_update_epic：既存のエピックを更新します
  • aha_delete_epic：エピックを削除します

アイデア管理（5 ツール）

  • aha_create_idea：プロダクト内にアイデアを作成します
  • aha_create_idea_with_category：カテゴリーを指定してアイデアを作成します
  • aha_create_idea_with_score：スコアを指定してアイデアを作成します
  • aha_update_idea：アイデアのワークフローのステータスやその他のフィールドを更新します
  • aha_delete_idea：アイデアを削除します
フェーズ 8B - 競合管理（3 ツール）

競合管理（3 ツール）

  • aha_create_competitor：プロダクト内に競合を作成します
  • aha_update_competitor：既存の競合を更新します
  • aha_delete_competitor：競合を削除します

注：イニシアチブデータへのアクセスは、読み取り操作と書き込み操作をより明確に分離するため、MCP リソース（aha_initiative、aha_initiatives、aha_initiative_comments、aha_initiative_epics）を通じて行うようになりました。

フェーズ 8C - ポータル統合と高度な機能（2 ツール）

ポータル統合

  • aha_create_idea_by_portal_user：ポータルユーザーとしてアイデアを作成します
  • aha_create_idea_with_portal_settings：ポータル設定を指定してアイデアを作成します
強化されたフィルタリングとリソース
  • イニシアチブのフィルタリング：query、updatedSince、assignedToUser、onlyActive パラメーターを追加して強化しました
  • ポータルの設定：skip_portal および submitted_idea_portal_id 設定をサポートします
  • 包括的なエンティティ対応：フィーチャー、エピック、アイデア、競合の完全な CRUD 操作に対応します
技術的な成果
  • 54 個の MCP ツールが、すべて Aha.io に直接クエリを実行します。ローカル状態は保持しません。
  • エンティティ一式を網羅する17 個の MCP リソースと、テンプレート化されたリソース URI
  • 17 個のドメイン固有プロンプト（ワークフローの自動化）
  • OKR（目標と主要な成果）を含む、ライフサイクル全体の管理に対応する36 個の基本的な CRUD および書き込み操作ツール
  • Aha 独自のインデックスを利用した、20 種類のレコードを対象とするレコード横断検索
  • リソースを表示しないクライアントでも、書き込み後にレコードの現在の状態を確認できる7 個の単一レコード読み取りツール
  • Aha がサポートするすべてのレコードタイプのコメントを読み取り・書き込みできます。アイデアのアイデアポータルでの会話は、独立したストリームとして処理します。
  • 目標と主要な成果の CRUDにより、Aha UI を介さずサーバーを通じて四半期ごとの OKR サイクルを実行できます。
  • 実行時設定用の5 個のサーバー設定ツール
  • 534 個のテストが合格し、サービスを包括的にカバーしています。
  • ネイティブ依存関係はありません。Node が動作する場所ならどこでもサーバーを実行できます。
  • 適切な Zod スキーマ検証を含む包括的なエラー処理

🔍 検索

aha_search は GraphQL API（POST /api/v2/graphql、searchDocuments）を通じて、Aha.io 独自の検索インデックスにクエリを実行します。ローカルには何もキャッシュしないため、結果は常に最新で、ネイティブ依存関係も書き込み可能なストレージも必要ありません。

// Everything matching "alerting", any record type
{ "query": "alerting" }

// Ideas only, within one workspace
{ "query": "alerting", "recordTypes": ["Idea"], "workspaceId": "7387509120724661690" }

// Sweep a workspace broadly: alternatives, because there is no match-all
{ "query": "a* OR e* OR i* OR o* OR u*", "recordTypes": ["Idea"], "workspaceId": "7387509120724661690" }

検索対象： レコード名と説明です。コメント本文も検索対象となり、親レコードへのリンクを含む Comment のヒットとして表示されます。

クエリ構文： 前方一致の term*、AND／OR／NOT、および "quoted phrases" が使用できます。

すべてに一致するクエリはありません。 * 単独の検索は拒否されます。Aha は単独の * に対して任意のサブセットを返し、workspaceId と組み合わせると何も返しません。空のワークスペースのように見える空の結果になります。ワークスペースを検索するのではなく、検索語を指定するか、リストリソース（aha://features、aha://ideas/{product_id}）を使って列挙してください。

ヒットに含まれる情報： 名前、タイプ、reference_num、内部 ID、ワークスペース、絶対 URL、updated_at です。アイデアのヒットにはポータルの votes と endorsements も含まれ、スコアを付けられるタイプには Aha.io の score も含まれるため、2 回目の呼び出しをせずに需要に基づいてアイデアを順位付けできます。リソースとして読み取り可能なタイプ（feature、epic、idea、initiative、goal、key result、release、requirement、competitor）のヒットには resource_link が含まれます。それ以外のタイプには URL からアクセスできます。

参照番号は省略せずに指定してください。 ワークスペースのプレフィックスも参照番号の一部です。IDEASVOC-I-9930 はアイデアを識別しますが、I-9930 は何も識別しません。Aha は短縮形に対して 404 を返すため、入力ミスではなくレコードが存在しないように見えます。

返されない情報： ワークフローのステータス、リリースへの所属、担当者、カスタムフィールドの値です。これらを確認するには、レコード自体を読み取ってください。

{ "featureId": "PRJ1-123" }   // aha_get_feature — full record, including custom fields

レコードタイプ（recordTypes。省略するとすべてを検索します）：

BusinessModel · Comment · Competitor · Epic · Feature · Goal · Idea · IdeaOrganization
IdeaTheme · IdeaUser · Initiative · KeyResult · Page · Persona · Project · Release
ReleasePhase · Requirement · StrategicPositioning · Task

ページネーション： perPage は 10～200 を指定でき、デフォルトは 20 です。10 未満を指定すると、Aha は 10 に引き上げます。total_count は 10,000 件でカウントを停止し、その場合は total_count_is_capped: true と報告されます。

ご自身のアカウントとトークンでアクセスできる範囲を確認するには、scripts/check-graphql.ts を使用してください。

AHA_COMPANY=mycompany AHA_TOKEN=... bun run scripts/check-graphql.ts
ローカルの埋め込みを使わない理由

以前のバージョンでは Aha のデータを SQLite に同期し、ローカルの「セマンティック検索」で結果を順位付けしていました。この機能は削除されました。埋め込み関数は文字コードを Math.sin() でハッシュしていたため、意味的な信号を持たず、類似度スコアも解釈できませんでした。また、ネイティブの sqlite3 モジュールと書き込み可能なデータディレクトリが必要だったため、パッケージ化されたインストールで問題が発生していました。Aha のサーバー側インデックスはキーワードベースですが、実際に機能し、常に最新で、こうした仕組みは一切不要です。

Aha は https://<yourcompany>.aha.io/api/v1/mcp に独自の MCP サーバーもホストしています。

🛠️ カスタムツールとリソースの追加

MCP サーバーにカスタムツール、リソース、またはプロンプトを追加する場合：

  1. すべてのリソース名、ツール名、プロンプト名では、ハイフン（-）ではなくアンダースコア（_）を使用してください

    // 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. この命名規則により、Cursor や MCP サーバーと連携するその他の AI ツールとの互換性が確保されます

🐳 Docker の使用方法

Docker イメージ

Aha MCP サーバーは、GitHub Container Registry で Docker イメージとして提供されています：

  • GitHub Container Registry：ghcr.io/cedricziel/aha-mcp
Docker での実行
基本的な使用方法
# 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 Streamable HTTP mode
docker run --rm \
  -p 3001:3001 \
  -e AHA_COMPANY="your-company" \
  -e AHA_TOKEN="your-api-token" \
  ghcr.io/cedricziel/aha-mcp --mode streamable-http

# Run in Streamable HTTP 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 streamable-http
設定の永続化

実行間で設定を永続化するには：

# 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
Docker Compose の使用

リポジトリには、簡単にセットアップできる docker-compose.yml ファイルが含まれています：

# 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 Streamable HTTP mode
docker-compose --profile http up

# Run in detached mode
docker-compose --profile http up -d

.env ファイルの例：

AHA_COMPANY=mycompany
AHA_TOKEN=your-api-token-here
MCP_AUTH_TOKEN=your-secure-token-here
Docker 環境変数

Docker イメージでは、npm パッケージと同じ環境変数をすべて使用できます：

変数説明デフォルト
AHA_COMPANYAha.io の会社サブドメイン-
AHA_TOKENAha.io API トークン-
MCP_TRANSPORT_MODEトランスポートモード（stdio または streamable-http）stdio
MCP_PORTstreamable-http モードのポート3001
MCP_HOSTstreamable-http モードのホスト0.0.0.0
MCP_AUTH_TOKENstreamable-http トランスポート用のベアラートークン-
MCP_TOOL_RATE_LIMIT_PER_MINUTE1 分あたりに許可されるツール呼び出し数（0 で無効）120
MCP_CONFIG_DIR設定ディレクトリ/home/mcp/.config
ヘルスチェック

Docker イメージには、streamable-http モード用のヘルスチェックが含まれています：

# Check if the HTTP server is healthy
curl http://localhost:3001/health

# Get detailed server status
curl http://localhost:3001/status
ソースからのビルド

Docker イメージをローカルでビルドするには：

# Build the image
npm run docker:build

# Test the image
npm run docker:test

# Run the image
npm run docker:run

# Run in Streamable HTTP mode
npm run docker:run:http
マルチアーキテクチャ対応

Docker イメージは、複数のアーキテクチャ向けにビルドされています：

  • linux/amd64（x86_64）
  • linux/arm64（Apple Silicon、ARM64）

Docker は、お使いのプラットフォームに適したイメージを自動的に取得します。

Docker のセキュリティ

Docker イメージでは、セキュリティのベストプラクティスに従っています：

  • 非 root ユーザー（mcp）として実行
  • 最小構成の Alpine Linux ベースイメージを使用
  • 適切なシグナル処理のために tini を含む
  • 設定ディレクトリに適切な権限を設定
  • マルチステージビルドを使用して攻撃対象領域を縮小

🏗️ 開発

コミットのガイドライン

このプロジェクトでは、コミットメッセージの一貫性を確保し、バージョン管理を自動化するために、Conventional Commits を使用しています。

コミットメッセージの形式：

<type>(<scope>): <subject>

<body>

<footer>

種類：

  • feat：新機能
  • fix：バグ修正
  • docs：ドキュメントのみの変更
  • style：コードの意味に影響しない変更
  • refactor：バグ修正や機能追加を伴わないコード変更
  • perf：パフォーマンスを改善するコード変更
  • test：不足しているテストの追加、または既存のテストの修正
  • build：ビルドシステムまたは外部依存関係に影響する変更
  • ci：CI 設定ファイルおよびスクリプトの変更
  • chore：src ファイルや test ファイルを変更しないその他の変更

例：

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)

コミットメッセージは、各コミット時と CI で commitlint を使用して検証されます。

テスト
ローカルでのテスト

テストスイートを実行します：

# Run all tests
bun test

# Run tests in watch mode
bun run test:watch

# Run tests with coverage
bun test --coverage
Docker でのテスト

Docker 環境には、テストに必要な依存関係がすべて含まれています：

# 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
データベース機能のテスト

Docker 環境には、以下が含まれています：

  • SQLite3：中核となるデータベース機能
  • Node.js の sqlite パッケージ：データベースドライバーとユーティリティ
  • 適切なフォールバック：テスト環境では sqlite-vec 拡張機能の警告を抑制
  • 一時データベース：各テストで分離された一時データベースファイルを使用
  • 適切なクリーンアップ：テスト後にデータベース接続とファイルをクリーンアップ
Docker 環境の確認
# 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

Docker 環境では、以下を含むテストスイート全体を実行できます：

  • すべてのサービスにわたる194 件以上のテストケース
  • データベースサービスのテスト（25 件のテストケース）
  • バックグラウンド同期サービスのテスト（16 件のテストケース）
  • MCP アクセシビリティのテスト（172 件のテストケース）
  • テストモードではSQLite 拡張機能の警告が自動的に抑制されます
ビルド

本番環境向けにビルドするには：

# Build stdio server
bun run build

# Build HTTP server
bun run build:http
公開
自動リリースプロセス（推奨）

このプロジェクトでは、バージョン管理と公開の自動化に release-please を使用しています。

  1. Conventional Commits 形式で変更を加えます。

    • 新機能には feat: を使用します（マイナーバージョンが上がります）。
    • バグ修正には fix: を使用します（パッチバージョンが上がります）。
    • 破壊的変更には feat!: または fix!: を使用します（メジャーバージョンが上がります）。

  2. main にプッシュします。release-please が自動的に次の処理を行います。

    • バージョンと変更履歴を更新したリリース PR を作成します。
    • リリース PR がマージされると、GitHub リリースを作成します。
    • リリースによって、npm、ghcr.io、および MCP Registry への公開が自動的に実行されます。

    レジストリのジョブは最後に実行されます。レジストリでは、すでに公開済みのアーティファクトを読み取って所有権を確認するためです。対象となるのは、npm パッケージ内の mcpName、イメージの io.modelcontextprotocol.server.name ラベル、およびリリースに添付された .mcpb アセットの SHA-256 です。GitHub OIDC で認証するため、レジストリの認証情報をどこにも保存する必要はありません。

手動での公開

パッケージを手動で公開するには：

# 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

注：自動公開を有効にするには、リポジトリの設定で NPM_TOKEN シークレットを設定してください。

📚 ドキュメント

  • CLAUDE.md - このリポジトリで作業する Claude Code 向けの開発ガイダンス
  • MCP のドキュメント - Model Context Protocol の公式ドキュメント

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

コメント

Markdown 対応

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。