# MCP 導入ガイド -- AI x SaaS 連携の実践手順書
**作成日**: 2026-02-18
**対象読者**: CDX/DS-DAL グループメンバー
**前提知識**: ターミナル操作、Python/Node.js の基礎
**所要時間**: 約 60〜90 分（初回構築）
---
## 目次
1. [はじめに -- このガイドの目的](#1-はじめに----このガイドの目的)
2. [MCP とは何か -- 導入前後で何が変わるか](#2-mcp-とは何か----導入前後で何が変わるか)
3. [この導入事例の応用範囲](#3-この導入事例の応用範囲)
4. [前提条件と必要なソフトウェア](#4-前提条件と必要なソフトウェア)
5. [セットアップ手順](#5-セットアップ手順-step-by-step)
6. [アーキテクチャ詳細（技術者向け補足）](#6-アーキテクチャ詳細技術者向け補足)
7. [よくあるエラーと対処法](#7-よくあるエラーと対処法)
8. [期待値の制御 -- できること・できないこと](#8-期待値の制御----できることできないこと)
9. [今後の展望](#9-今後の展望)
---
## 1. はじめに -- このガイドの目的
### 1.1 背景
私たちは日常的に Asana でタスク管理を行っています。一方で、AI（大規模言語モデル）を活用した開発環境も進化しています。しかし、この2つは「別世界」でした。AI に「プロジェクトの進捗を教えて」と聞いても、AI は Asana の中身を知りません。結局、ブラウザで Asana を開いて、情報を手でコピーして AI に伝え直す、という作業が発生していました。
**MCP（Model Context Protocol）** を導入すると、AI が直接 Asana にアクセスできるようになります。「AIに手足が生える」イメージです。
### 1.2 このガイドのゴール
このガイドを最後まで実行すると、以下ができるようになります。
- MCP クライアント（Cursor、VS Code 等）から、自然言語で Asana の情報を取得できる
- タスクやプロジェクトの作成・更新を指示できる
- 削除操作には「二段階確認」が強制され、誤操作を防止できる
- 全ての破壊的操作が監査ログに記録される
### 1.3 重要な前提
- **この手順書は全て人間が手作業で実行するもの**です。AI に構築作業を委任するものではありません。
- 手順書内の設定値（メールアドレス、トークン等）はプレースホルダです。自分の情報に置き換えてください。
- 今回は Asana を対象にしていますが、構築プロセスの大部分は他のサービス向け MCP にも応用できます（第3章参照）。
---
## 2. MCP とは何か -- 導入前後で何が変わるか
### 2.1 MCP の概念
MCP（Model Context Protocol）は、Anthropic 社が策定した **AI と外部サービスを接続するためのオープン標準プロトコル** です。特定の IDE や AI ツールに依存するものではありません。
```mermaid
flowchart LR
You["あなた"] -->|自然言語で指示| Client["MCP クライアント\n(Cursor / VS Code / Claude Desktop)"]
Client -->|"JSON-RPC 2.0\n(MCP プロトコル)"| Server["MCP サーバー"]
Server -->|"REST API / SDK"| Service["外部サービス\n(Asana, Jira, Slack 等)"]
```
「MCPクライアント」とは、このプロトコルを話せるアプリケーションの総称です（Cursor、VS Code + GitHub Copilot、Claude Desktop 等）。
### 2.2 導入前後の比較
**導入前（MCP なし）:**
```mermaid
flowchart LR
You["あなた"] -->|質問| AI["AI"]
AI -->|"回答するが\nAsanaの中身は\n知らない"| You
You -->|ブラウザで確認| Asana["Asana"]
Asana -->|情報を目視| You
You -->|"手でコピーして\n伝え直す"| AI
```
AI は「頭は良いが手足がない」状態。あなたが情報の橋渡し役になっています。
**導入後（MCP あり）:**
```mermaid
flowchart LR
You["あなた"] -->|"未完了タスクを\n教えて"| AI["AI + MCP"]
AI -->|自動アクセス| Asana["Asana"]
Asana -->|データ返却| AI
AI -->|"未完了タスクは\n7件です..."| You
```
AI に「手足」が生えた状態。あなたは指示を出すだけです。
### 2.3 具体的な差分
| 観点 | 導入前 | 導入後 |
|:---|:---|:---|
| 情報取得 | ブラウザで Asana を開き、目視で確認 | 自然言語で質問するだけ |
| タスク作成 | Asana の UI で手入力 | 「タスクを作って」で完了 |
| 誤削除リスク | ワンクリックで即削除 | プレビュー確認 + トークン承認が必須 |
| 操作の記録 | Asana の履歴のみ | 独自の監査ログ (JSONL) に詳細記録 |
| コンテキスト切り替え | エディタ ↔ ブラウザの往復 | MCP クライアント内で完結 |
### 2.4 本ガイドで構築するシステムの全体像
```mermaid
flowchart TB
subgraph LocalPC ["あなたの PC"]
Client["MCP クライアント\n(Cursor / VS Code / Claude Desktop)"]
subgraph OfficialMCP ["公式 MCP サーバー (asana-official)"]
OfficialDesc["閲覧 / 作成 / 更新 / 検索\n(15ツール)"]
end
subgraph GuardMCP ["自作ガードサーバー (asana-guard)"]
GuardDesc["削除の二段階確認\n監査ログ記録\n(5ツール)"]
end
Client -->|"MCP プロトコル\n(stdio)"| OfficialMCP
Client -->|"MCP プロトコル\n(stdio)"| GuardMCP
end
subgraph Cloud ["クラウド"]
Asana["Asana"]
end
OfficialMCP -->|"Asana 内部 API\n(OAuth 認証)"| Asana
GuardMCP -->|"REST API\n(PAT 認証)"| Asana
```
- **公式 MCP サーバー**: Asana 社が提供・メンテナンス。閲覧・作成・更新など日常操作を担当。
- **自作ガードサーバー**: ローカルで動く Python サーバー。削除操作に二段階確認を強制し、監査ログを記録する。
---
## 3. この導入事例の応用範囲
### 3.1 Asana だけに使えるもの？
**いいえ。** 基礎の約80%は汎用的で、他のサービスにも応用できます。
| 技術要素 | Asana 固有？ |
|:---|:---|
| MCP プロトコルの理解と設定方法 | **汎用** |
| `mcp-remote` によるリモート MCP 接続方法 | **汎用** |
| OAuth 認証の設定パターン (ポート固定等) | **汎用** |
| FastMCP での自作サーバー構築技術 | **汎用** |
| 二段階削除ガードの設計思想 | **汎用** |
| 監査ログの仕組み (JSONL、秘匿マスク) | **汎用** |
| `keyring` でのシークレット管理 | **汎用** |
| 企業プロキシ環境への対応ノウハウ | **汎用** |
| `asana_client.py` の API 呼び出し部分 | **Asana 固有** |
| `delete_guard.py` のビジネスルール | **Asana 固有** |
つまり、`asana_client.py` を `jira_client.py` や `slack_client.py` に差し替えれば、同じ構造で他サービスのガード付き MCP を構築できます。
### 3.2 特定の IDE に縛られる？
**いいえ。** MCP はオープンな業界標準プロトコルです。以下のツールが対応しています。
| ツール | MCP 対応状況 | 設定ファイル |
|:---|:---|:---|
| **Cursor** | ネイティブ対応 | `.cursor/mcp.json` |
| **VS Code + GitHub Copilot** | 対応済み | `.vscode/mcp.json` |
| **Claude Desktop** | ネイティブ対応 | `claude_desktop_config.json` |
| **Windsurf** | 対応済み | 各ドキュメント参照 |
**サーバー側のコードは一切変更不要** です。変わるのは設定ファイルの場所と書き方だけです。
---
## 4. 前提条件と必要なソフトウェア
### 4.1 必要なソフトウェア
| ソフトウェア | 用途 | インストール方法 |
|:---|:---|:---|
| **Node.js (LTS)** | 公式 MCP サーバーへの接続ブリッジ (`mcp-remote`) | `winget install OpenJS.NodeJS.LTS` |
| **Python 3.12 以上** | 自作ガードサーバーの実行 | `winget install Python.Python.3.12` |
| **MCP クライアント** (いずれか1つ) | MCP サーバーとの通信 | 下記参照 |
> **補足**: 「公式 MCP だけ使い、ガードサーバーは不要」という場合は、Node.js と MCP クライアントだけで完結します（Python 不要）。
### 4.2 MCP クライアントの選択
自分が普段使っているツールを選んでください。
- **Cursor**: [https://www.cursor.com/](https://www.cursor.com/)
- **VS Code**: [https://code.visualstudio.com/](https://code.visualstudio.com/) + GitHub Copilot 拡張
- **Claude Desktop**: [https://claude.ai/download](https://claude.ai/download)
### 4.3 その他の前提
- Asana アカウントを持っていること（Developer Console へのアクセス権が必要）
- 社内プロキシ: `http://c000a10-vip.cosmo-oil.co.jp:12080`（設定テンプレートに組み込み済み）
- Windows の管理者権限があること（ソフトウェアインストールのため）
---
## 5. セットアップ手順 (Step-by-Step)
各ステップは以下の4項目で構成されています。
- **何をするか**: 作業の目的
- **具体的な手順**: コマンドや操作内容
- **完了条件**: 正常に終わったことの確認方法
- **注意点**: よくあるエラーと対処法
---
### Step 1: Node.js と Python のインストール確認
**何をするか**: MCP サーバーの実行に必要なランタイムがインストール済みかを確認する。
**具体的な手順**:
PowerShell を開き、以下のコマンドを実行する。
```powershell
node -v
python --version
```
未インストールの場合は以下を実行する。
```powershell
winget install OpenJS.NodeJS.LTS
winget install Python.Python.3.12
```
インストール後、PowerShell を一度閉じて開き直す（PATH を反映するため）。
**完了条件**:
```
> node -v
v22.x.x (v18 以上であれば OK)
> python --version
Python 3.12.x (3.10 以上であれば OK)
```
**注意点**:
- `winget` が使えない場合は、公式サイトからインストーラをダウンロードしてください。
- Node.js はポータブル版ではなく、通常のインストーラ版を使用してください。ポータブル版は PATH 設定ミスを招きます。
---
### Step 2: リポジトリのクローンと Python 仮想環境の構築
**何をするか**: ソースコードを取得し、Python の依存パッケージをインストールする。
**具体的な手順**:
```powershell
# リポジトリをクローン（URL は実際のリポジトリに置き換えてください）
git clone <リポジトリURL> Asana_MCP_RestAPI
cd Asana_MCP_RestAPI
# Python 仮想環境を作成
python -m venv .venv
# 仮想環境を有効化
.venv\Scripts\Activate.ps1
# 依存パッケージをインストール
pip install -r mcp-local-server\pyproject.toml
```
> `pyproject.toml` から直接インストールする場合は以下でも可:
> ```powershell
> pip install mcp httpx keyring pydantic pyyaml
> ```
**完了条件**:
```powershell
# 仮想環境が有効であること（プロンプトに (.venv) と表示される）
(.venv) PS> python -c "import mcp; print('OK')"
OK
```
**注意点**:
- **`pip install --upgrade pip` は実行しないでください。** Windows 環境ではファイルロック (`WinError 32`) が発生する場合があります。pip のバージョンアップは必須ではありません。
- 仮想環境の有効化でエラーが出る場合は、PowerShell の実行ポリシーを確認してください:
```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```
---
### Step 3: Asana Personal Access Token (PAT) の取得と保存
**何をするか**: Asana の認証情報を取得し、OS の安全なストレージに保存する。
**具体的な手順**:
**(1) PAT を生成する**
1. ブラウザで Asana にログインする
2. 右上のプロフィール画像 → 「マイ設定」→「アプリ」→「デベロッパーアプリの管理」を開く
3. 「パーソナルアクセストークンの作成」をクリックする
4. 表示されたトークン文字列をコピーする（このトークンは二度と表示されません）
**(2) PAT を安全に保存する**
仮想環境が有効な状態で以下を実行する。
```powershell
(.venv) PS> python scripts\setup_auth.py
```
プロンプトが表示されたら、コピーした PAT を貼り付けて Enter を押す。
**(3) 接続を確認する**
```powershell
(.venv) PS> python scripts\verify_connection.py
```
**完了条件**:
```
API Base: https://app.asana.com/api/1.0
Proxy: http://c000a10-vip.cosmo-oil.co.jp:12080
Log Dir: C:\...\logs
User: あなたの名前
Email: your_name@cosmo-oil.co.jp
GID: 1234567890123456
Connection OK
```
**注意点**:
- **PAT を貼り付ける際に文字化けが起きることがあります。** ターミナルへのペースト時に、非 ASCII 文字（制御文字や全角スペース等）が混入する場合があります。`setup_auth.py` にはサニタイズ処理が組み込まれていますが、接続エラーが出る場合はスクリプトを再実行してください。
- PAT は Windows 資格情報マネージャー（DPAPI 暗号化）に保存されます。平文ファイルには保存されません。
---
### Step 4: Asana OAuth アプリの作成（公式 MCP 用）
**何をするか**: 公式 MCP サーバーとの OAuth 認証に必要なアプリを Asana 側に登録する。
**具体的な手順**:
1. ブラウザで [https://app.asana.com/0/my-apps](https://app.asana.com/0/my-apps) を開く
2. 「アプリを作成」をクリックする
3. 以下の情報を入力する:
- **アプリ名**: `MCP Integration`（任意の名前）
- **アプリの用途**: 個人的に使用
4. 作成後、「OAuth」タブを開く
5. **リダイレクト URL** に以下を追加する:
```
http://localhost:3334/oauth/callback
```
6. 「クライアント ID」と「クライアント シークレット」をメモする
**完了条件**:
- クライアント ID（数字の文字列）を取得できていること
- クライアント シークレット（英数字の文字列）を取得できていること
- リダイレクト URL が `http://localhost:3334/oauth/callback` に設定されていること
**注意点**:
- **リダイレクト URL のポート番号 `3334` は非常に重要です。** `mcp-remote` はデフォルトでポートを動的に選択しますが、Asana 側に登録した URL と一致しないと認証エラー (`redirect_uri mismatch`) が発生します。Step 5 の設定でポートを `3334` に固定します。
- OAuth アプリの「提出してレビューを受ける」は不要です。個人利用の範囲であればそのまま使えます。
---
### Step 5: MCP クライアントの設定ファイル作成
**何をするか**: MCP クライアントがサーバーに接続するための設定ファイルを作成する。
**具体的な手順**:
使用する MCP クライアントに応じて、適切な場所に設定ファイルを作成してください。
---
#### Cursor の場合
ファイル: `<プロジェクトルート>/.cursor/mcp.json`
```json
{
"mcpServers": {
"asana-official": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.asana.com/v2/mcp",
"3334",
"--static-oauth-client-info",
"{\"client_id\":\"<あなたのクライアントID>\",\"client_secret\":\"<あなたのクライアントシークレット>\"}",
"--enable-proxy"
],
"env": {
"HTTPS_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080",
"HTTP_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080"
}
},
"asana-guard": {
"command": "${workspaceFolder}/.venv/Scripts/python.exe",
"args": [
"${workspaceFolder}/mcp-local-server/src/server.py"
],
"env": {
"ASANA_WORKSPACE": "<あなたのワークスペースGID>",
"HTTPS_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080",
"HTTP_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080",
"LOG_DIR": "${workspaceFolder}/logs"
}
}
}
}
```
---
#### VS Code + GitHub Copilot の場合
ファイル: `<プロジェクトルート>/.vscode/mcp.json`
```json
{
"servers": {
"asana-official": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.asana.com/v2/mcp",
"3334",
"--static-oauth-client-info",
"{\"client_id\":\"<あなたのクライアントID>\",\"client_secret\":\"<あなたのクライアントシークレット>\"}",
"--enable-proxy"
],
"env": {
"HTTPS_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080",
"HTTP_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080"
}
},
"asana-guard": {
"command": "<プロジェクトルートの絶対パス>/.venv/Scripts/python.exe",
"args": [
"<プロジェクトルートの絶対パス>/mcp-local-server/src/server.py"
],
"env": {
"ASANA_WORKSPACE": "<あなたのワークスペースGID>",
"HTTPS_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080",
"HTTP_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080",
"LOG_DIR": "<プロジェクトルートの絶対パス>/logs"
}
}
}
}
```
---
#### Claude Desktop の場合
ファイル:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"asana-official": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.asana.com/v2/mcp",
"3334",
"--static-oauth-client-info",
"{\"client_id\":\"<あなたのクライアントID>\",\"client_secret\":\"<あなたのクライアントシークレット>\"}",
"--enable-proxy"
],
"env": {
"HTTPS_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080",
"HTTP_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080"
}
},
"asana-guard": {
"command": "<プロジェクトルートの絶対パス>/.venv/Scripts/python.exe",
"args": [
"<プロジェクトルートの絶対パス>/mcp-local-server/src/server.py"
],
"env": {
"ASANA_WORKSPACE": "<あなたのワークスペースGID>",
"HTTPS_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080",
"HTTP_PROXY": "http://c000a10-vip.cosmo-oil.co.jp:12080",
"LOG_DIR": "<プロジェクトルートの絶対パス>/logs"
}
}
}
}
```
---
**プレースホルダの置き換え一覧**:
| プレースホルダ | 置き換える値 | 取得方法 |
|:---|:---|:---|
| `<あなたのクライアントID>` | Step 4 で取得した Client ID | Asana Developer Console |
| `<あなたのクライアントシークレット>` | Step 4 で取得した Client Secret | Asana Developer Console |
| `<あなたのワークスペースGID>` | Asana ワークスペースの GID | Asana URL の数字部分、または API で取得 |
| `<プロジェクトルートの絶対パス>` | リポジトリをクローンした場所 | 例: `C:/Users/yourname/Asana_MCP_RestAPI` |
**プロキシ設定について**: 上記テンプレートには社内プロキシ (`http://c000a10-vip.cosmo-oil.co.jp:12080`) と `--enable-proxy` フラグが設定済みです。社内ネットワークから接続する場合はそのまま使用してください。
**完了条件**:
- 設定ファイルが正しい場所に保存されていること
- JSON の構文エラーがないこと（VS Code 等で開いてエラー表示がないことを確認）
**注意点**:
- **この設定ファイルにはシークレット（Client Secret）が含まれます。** Git リポジトリにコミットしないよう、`.gitignore` に追加してください:
```
.cursor/mcp.json
.vscode/mcp.json
```
- PowerShell 上で JSON 文字列を引数として渡すとエスケープ問題が発生しやすいです。**設定ファイルに直接書く** のが最も確実な方法です。
- パス区切りは Windows でも `/`（スラッシュ）を使用してください。
---
### Step 6: MCP クライアントの再起動と接続確認
**何をするか**: MCP クライアントを再起動してサーバーを読み込み、接続を確認する。
**具体的な手順**:
1. MCP クライアント（Cursor / VS Code / Claude Desktop）を完全に終了する
2. 再度起動する
3. MCP サーバーの接続状態を確認する:
- **Cursor**: Settings → MCP Servers で `asana-official` と `asana-guard` が緑色のインジケータになっていること
- **VS Code**: コマンドパレット (Ctrl+Shift+P) → `MCP: List Servers` で確認
- **Claude Desktop**: Settings → Developer → MCP Servers で確認
4. **初回のみ**: `asana-official` の起動時にブラウザが自動的に開き、Asana の OAuth 認証画面が表示されます。自分の Asana アカウントで「許可」をクリックしてください。ブラウザに `Authorization successful! You may close this window.` と表示されれば成功です。
**完了条件**:
- `asana-official` と `asana-guard` の両方が「接続済み」状態になっていること
- OAuth 認証が完了していること（初回のみ）
**注意点**:
- **ポート競合エラー (`EADDRINUSE`)**: 前回の `mcp-remote` プロセスが終了せずにポートを掴んでいる場合に発生します。以下の手順で解決してください:
1. タスクマネージャーで `node.exe` プロセスを全て終了する
2. `~/.mcp-auth/` フォルダ内のファイルを全て削除する
3. MCP クライアントを再起動する
- OAuth 認証は初回のみ必要です。トークンはローカルにキャッシュされます。ただし、トークンの有効期限が切れた場合は再認証が求められます。
---
### Step 7: Agent ルールファイルの配置（Cursor を使用する場合のみ）
**何をするか**: AI Agent が操作の種類に応じて適切な MCP サーバーを自動選択するためのルールを配置する。
> **注意**: この手順は Cursor 固有の機能です。VS Code や Claude Desktop には同等の仕組みがないため、それらのクライアントでは AI への指示に「削除は asana-guard を使って」等を明示する必要があります。
**具体的な手順**:
リポジトリに含まれている `.cursor/rules/asana-operations.mdc` を確認してください。このファイルは、以下のルールを AI Agent に自動適用します:
- 閲覧・作成・更新 → `asana-official` を使用
- 削除・一括操作 → `asana-guard` を使用
- 「削除」「消す」「一括」等のキーワードを検知した場合、自動的に `asana-guard` を強制
- 削除時は必ず「プレビュー表示 → ユーザー承認 → 実行」の3ステップを踏む
**完了条件**:
- `.cursor/rules/asana-operations.mdc` がリポジトリ内に存在すること
---
### Step 8: 動作確認（手動テスト）
**何をするか**: 全てのセットアップが正しく完了したことを、実際の操作で確認する。
**具体的な手順**:
MCP クライアントの AI チャット機能を使い、以下の操作を順番に試してください。全て手動で実施します。
**(1) 閲覧テスト**
AI に以下のような指示を送り、Asana の情報が返ることを確認する。
```
自分に割り当てられているタスクを教えてください
```
正常であれば、自分のタスク一覧が表示されます。
**(2) 作成テスト**
```
「[TEST] 動作確認用プロジェクト」という名前でテスト用プロジェクトを作成してください
```
```
そのプロジェクトに「[TEST] テストタスク」を作成してください
```
Asana をブラウザで開き、実際にプロジェクトとタスクが作成されていることを確認する。
**(3) 削除テスト（二段階確認の動作確認）**
```
「[TEST] テストタスク」を削除してください
```
以下の流れになれば正常です:
1. AI がタスクの情報（名前、プロジェクト、担当者等）をプレビュー表示する
2. 「削除してよいですか？」と確認を求められる
3. 「はい」と回答すると削除が実行される
**(4) クリーンアップ**
```
「[TEST] 動作確認用プロジェクト」を削除してください
```
テスト用に作成した全てのリソースを削除し、ワークスペースを元の状態に戻してください。
**完了条件**:
- 閲覧、作成、削除が全て正常に動作すること
- 削除時に二段階確認（プレビュー → 承認 → 実行）が動作すること
- テスト用データが全て削除され、ワークスペースが元の状態に戻っていること
---
## 6. アーキテクチャ詳細（技術者向け補足）
カスタマイズや拡張を行いたい方向けの技術情報です。セットアップだけが目的であれば、この章は飛ばしても問題ありません。
### 6.1 ディレクトリ構成
```
Asana_MCP_RestAPI/
├── .cursor/
│ ├── mcp.json ← MCP サーバー設定 (Cursor用、.gitignore対象)
│ └── rules/
│ └── asana-operations.mdc ← Agent 行動規範 (Cursor用)
├── configs/
│ ├── .env.example ← 環境変数テンプレート
│ ├── naming_rules.yaml ← 命名規則ポリシー (将来用)
│ └── policies.yaml ← 運用ポリシー定義
├── logs/ ← 監査ログ出力先 (.gitignore対象)
├── mcp-local-server/
│ ├── pyproject.toml ← Python 依存定義
│ └── src/
│ ├── server.py ← MCP サーバー本体 (FastMCP)
│ ├── asana_client.py ← Asana REST API クライアント
│ ├── auth.py ← 認証情報管理 (keyring)
│ ├── config.py ← 設定値ローダー
│ ├── audit_logger.py ← 監査ログ記録
│ ├── rate_limiter.py ← レートリミッター
│ └── tools/
│ └── delete_guard.py ← 二段階削除ロジック
├── scripts/
│ ├── setup_auth.py ← PAT 登録スクリプト
│ └── verify_connection.py ← 疎通確認スクリプト
├── plans/ ← 計画・テスト計画
├── reports/ ← レポート類
└── .gitignore
```
### 6.2 主要モジュールの役割
| モジュール | 役割 |
|:---|:---|
| `server.py` | FastMCP フレームワークで 5 つのツールを登録し、stdio で MCP クライアントと通信する |
| `asana_client.py` | Asana REST API への HTTP リクエストを実行する。リトライ（429/5xx対応）とプロキシ設定を内蔵 |
| `auth.py` | Windows 資格情報マネージャーから PAT を取得する。平文ファイルには一切書き出さない |
| `config.py` | 環境変数から設定値（プロキシ URL、タイムアウト、ログディレクトリ等）を読み込む |
| `delete_guard.py` | 削除の二段階フロー（プレビュー → トークン発行 → 検証 → 実行）を制御する |
| `audit_logger.py` | 全操作を JSONL 形式で記録する。Bearer トークン等の秘匿情報は自動マスクされる |
### 6.3 ガードサーバーが提供するツール一覧
| ツール名 | 機能 |
|:---|:---|
| `guard_delete_task` | タスク削除のプレビューを表示し、60秒有効の確認トークンを発行する |
| `guard_delete_project` | プロジェクト削除のプレビューを表示し、60秒有効の確認トークンを発行する |
| `guard_confirm_delete` | 確認トークンを検証し、有効であれば削除を実行する |
| `guard_audit_log` | 監査ログを検索・表示する |
| `guard_check_connection` | Asana API への疎通を確認する |
---
## 7. よくあるエラーと対処法
実際の構築で発生したエラーとその解決策をまとめています。
### 7.1 OAuth リダイレクトエラー
**症状**: ブラウザに `invalid_request: The redirect_uri parameter does not match a valid url for the application` と表示される。
**原因**: `mcp-remote` が使用するポート番号と、Asana Developer Console に登録したリダイレクト URL のポート番号が一致していない。
**対処**:
1. Asana Developer Console のリダイレクト URL が `http://localhost:3334/oauth/callback` であることを確認する
2. 設定ファイルの `args` で、`"3334"` が `mcp-remote` の URL の直後（第2引数の位置）にあることを確認する
### 7.2 PAT の文字化け / 認証エラー
**症状**: `verify_connection.py` で `UnicodeEncodeError` や `401 Unauthorized` が発生する。
**原因**: ターミナルへの PAT 貼り付け時に、非 ASCII 文字（制御文字、全角文字等）が混入した。
**対処**:
1. `python scripts\setup_auth.py` を再実行する
2. PAT をコピーし直し、貼り付け後に Enter を押す
3. スクリプトが自動的にサニタイズ処理を行い、不要な文字を除去する
### 7.3 ポート競合 (EADDRINUSE)
**症状**: MCP クライアント起動時に `EADDRINUSE: address already in use 127.0.0.1:3334` と表示される。
**原因**: 前回の `mcp-remote` プロセスが正常に終了せず、ポートを掴んだまま残っている。
**対処**:
1. タスクマネージャーで `node.exe` プロセスを全て終了する
2. 以下のフォルダ内のファイルを削除する:
```
%USERPROFILE%\.mcp-auth\
```
3. MCP クライアントを再起動する
### 7.4 Python ImportError
**症状**: ガードサーバー起動時に `ModuleNotFoundError: No module named 'config'` 等が発生する。
**原因**: ディレクトリ名 `mcp-local-server` にハイフンが含まれており、Python がモジュールとして認識できない。
**対処**: この問題は `server.py` 内の `sys.path` 操作で対処済みです。エラーが発生する場合は、仮想環境が有効になっているか確認してください:
```powershell
.venv\Scripts\Activate.ps1
```
### 7.5 pip アップグレードでファイルロック
**症状**: `pip install --upgrade pip` 実行時に `OSError: [WinError 32]` が発生する。
**原因**: Windows 環境で pip が自身を更新しようとした際に、ファイルがロックされる。
**対処**: **pip のアップグレードはスキップしてください。** 必須ではありません。依存パッケージのインストールは pip のバージョンに関係なく動作します。
---
## 8. 期待値の制御 -- できること・できないこと
### 8.1 できること
| 操作 | 担当サーバー | 説明 |
|:---|:---|:---|
| ポートフォリオ一覧・詳細の閲覧 | 公式 MCP | |
| プロジェクト一覧・詳細の閲覧 | 公式 MCP | |
| タスクの検索・詳細の閲覧 | 公式 MCP | |
| ユーザー情報の取得 | 公式 MCP | |
| ステータス概要の取得 | 公式 MCP | |
| プロジェクトの新規作成 | 公式 MCP | |
| タスクの新規作成 | 公式 MCP | |
| タスクの更新（名前変更、完了マーク等） | 公式 MCP | |
| タスクの安全な削除（二段階確認付き） | ガード MCP | プレビュー → 承認 → 実行 |
| プロジェクトの安全な削除（二段階確認付き） | ガード MCP | プレビュー → 承認 → 実行 |
| 全操作の監査ログ記録 | ガード MCP | JSONL 形式で記録 |
### 8.2 できないこと / 現在の制約
- **一括操作のドライラン**: 未実装。将来対応予定。
- **命名規則の自動強制**: ポリシーファイル (`configs/naming_rules.yaml`) は存在するが、チェックロジックは未実装。
- **Asana の全機能カバー**: カスタムフィールド操作、添付ファイル管理、コメント投稿等は現時点では限定的。
- **AI の判断ミスの完全排除**: 二段階確認で削除の誤操作は防止しているが、AI が指示を誤解するリスクはゼロではない。
### 8.3 「AI が勝手にやる」わけではない
重要な点として、MCP を導入しても **AI が自律的にタスクを操作するわけではありません**。
- AI は「あなたの指示に基づいて」操作を実行します
- 指示がない限り、AI が勝手にタスクを作成したり削除したりすることはありません
- 削除操作には必ず人間の承認が必要です
- 曖昧な指示を出すと、AI が意図しない操作を行う可能性があります。**指示は具体的に** 出してください
---
## 9. 今後の展望
### 9.1 短期（3ヶ月以内）
- **命名規則チェックの実装**: プロジェクトやタスクの命名がポリシーに準拠しているかを自動チェックする機能
- **一括操作のドライラン**: 実行前に影響範囲を一覧表示し、確認後に実行する機能
### 9.2 中期（6ヶ月以内）
- **コンテナ化 (Docker)**: ローカル環境依存を排除し、チーム全員が同じ環境で即座に利用可能にする
- **他サービスへの横展開**: Jira、Slack、Google Drive 等の MCP ガードサーバーを同じアーキテクチャで構築
### 9.3 長期
- **CI/CD パイプライン**: E2E テストの自動実行による品質保証
- **社内サーバー/クラウドへの移行**: ローカル実行からチーム共有の実行基盤への移行
---
*End of Guide*
