da-mcp

Document Authoring (DA) 用のリモート Model Context Protocol (MCP) サーバーです。このサーバーは、Claude や ChatGPT などの LLM アシスタントに DA 管理操作への直接アクセスを提供します。

特徴

• 10 DA Admin Tools: DA リポジトリを管理するための完全なツールセット

• リモートアクセス: Cloudflare Workers にデプロイ可能で、グローバルエッジ配信に対応

• Streamable HTTP: リモートサーバー向けの最新 MCP トランスポートプロトコル

• Token Pass-through: Authorization ヘッダーで DA API トークンを渡すシンプルな認証方式

• 本番環境対応: エラーハンドリング、ロギング、CORS サポート、ヘルスチェックを搭載

• TypeScript: 信頼性と保守性を高める完全型付けのコードベース

Related MCP server: Core Content Services MCP Server

アーキテクチャ

┌─────────────────┐
│   MCP Client    │
│ (Claude/Cursor) │
└────────┬────────┘
         │ Streamable HTTP
         │ + DA Token
         ↓
┌─────────────────────────┐
│  DA MCP                 │
│  ┌──────────────────┐   │
│  │   MCP Server     │   │
│  │   (10 Tools)     │   │
│  └──────────────────┘   │
└───────────┬─────────────┘
            │ HTTPS + Token
            ↓
┌─────────────────────────┐
│  DA Admin API           │
│  (admin.da.live)        │
└─────────────────────────┘

プロジェクト構造

src/
├── index.ts              # Cloudflare Worker entry point
├── mcp/
│   ├── server.ts         # MCP server initialization
│   ├── tools.ts          # Tool definitions (schemas)
│   └── handlers.ts       # Tool implementation handlers
└── da-admin/
    ├── client.ts         # DA Admin API client
    └── types.ts          # TypeScript types

利用可能なツール

前提条件

• Node.js 18+ と npm

• Cloudflare アカウント（無料枠で利用可能）

• Wrangler CLI がインストールされていること（npm install -g wrangler）

• DA Admin API トークン

インストール

1. リポジトリをクローンして依存関係をインストール：

git clone <repository-url>
cd da-mcp
npm install

2. Wrangler を設定：

必要に応じて wrangler.toml を編集し、デプロイ設定をカスタマイズします。

開発

ローカル開発

ホットリロード付きでサーバーをローカル実行：

npm run dev

サーバーは http://localhost:8787 で利用できます。

テストエンドポイント

• ヘルスチェック： http://localhost:8787/health

• MCP エンドポイント： http://localhost:8787/mcp

MCP Inspector でのテスト

1. ローカルサーバーを起動：npm run dev

2. MCP Inspector を開く

3. 接続を設定：

   • タイプ：Streamable HTTP

   • URL：http://localhost:8787/mcp

   • ヘッダー：Authorization: Bearer YOUR_DA_TOKEN

デプロイ

Cloudflare Workers にデプロイ

# Deploy to production
npm run deploy

# Or deploy to development environment
wrangler deploy --env development

パブリック URL

デプロイ後、MCP サーバーは次の URL でアクセスできます：

• ダイレクト MCP エンドポイント：
  https://da-mcp.adobeaem.workers.dev/mcp

• AEM API ルーター経由の IMS 認証：
  https://mcp.adobeaemcloud.com/adobe/mcp/da
  （Adobe IMS ログインに対応。詳細は下記の 認証 セクションを参照してください。）

クライアント設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または同等の場所に追加：

{
  "mcpServers": {
    "da-live-admin": {
      "type": "streamable-http",
      "url": "https://da-mcp.adobeaem.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DA_USER_IMS_TOKEN"
      }
    }
  }
}

VS Code / Cursor

.vscode/mcp.json または Cursor の設定に追加：

{
  "mcpServers": {
    "da-admin-mcp-direct": {
      "url": "https://da-mcp.adobeaem.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DA_USER_IMS_TOKEN"
      }
    },
    "da-prod-mcp": {
      "url": "https://mcp.adobeaemcloud.com/adobe/mcp/da"
    }
  }
}

認証

サーバーはシンプルなトークンパススルー認証を使用します：

1. クライアントが Authorization ヘッダーで DA Admin API トークンを送信

2. サーバーがトークンを抽出して DA Admin API に渡す

3. DA Admin API へのすべてのリクエストでこのトークンを使用

Authorization ヘッダーの形式：

Authorization: Bearer YOUR_DA_USER_IMS_TOKEN

または単に：

Authorization: YOUR_DA_USER_IMS_TOKEN

注： API ルーターのパブリック（認証付き）URL 経由で API にアクセスする場合、IMS（Adobe Identity Management Service）ログインは AEM API ルーターによって自動的に処理されます。この場合、Authorization ヘッダーで DA Admin API トークンを提供する必要はありません。IMS ログインフローが認証を提供します。

使用例

設定が完了すると、AI アシスタントに DA 操作を依頼できます：

Claude, can you list all the sources in the adobe/my-docs repository?

Please get the content of docs/index.md from the adobe/my-docs repository.

Create a new file at docs/new-page.md with some markdown content.

API エンドポイント

GET /health

サーバーのステータスを返すヘルスチェックエンドポイント。

レスポンス：

{
  "status": "healthy",
  "service": "da-mcp",
  "version": "1.0.0",
  "environment": "production",
  "timestamp": "2025-01-07T12:00:00.000Z"
}

POST /mcp

ツール実行のための MCP プロトコルエンドポイント。DA Admin API トークンを含む Authorization ヘッダーが必要です。

エラーハンドリング

すべてのツールに包括的なエラーハンドリングが含まれています：

• 401 Unauthorized：DA Admin トークンが欠落しているか無効

• 404 Not Found：無効なエンドポイント

• 408 Timeout：リクエストが 30 秒以上かかった

• 500 Internal Error：詳細を含むサーバー側エラー

エラーは LLM クライアントが理解しやすい形式で整形されます。

ロギング

サーバーは重要なイベントとエラーを Cloudflare Workers ログに記録します：

# View logs in real-time
wrangler tail

# View logs for specific environment
wrangler tail --env production

モニタリング

デプロイした Worker を監視：

1. Cloudflare Dashboard：呼び出し、エラー、パフォーマンスを表示

2. Wrangler Tail：リアルタイムログ（wrangler tail）

3. ヘルスエンドポイント：/health での定期的なヘルスチェック

コントリビューション

コントリビューションを歓迎します！以下の手順でお願いします：

1. リポジトリをフォーク

2. フィーチャーブランチを作成

3. テストを含む変更を加える

4. プルリクエストを送信