ツールアーキテクチャ概要

BluePeriodのAIエージェント（内製・MCP）で使用されるツールの定義場所と構造を説明します。

1. ツールの二層構造

BluePeriodのツールは、役割に応じて2つの場所に定義されています：

next-app/src/
├── ai/agents/tools/          # エージェント汎用ツール（インフラ）
└── lib/features/*/tools.ts   # Feature層ツール（ビジネスロジック）

2. エージェント汎用ツール (ai/agents/tools/)

役割: エージェントのインフラストラクチャに関わる機能。Feature層には属さない汎用的な機能。

計9ツール

これらはFeature（プロジェクト・執筆等）とは無関係な、エージェント自体の動作に必要な機能です。

3. Feature層ツール (lib/features/*/tools.ts)

役割: BluePeriodの機能（プロジェクト、執筆、キャラクター等）に関わるツール。

3.1. Projects (lib/features/projects/tools.ts)

計8ツール

3.2. Editorial - Plot (lib/features/editorial/tools/plot-tools.ts)

計8ツール

3.3. Editorial - Manuscript (lib/features/editorial/tools/manuscript-tools.ts)

計5ツール

3.4. Editorial - Writing Prompts (lib/features/editorial/tools/writing-prompt-tools.ts)

計7ツール

3.5. Characters (lib/features/characters/tools.ts)

計7ツール

3.6. Prompt Assets (lib/features/prompts/asset-tools.ts)

計7ツール

3.7. Chat - Artifacts (lib/features/chat/artifact-tools.ts)

計8ツール

3.8. System (lib/features/system/tools.ts)

計2ツール

3.9. Published Projects (lib/features/projects/publishedTools.ts)

Published作品（Explore/公開済みプロジェクト）の読み取り専用ツール。Supabaseのpublished_projectsテーブルにアクセスし、getDisplayMetadata / getDisplayTags / getLocalizationLanguagesによる多言語対応を内蔵する。HITL（Human-in-the-Loop）確認は不要。

計4ツール

4. 統合方法

4.1. Feature層ツールの統合

lib/features/editorial/tools/index.ts で全てのFeature層ツールが統合されます：

export const createEditorialTools = (get: Getter, set: Setter, t: TFunction, toastFn: typeof toast) => {
  return [
    ...createPlotTools(get, set, t, toastFn),
    ...createManuscriptTools(get, set, t, toastFn),
    ...createWritingPromptTools(get, set),
    ...createCharacterTools(get, set),
    ...createProjectTools(get, set),
    ...createPromptAssetTools(get, set),
    ...createSystemTools()
  ];
};

4.2. 内製エージェントでの使用

ai/agents/assistantGraph.ts でエージェント汎用ツールとFeature層ツールが結合されます。用途別にツールセットが分割されており、generalTools（artifact操作のみ）と writingToolsFull（執筆ツールを含むフルセット）があります。

4.3. MCPブリッジでの使用

hooks/useMcpBridge.ts が外部MCPリクエストを受け付け、Service層のメソッドを呼び出します。MCPブリッジはビジネスロジックを持たず、Service呼び出しのみを行う薄いディスパッチャとして機能します。

5. ツール数の合計

6. 命名規則

6.1. blueperiod_ プレフィックス

Feature層ツールはMCPとの互換性のため、全て blueperiod_ プレフィックスを持ちます。

6.2. ツール名フォーマット

Feature層ツールの命名は blueperiod_<operation>_<domain>[_<format>] パターンに従います：

• operation: list, get, create, update, edit, delete, toggle
• domain: plot, manuscript, writing_prompt, character, prompt_asset, artifact, project, published_project, global_store
• format: structured（Adit JSONパッチ）, delimiter（SEARCH/REPLACEブロック）

6.3. エージェント汎用ツール

プレフィックスなし（web_search, finish_task 等）

7. 新しいツールの追加方法

7.1. Feature層ツールを追加する場合

1. 対応するFeatureディレクトリの tools.ts にDynamicStructuredTool定義を追加
2. Service層にビジネスロジックメソッドを追加
3. lib/features/editorial/tools/index.ts に統合（必要な場合）
4. MCPブリッジ（useMcpBridge.ts）にcase文を追加

7.2. エージェント汎用ツールを追加する場合

1. ai/agents/tools/ に新しいツールファイルを作成
2. ai/agents/assistantGraph.ts でインポートして使用

関連ドキュメント:

• 12_ai_agent_architecture - 内製エージェントのアーキテクチャ
• 18_agent_tool_integration_guide - ツール統合ガイド
• 19_mcp_architecture - MCPアーキテクチャ