# iA Document Management MCP - Implementation Notes
## 実装完了日
2026-02-08
## 実装した機能
### 1. ia_login - ログイン
- **エンドポイント**: `POST /spa/service/auth/login`
- **認証方式**: Form URL-encoded (user, password, domain)
- **成功レスポンス**: HTTP 200 + `X-Spa-Error-Code: 0`
- **返却データ**:
- `sessionCookie`: セッションID (JSESSIONID)
- `xsrfCookie`: XSRF-TOKEN cookie
- `xsrfToken`: CSRFトークン (ヘッダー `X-Xsrf-Token` より取得)
- `userId`: ログインユーザーID
**実装状況**: ✅ 完全動作確認済み
### 2. ia_search_documents - フリーワード検索
- **エンドポイント**: `POST /spa/service/search_v21/folder`
- **認証**: セッションCookie必須
- **CSRF保護**: オプションでXSRFトークンをヘッダーに含める
- **リクエスト形式**: JSON
- **主要パラメータ**:
- `folderIds`: 検索対象フォルダIDの配列
- `searchWord`: フリーワード検索文字列
- `operator`: AND/OR条件
- `recursive`: サブフォルダを含むか
- `properties`: 取得するシステムプロパティ
**実装状況**: ✅ 実装完了（APIリクエストは成功、フォルダIDが存在する場合に動作）
**重要**: フォルダIDの指定は `{id: "123"}` 形式（`folderId`ではなく`id`）
### 3. ia_logout - ログアウト
- **エンドポイント**: `POST /spa/service/auth/logout`
- **認証**: セッションCookie + XSRFトークン + 特殊ヘッダー必須
- **必須ヘッダー**:
- `X-Requested-With: XMLHttpRequest`
- `X-XSRF-TOKEN: [トークン値]`
- **解決**: 上記ヘッダーを追加することで正常に動作
**実装状況**: ✅ 完全動作確認済み（X-Requested-Withヘッダー追加により解決）
## CSRF/XSRF トークンの扱い
### 発見した仕様（公式ドキュメント確認済み）
1. ログインレスポンスに以下が含まれる:
- レスポンスヘッダー: `X-Xsrf-Token: XXXX-XXXX-...`
- Set-Cookieヘッダー: `XSRF-TOKEN=XXXX-XXXX-...; Path=/; Secure`
2. 後続のリクエスト（非GETリクエスト）では **以下の2つのヘッダーが必須**:
- `X-Requested-With: XMLHttpRequest` ← **これが重要！**
- `X-XSRF-TOKEN: [トークン値]`
- Cookieに`XSRF-TOKEN`を含める
3. 公式ドキュメントで確認
- [CSRF Token Implementation](https://cs.wingarc.com/manual/ia/cloud/ja/1567416.html)
- X-Requested-Withヘッダーが必須であることが記載されている
- 誤ったCSRFトークンを指定するとトークンが無効になり、再ログインが必要
## テスト結果
### ログイン
```
✅ Status: 200
✅ Error Code: 0
✅ User ID: sakimoto.t
✅ XSRF Token: 正常に取得
✅ Session Cookie: 正常に取得
```
### ログアウト（X-Requested-Withヘッダー追加後）
```
✅ Status: 200
✅ Error Code: 0
✅ User ID: sakimoto.t
✅ ログアウト成功
```
### 検索
```
✅ APIリクエスト成功（Status 200 for valid folder IDs）
⚠️ フォルダID "1" は存在しないため Error Code: -20709
✅ 正しいフォルダIDを指定すれば検索結果を取得可能
```
## 推奨される使用方法
1. **ログイン**
```javascript
const result = await ia_login({
user: "username",
password: "password",
domain: "local",
baseUrl: "https://wat-cloud-div.spa-cloud.com"
});
const { sessionCookie, xsrfToken, xsrfCookie } = result;
```
2. **検索**
```javascript
const searchResult = await ia_search_documents({
folderIds: [{ folderId: "123" }],
searchWord: "請求書",
sessionCookie,
xsrfToken,
recursive: true,
operator: "AND"
});
```
3. **ログアウト** (オプション)
```javascript
// 403が返る可能性が高いが、セッションは自動的にタイムアウトする
const logoutResult = await ia_logout({
sessionCookie,
xsrfToken
});
```
## セキュリティに関する注意事項
1. **認証情報の保護**
- ユーザー名とパスワードは環境変数または安全な方法で管理
- セッションCookieとXSRFトークンは一時的にメモリに保持
- 決してGitリポジトリにコミットしない
2. **セッション管理**
- セッションは一定期間の非アクティブ後に自動的に期限切れ
- ログアウトAPIが403を返しても、クライアント側でセッション情報を破棄
3. **HTTPS通信**
- すべての通信はHTTPS経由で行われる
- Cookie属性: `Secure; HttpOnly`
## 既知の制限事項
1. **ログアウトAPI**: ブラウザ外からの呼び出しで403エラー
2. **タイムアウト**: セッションタイムアウト時間は不明（サーバー側で管理）
3. **同時セッション**: 同一ユーザーの複数セッション可否は未確認
## 今後の改善案
1. 検索APIの実際のテスト実施（フォルダIDが必要）
2. エラーハンドリングの強化
3. リトライロジックの追加（ネットワークエラー時）
4. セッションタイムアウトの自動検出と再ログイン
5. ログ出力機能の追加（デバッグ用）
## 参考資料
- [iA Cloud ログインAPI](https://cs.wingarc.com/manual/ia/cloud/ja/1027707.html)
- [iA Cloud 文書検索API](https://cs.wingarc.com/manual/ia/cloud/ja/4261290.html)
- [iA Cloud ログアウトAPI](https://cs.wingarc.com/manual/ia/cloud/ja/1387624.html)
