Ava

Ava は、進捗の共有やチームとのコミュニケーションが苦手な人でも、AI が自動で外部化と情報共有を手伝ってくれる世界をつくるプロジェクトです。

作業に集中しすぎて進捗報告を忘れてしまう、詰まっているのになかなか相談できない、定期的な進捗確認ミーティングでコーディングが中断される。こんな悩みはありませんか？

Ava ができること

自動で進捗をSlackに報告

Claude Code や Cursor などの AI コーディングエージェントで作業を進めると、自動的に Slack の指定チャンネルに進捗が投稿されます。

• タスク開始: 何に取り組み始めたかを報告
• 進捗更新: 作業の進み具合を随時共有
• ブロッキング報告: 困っていることを自動で相談
• 休止・再開: 別タスク優先時や中断時の状況を共有
• 完了報告: 完了内容を共有

プライバシーに配慮した設計

Slack に送られるのは、抽象的なサマリのみです。コードの全文、秘密鍵やトークン、エラーログの詳細は送信されません。送信されるのは作業内容の要約、ブロッキング・休止の理由の概要、完了サマリのみです。

自分でコントロールできる自動化

いつ報告するか、どの粒度で話すか、何を共有するかは自然言語でコントロールできます。完全に自動化されたツールではなく、プロンプト次第でルーチンも自分でコントロールすることで安心感を得られます。

ハイパーフォーカスでも安心

集中して作業しているときでも、AI が代わりにチームとコミュニケーションを取ってくれます。マイクロマネジメントが不要になり、信頼関係を保ちながら開発に集中できます。

---

主な機能

MCP サーバー

Model Context Protocol (MCP) に対応した HTTP サーバーを /mcp エンドポイントで提供。AI Agents から直接タスク管理が可能です。

利用可能なツール:

• start_task - タスクを開始して Slack に通知
• update_task - 進捗を更新（ブロッキング・休止を自動解消）
• report_blocked - ブロッキングを報告
• pause_task - タスクを一時休止
• resume_task - 休止中のタスクを再開
• complete_task - タスク完了と PR を報告
• list_tasks - タスク一覧を取得

OAuth 2.1 + PKCE 認証

セキュアな認証フローで MCP クライアントを保護：

• 動的クライアント登録 (/api/oauth/register)
• Authorization Code + PKCE フロー (/oauth/authorize)
• アクセストークン管理 (/api/oauth/token)
• Well-Known メタデータエンドポイント

Slack 統合

ユーザー認証:

• Slack OpenID Connect でシームレスなログイン
• ワークスペース単位でのボットインストール

リアルタイム通知:

• タスクごとに専用スレッドを作成
• 開始・進捗・ブロッキング・休止・再開・完了をリアルタイムで投稿
• コードや機密情報は送信せず、抽象的なサマリのみ

日次レポート:

• /daily-report コマンドで AI による日次サマリを生成
• 実行ユーザーのみに表示される ephemeral message

Stripe サブスクリプション

Terraform による料金プラン管理:

• Infrastructure as Code で料金プランを管理
• dev/prod 環境ごとに独立した設定
• lookup key を使った柔軟な価格管理
• Stripe Provider（lukasaron/stripe）を使用

サブスクリプション API:

• チェックアウト (POST /api/stripe/checkout): サブスクリプション購入画面へリダイレクト
• ビリングポータル (POST /api/stripe/portal-session): サブスクリプション管理画面へリダイレクト
• サブスクリプション取得 (GET /api/stripe/subscription): 現在のサブスクリプション情報を取得

Webhook 対応:

• customer.subscription.created/updated/deleted: サブスクリプション変更の自動同期
• customer.deleted: 顧客削除時のデータクリーンアップ
• 署名検証によるセキュアな通信

料金プラン:

• Basic Plan: 500円/月
• lookup key basic_monthly で価格を動的取得
• 自動税計算対応（日本）

ダッシュボード

Web UI でタスクの可視化：

• 進行中・ブロッキング・休止・完了のステータス別表示
• タスクの詳細履歴（更新・ブロッキング・休止の記録）
• チーム全体の作業状況を一覧で確認

開発者体験

• ワンストップオンボーディング（Slack 連携 → チャンネル選択 → MCP 設定）
• .mcp.json 自動生成
• 自己署名証明書対応の開発サーバー
• TypeScript フルサポート

---

アーキテクチャ

Monorepo 構成

このプロジェクトは pnpm workspace を使用した monorepo 構成です:

ava/
├── apps/
│   └── www/              # Next.js アプリケーション (MCP サーバー、API、ダッシュボード)
├── packages/
│   ├── database/         # Drizzle ORM スキーマと DB ユーティリティ
│   └── integrations/     # 外部サービス連携 (Slack, Stripe など)
└── infra/                # Terraform による Infrastructure as Code

システムアーキテクチャ

┌─────────────────┐
│   AI Agents     │
│  (MCP Client)   │
└────────┬────────┘
         │ HTTPS + OAuth 2.1
         ▼
┌─────────────────────────────────────────────────┐
│            Ava (Next.js 16)                     │
│                                                 │
│  ┌──────────┐      ┌────────────┐              │
│  │   /mcp   │      │  /api/*    │              │
│  │  (Hono)  │      │  (Hono)    │              │
│  └──────────┘      └────────────┘              │
│                                                 │
│  ┌──────────────────────────────┐              │
│  │    Next.js App Router        │              │
│  │  (Dashboard, Onboarding)     │              │
│  └──────────────────────────────┘              │
│                                                 │
│  ┌──────────────────────────────┐              │
│  │   OpenTelemetry              │              │
│  │   (instrumentation.ts)       │              │
│  └──────────────────────────────┘              │
└────┬───────────┬───────────┬───────────┬────────┘
     │           │           │           │
     ▼           ▼           ▼           ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│PostgreSQL│ │Slack API │ │Stripe API│ │  Axiom   │
│(Drizzle) │ │(Bot,OIDC)│ │(Payments)│ │ (Traces) │
└──────────┘ └──────────┘ └──────────┘ └──────────┘

ルーティング構成:

• /mcp - MCP サーバー（Hono、単独ルート）
• /api/* - API エンドポイント（Hono、catch-all ルート）
  • /api/oauth/* - OAuth 2.1 認可サーバー
  • /api/auth/* - Slack OIDC 認証
  • /api/slack/* - Slack 連携（ボットインストール、コマンド）
  • /api/stripe/* - Stripe サブスクリプション（チェックアウト、ビリングポータル、Webhook）
  • /api/health - ヘルスチェック
• その他 - Next.js App Router（ダッシュボード、オンボーディング）

---

技術スタック

| カテゴリ | 技術 | | ------------------ | ---------------------------------------- | | フレームワーク | Next.js 16 (App Router), React 19 | | API | Hono 4.10 | | データベース | PostgreSQL + Drizzle ORM | | 認証 | Arctic (OAuth 2.1), Slack OpenID Connect | | MCP | @hono/mcp, @modelcontextprotocol/sdk | | AI | Vercel AI SDK + OpenAI | | 決済 | Stripe | | Infrastructure | Terraform, Stripe Provider (lukasaron) | | Observability | OpenTelemetry, Axiom | | UI | Tailwind CSS v4, Radix UI, shadcn/ui | | 型安全 | TypeScript 5, Zod | | テスト | Vitest, Playwright | | 開発ツール | pnpm, Lefthook, ESLint, Prettier |

---

前提条件

必須

• Node.js 18+ (corepack enable pnpm 推奨)
• Docker & Docker Compose (PostgreSQL 用)
• Slack アプリ - 以下の設定で作成:

Slack アプリの設定

方法 1: App Manifest を使用（推奨）

1. Slack API で「Create New App」→「From an app manifest」を選択

2. ワークスペースを選択

3. 以下の App Manifest を貼り付け（<YOUR_BASE_URL> を実際のベース URL に置き換えてください）:

{
  "display_information": {
    "name": "Ava"
  },
  "features": {
    "bot_user": {
      "display_name": "Ava",
      "always_online": false
    },
    "slash_commands": [
      {
        "command": "/daily-report",
        "url": "https://<YOUR_BASE_URL>/api/slack/commands",
        "description": "本日のタスクサマリを生成",
        "usage_hint": "",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "redirect_urls": [
      "https://<YOUR_BASE_URL>/api/auth/slack/callback",
      "https://<YOUR_BASE_URL>/api/slack/install/callback"
    ],
    "scopes": {
      "user": ["openid", "profile", "email"],
      "bot": [
        "chat:write",
        "chat:write.public",
        "channels:read",
        "groups:read",
        "commands"
      ]
    }
  },
  "settings": {
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://<YOUR_BASE_URL>/api/slack/interactions"
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": true
  }
}

4. App Credentials から Client ID、Client Secret、Signing Secret を取得

方法 2: 手動設定

1. Slack API で「Create New App」→「From scratch」を選択

2. OAuth & Permissions で Bot Token Scopes を追加:

   • chat:write - メッセージ投稿
   • chat:write.public - パブリックチャンネルへの投稿
   • channels:read - チャンネル一覧取得
   • groups:read - プライベートチャンネル一覧取得
   • commands - Slash Command 実行

3. OAuth & Permissions で User Token Scopes を追加:

   • openid - OpenID Connect 認証
   • profile - プロフィール情報取得
   • email - メールアドレス取得

4. OAuth & Permissions で Redirect URLs を追加:

   https://<YOUR_BASE_URL>/api/auth/slack/callback
   https://<YOUR_BASE_URL>/api/slack/install/callback
   

5. Slash Commands で /daily-report を作成:

   • Request URL: https://<YOUR_BASE_URL>/api/slack/commands
   • Description: 本日のタスクサマリを生成

6. App Credentials から Client ID、Client Secret、Signing Secret を取得

• OpenAI API キー - OpenAI Platform で取得
• Stripe アカウント - Stripe Dashboard でアカウントを作成
  • テスト環境で開発する場合は、テストモードの API キーと Webhook シークレットを使用
  • Webhook エンドポイント: https://<YOUR_BASE_URL>/api/stripe/webhook
  • Webhook イベント: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.deleted

---

環境変数の設定

プロジェクトルートに .env ファイルを作成してください。.env.example を参考にしてください：

cp .env.example .env

その後、以下の環境変数を設定します。

環境変数の説明

| 変数名 | 説明 | 必須 | | ------------------------- | ------------------------------------------------------------------------------------ | ---- | | NEXT_PUBLIC_BASE_URL | アプリケーションのベース URL。OAuth メタデータや Slack リダイレクト URL の構築に使用 | Yes | | NEXT_PUBLIC_SITE_NAME | サイト名（デフォルト: "Ava"） | No | | DATABASE_URL | PostgreSQL 接続文字列 | Yes | | SLACK_APP_CLIENT_ID | Slack アプリの Client ID | Yes | | SLACK_APP_CLIENT_SECRET | Slack アプリの Client Secret | Yes | | SLACK_SIGNING_SECRET | Slack アプリの Signing Secret（Slash Command の署名検証に使用） | Yes | | OPENAI_API_KEY | OpenAI API キー（日次レポート機能に使用） | Yes | | STRIPE_SECRET_KEY | Stripe API キー（テスト環境: sk_test_、本番環境: sk_live_） | Yes | | STRIPE_WEBHOOK_SECRET | Stripe Webhook 署名シークレット（Webhook イベントの検証に使用） | Yes | | AXIOM_API_TOKEN | Axiom API トークン（OpenTelemetry トレースの送信に使用、本番環境のみ） | No | | AXIOM_DATASET_NAME | Axiom データセット名（OpenTelemetry トレースの送信先、本番環境のみ） | No |

---

ローカル開発

# corepack を有効化
$ npm run setup

# 依存関係をインストール
$ pnpm install

# .env としてコピー
$ cp .env.example .env

.env ファイルに環境変数を設定してください（前述の「環境変数の設定」を参照）。

# PostgreSQL コンテナを起動
$ pnpm db:up

# マイグレーションを実行
$ pnpm db:migrate

# 開発サーバーを起動
$ pnpm dev

サーバーが起動したら、https://localhost:3000 にアクセスしてください。

Stripe Webhook のローカルテスト