# AIエージェント開発プロジェクト詳細
## 1. プロジェクト概要
### サービス概要
- 複数のデジタルマーケティングAPIを統合したAIチャットアプリケーションの開発
- Google Analytics 4、Google Ads、Google Tag Manager、Search Console、Meta広告などのプラットフォームにAI経由でアクセス可能な統合基盤を構築
- MCP(Model Context Protocol)を採用したマイクロサービス設計により、各マーケティングAPIを独立したサービスとして管理
- 複数のLLMプロバイダー(xAI、OpenAI、Anthropic、Gemini等)に対応したマルチモデル戦略を実現
### アーキテクチャ
- 2リポジトリ構成
- フロントエンド(Next.js)とMCPゲートウェイサーバー(Express + Python)の分離アーキテクチャ
- マルチテナント対応(ユーザーごとのOAuthトークン管理)
---
## 2. 技術スタック
### フロントエンド
| カテゴリ | 技術 |
|---------|------|
| フレームワーク | React 19, Next.js 16(App Router), TypeScript |
| スタイリング | Tailwind CSS 4 |
| UIコンポーネント | Radix UI, shadcn/ui |
### バックエンド
| カテゴリ | 技術 |
|---------|------|
| 言語 | TypeScript, Python 3 |
| フレームワーク | Express 5, Node.js 20 |
### AI/LLM
| カテゴリ | 技術 |
|---------|------|
| SDK | Vercel AI SDK, Anthropic SDK, OpenAI SDK |
| モデル | xAI(grok-2), OpenAI, Anthropic, Gemini |
### MCP Server
| カテゴリ | 技術 |
|---------|------|
| SDK | @modelcontextprotocol/sdk |
| プロトコル | JSON-RPC, SSE |
### データベース・認証
| カテゴリ | 技術 |
|---------|------|
| DB | Supabase(PostgreSQL), Redis |
| ORM | Drizzle ORM |
| 認証 | NextAuth 5, OAuth(Google/Meta), Magic Link(Resend) |
### インフラ・ツール
| カテゴリ | 技術 |
|---------|------|
| ホスティング | Vercel, Fly.io |
| コンテナ | Docker |
| テスト | Playwright(E2E) |
| ツール | GitHub, Biome, Sentry |
### 外部連携API
- Google Ads API
- GA4 API
- GTM API
- Search Console API
- Meta Ads API
---
## 3. 担当フェーズ
### フロントエンド
#### ジョイン前の既存アーキテクチャにおける課題提起
| 課題 | 詳細 |
|------|------|
| コンポーネント設計の不統一 | 既存実装がAtomic Designに沿っておらず、再利用性が低い |
| テスト基盤の欠如 | Storybook未導入、ビジュアルリグレッションテストなし |
| 品質担保の仕組みがない | 意図しないUI変更を検知する仕組みがない |
#### Atomic Designにおける再設計・実装
| やったこと | 詳細 |
|-----------|------|
| **コンポーネント設計の見直し** | 既存実装をAtomic Designベースで再設計 |
| **UI/ロジック分離** | UIコンポーネントはPropsを受け取り表示のみに徹する設計 |
| **shadcn/ui活用** | 基底コンポーネントとして使用し、プロジェクト用にカスタマイズ |
| **再利用性の向上** | 汎用的なコンポーネントの抽出・整理 |
#### Storybook・リグレッションテストの導入
| やったこと | 詳細 |
|-----------|------|
| **Storybook導入** | コンポーネントカタログとしてStorybookを構築 |
| **VRT導入** | Chromaticと連携しビジュアルリグレッションテストを実現 |
| **品質担保の仕組み化** | 意図しないUI変更を自動検知できる状態を構築 |
---
### バックエンド
#### Google Tag Manager MCP Serverの開発
**OAuth認証検証**
| やったこと | 詳細 |
|-----------|------|
| **技術調査** | GTM APIがOAuth 2.0必須であること、既存のGoogle Ads/GA4実装を流用可能であることを確認 |
| **実現可能性の検証** | 必要なパッケージ、スコープ、実装フローを詳細に調査・整理 |
| **既存アーキテクチャとの整合性確認** | 既存の`Integrations`テーブルや`getValidAccessToken`との統合方法を整理 |
| **プロトタイプ作成** | `scripts/gtm-prototype.ts`で実際にAPIへの疎通を確認 |
**GTM APIの調査・提案**
| やったこと | 詳細 |
|-----------|------|
| **必要なAPIの特定** | 本プロジェクトで必要となるGTM APIを調査し提案 |
| **スコープの整理** | `tagmanager.manage.users`スコープは不要であることを確認 |
| **懸念点の提案** | チャット側から呼び出す際のGTM APIにおける注意点を整理 |
**MCP Server実装**
| やったこと | 詳細 |
|-----------|------|
| **OAuthを用いたGTM API呼び出し実装** | 既存のGoogle Ads実装を参考に、GTM用の認証フローを構築 |
| **オープンソース活用** | stape-io/google-tag-manager-mcp-serverを参考に実装 |
| **マルチテナント対応** | ユーザーごとのOAuthトークン管理を実現 |
---
## 4. 出したバリュー・できること
### 既存プロジェクトへの課題提起と改善
#### 課題発見から改善提案まで
| やったこと | 詳細 |
|-----------|------|
| **アーキテクチャの課題特定** | ジョイン時に既存実装の課題を構造的に把握 |
| **改善提案** | Atomic Design、Storybook、VRT導入を提案 |
| **実行** | 提案内容を自ら実装し、開発基盤を整備 |
#### 本業で培ったスキルの応用
| 本業での経験 | AIエージェント開発での応用 |
|-------------|--------------------------|
| Atomic Designベースのコンポーネント設計 | 既存実装の再設計 |
| Storybook × Chromatic導入経験 | テスト基盤の構築 |
| VRTによる品質担保 | 意図しないUI変更の自動検知 |
| shadcn/ui活用経験 | 基底コンポーネントの整理 |
---
### 新技術領域へのキャッチアップ
#### MCP(Model Context Protocol)の習得
| やったこと | 詳細 |
|-----------|------|
| **プロトコルの理解** | JSON-RPC、SSEを用いたAI-API連携の仕組みを理解 |
| **実装** | GTM MCP Serverを実際に構築 |
| **設計思想の理解** | MCPが「部品」であり、課題解決には上位設計が必要であることを認識 |
#### AI/LLMエコシステムの理解
| 学んだこと | 詳細 |
|-----------|------|
| **Vercel AI SDK** | マルチモデル対応のAIアプリケーション構築方法 |
| **OAuth × MCP** | ユーザーごとのAPIアクセス管理の設計 |
| **マーケティングAPI統合** | GA4、Google Ads、GTM等のAPI連携実装 |
---
### AI Agentに対する考察
#### MCPの現在地と限界の理解
| 観点 | 考察 |
|------|------|
| **MCPの本質** | AIにMCPで実行できる関数を公開し、チャットの指示をAIに飛ばしてMCPで何を実行するかを行っているだけ |
| **自律性の欠如** | 現状は完全に受動的。ユーザーが指示しない限り何も起きない |
| **ドメイン知識の必要性** | ツールがあってもドメイン知識がなければ使えない |
#### 「なんでもできる」の罠
| 問題点 | 詳細 |
|--------|------|
| **汎用性の罠** | 「なんでもできます」は基本何もできないのと同じ |
| **素人には使えない** | 高度な専門知識がないとチャットベースでの課題解決は困難 |
| **課題発見の難しさ** | 人が感じている課題は感覚的で言語化が困難 |
#### 真に価値を発揮するために必要なもの
| 必要なもの | 詳細 |
|-----------|------|
| **AI専用のUIUX設計** | Chatだけでは課題発見・導線設計ができない |
| **高度なシステム設計** | 状態管理、コンテキスト保持、マルチステップ実行が必要 |
| **ドメイン知識の組み込み** | 特定の課題に特化したソリューション設計 |
#### 結論
> AI Agentが真に価値を発揮するには、「ユーザーが課題を言語化できない」前提で設計する必要がある。
> 現状のChat + MCPは「課題がわかっている専門家向けのツール」であり、素人の課題解決には「課題発見→言語化→解決」の全体設計が必要。
---
## 5. できること(本プロジェクトで証明されたスキル)
| カテゴリ | できること |
|---------|-----------|
| **既存プロジェクトへの参画** | 既存アーキテクチャの課題を特定し、改善提案・実行までできる |
| **フロントエンド再設計** | Atomic Designベースでのコンポーネント再設計 |
| **テスト基盤構築** | Storybook、VRT導入による品質担保の仕組み化 |
| **新技術キャッチアップ** | MCP、AI SDK等の新技術を短期間で習得し実装 |
| **バックエンド実装** | OAuth認証、外部API連携の調査・実装 |
| **技術調査・提案** | 実現可能性の検証、懸念点の整理、ドキュメント化 |
| **AI/LLMエコシステム理解** | MCPの設計思想、限界、活用方法を構造的に理解 |
---
## 6. 成果・実績
| 実績 | 詳細 |
|------|------|
| **課題提起** | ジョイン前のアーキテクチャ課題を構造的に整理・提案 |
| **フロントエンド再設計** | Atomic Designベースでのコンポーネント再設計を実施 |
| **Storybook導入** | コンポーネントカタログ・テスト基盤を構築 |
| **VRT導入** | Chromaticと連携しビジュアルリグレッションテストを実現 |
| **GTM OAuth検証** | 技術調査〜プロトタイプ作成〜実装まで完了 |
| **GTM MCP Server実装** | OAuth認証を用いたGTM API呼び出しを実現 |
---
## 7. 技術スタック(まとめ)
| カテゴリ | 技術 |
|---------|------|
| Frontend | React 19, Next.js 16, TypeScript, Tailwind CSS 4, Radix UI, shadcn/ui |
| Backend | Express 5, Node.js 20, Python 3 |
| AI/LLM | Vercel AI SDK, Anthropic SDK, OpenAI SDK, xAI(grok-2) |
| MCP | @modelcontextprotocol/sdk, JSON-RPC, SSE |
| Database | Supabase(PostgreSQL), Drizzle ORM, Redis |
| Auth | NextAuth 5, OAuth(Google/Meta), Magic Link(Resend) |
| Infra | Vercel, Fly.io, Docker |
| Test | Playwright(E2E), Storybook, Chromatic |
| Tools | GitHub, Biome, Sentry |
| External API | Google Ads API, GA4 API, GTM API, Search Console API, Meta Ads API |