🔍 🤖 🌐 Ollama Chat with MCP

🔍 🤖 🌐 Osoba

ローカルおよびホスト型の LLM と、インテリジェントなウェブ検索およびコンテンツ抽出、SQL、YouTube の文字起こし分析、HubSpot のアクション、Python によるデータ分析、Canva でのデザイン作成、Figma のデザイン検査、Poe によるマルチモデル AI（テキスト、画像、動画、音声の生成）、安全なコードのひな形作成を行う Codex MCP サーバーを Model Context Protocol（MCP）経由で統合する、強力でモダンな UI です。ユーザープロファイルと会話コンテキストを通じたパーソナライズされた AI アシスタンス、永続的な参照資料のためのドキュメントナレッジベース、プロバイダー設定、複数プロバイダーのモデル選択、ストリーミングチャット、会話の永続化、堅牢なタスクシステム、タイムゾーンを考慮したスケジュールタスクなどの機能を備えています。

概要

Osoba は、MCP ツールの利用を通じて、ローカルモデルとホスト型モデルの両方を拡張する方法を紹介します。Ollama でローカル実行する LLM に、インテリジェントなウェブ検索とコンテンツ抽出、SQL クエリ、YouTube の文字起こしの取り込み、HubSpot のビジネスアクション、Python ベースの CSV 分析／可視化、Canva デザインの作成とエクスポート、Figma ファイル／デザインの検査とエクスポート、テキストチャットとメディア生成（画像、動画、音声）に対応する Poe のマルチモデル AI、さらに隔離されたワークスペース内でコードを生成する Codex Workspace サーバーを組み合わせています。マルチプロバイダー層では、OpenAI、Anthropic、Google、OpenRouter、Groq、SambaNova を追加しています。会話とタスクは MongoDB に永続化されます。

このプロジェクトは、次の主要なコンポーネントで構成されています。

• バックエンド（FastAPI）：チャットロジック、モデルプロバイダーのルーティング、MCP サービスとの通信（ウェブ検索、SQL、YouTube、HubSpot、Python、Canva、Figma、Poe、Codex などの MCP サービスの起動と管理を含む）、タスク／スケジューラー、永続化を管理します。

• フロントエンド（React）：ユーザーがチャットアプリケーションを操作するための、モダンでレスポンシブなウェブインターフェースです。

• MCP Smart Web Search Server モジュール：Serper.dev API を使用したインテリジェントなウェブ検索と、上位の検索結果からの自動コンテンツ抽出を提供します。URL の優先順位付け、robots.txt の遵守、礼儀正しいクローリングの実践を伴う、複数の手法によるコンテンツ抽出（trafilatura、BeautifulSoup）を使用します。

• MCP SQL Server モジュール：MySQL データベースに対する読み取り専用クエリを実行します（スキーマリソースとクエリの安全対策を含む）。

• MCP YouTube Transcript Server：複数の方法（youtube-transcript-api、Pytube、yt-dlp）を使用して堅牢に文字起こしを取得し、必要に応じてプロキシにも対応します。その後、フォローアップ用に文字起こしのコンテキストを会話に保存します。

• MCP HubSpot Business Tools：OAuth を使用した HubSpot API 経由で、JSON を優先するプロンプトフローによりマーケティングメールを作成／更新します。

• MCP Python Data Analysis Server：CSV の読み込み、データのプロファイリング、フィルタリング、グループ化／集計、外れ値の検出、データ型変換、統計的仮説検定、可視化（base64 画像）など、分析ワークフロー全体に対応する包括的なデータ分析ツールキットです。

• MCP Canva Design Server：チャットや自律型タスクから直接、Canva デザインの作成、閲覧、エクスポート、インポート、サイズ変更、自動入力を行います。標準サイズのプリセット（Instagram、YouTube、プレゼンテーションなど）、カスタム寸法、ブランドテンプレートの自動入力（Enterprise）、アセットのアップロード、デザインのインポート（PDF/PPTX/DOCX/PSD）、PNG、JPG、PDF、PPTX、SVG、MP4、GIF へのエクスポートに対応しています。Canva Connect API のアクセストークン（OAuth 2.0）が必要です。

• MCP Figma Design Server：チャットやタスクから、Figma ファイルの読み取り、特定ノードの抽出、フレームやコンポーネントの画像（PNG/JPG/SVG/PDF）へのエクスポート、コメントの管理、デザインシステム全体（カラートークン、タイポグラフィ、間隔、コンポーネント）の抽出を行います。Figma Personal Access Token が必要です。

• MCP Poe AI Models Server：単一の OpenAI 互換 API を通じて、Poe プラットフォーム上の数百種類の AI モデルを利用できます。最先端の LLM（Claude、GPT、Gemini、Grok、Llama）によるテキスト生成、GPT-Image-1.5、Flux、Stable Diffusion などのモデルによる画像生成（アスペクト比の制御に対応）、動画や音声の生成を、チャットやタスクから行えます。Poe API キーが必要です。

• MCP Codex Workspace Server：実行ごとにワークスペースを作成し、隔離されたディレクトリ内で Codex CLI を起動します。アーティファクト（JSONL イベント、マニフェスト）を永続化し、設定可能な出力ポリシーを適用して、ストリーミングに適した UX を実現する非同期実行 API を提供します。有効な OpenAI API キーが必要です。

• MongoDB：会話履歴とユーザーデータを保存します。

このアーキテクチャは、MCP によってローカルモデルが外部のツールやデータソースにアクセスできるようになり、その機能が大幅に強化されることを示しています。バックエンドがすべての MCP サービスを起動・監督し、スケーラブルで機能豊富な構成を実現します。

機能

• 🧠 スマートウェブ検索：上位の検索結果からコンテンツを自動抽出する、インテリジェントなウェブ検索です。検索スニペットにとどまらず、高度な抽出手法を用いてウェブページ全体を取得・分析します。
• 🔎 URL の優先順位付け：関連性スコアに基づいて検索結果をスマートに順位付けします。タイトル／スニペットとの一致度、ドメインの権威性、検索順位の重み付けなどを考慮します。
• 🤖 配慮あるウェブクローリング：robots.txt を尊重し、レート制限を実装し、倫理的なコンテンツ抽出のために適切な User-Agent を使用します。
• 👤 ユーザープロフィールとコンテキスト：個人情報（役割、専門知識、プロジェクト）を設定し、会話をピン留めしてコンテキストに応じた AI アシスタンスを受けられます。AI はユーザーの背景を理解し、過去の作業を参照して、個人に合わせた回答を提供します。
• 🎯 目標と優先事項：構造化されたドキュメント（最大 2000 文字）で、短期・中期・長期の目標を定義し、AI が目標を理解して適切なアシスタンスを提供できるようにします。
• 🔔 プロアクティブなエージェントのハートビート：コンテキストの収集（セマンティックメモリー、git、プロジェクトファイル、システムの状態）、タスクの自動作成、ファイルベースの設定（HEARTBEAT.md）を備えた、強化されたバックグラウンドサービスです。実行間隔やコンテキストソースを設定でき、ファイルと UI の双方向同期にも対応します。
• 📌 会話のピン留め：今後のチャットのコンテキストに含める会話を選択できます。これにより、AI は過去のやり取りを基に内容を発展させ、セッション間の一貫性を保てます。
• 🧠 セマンティックメモリー：ChromaDB と nomic-embed-text の埋め込みを利用した、インテリジェントなセマンティック検索機能付きの無制限の会話保存です。5 件以上のメッセージがある会話を自動でインデックス化し、キーワードではなく意味に基づいて検索して、関連する過去の会話を新しいチャットに挿入します。会話履歴の検索と管理には、メモリーブラウザー（Ctrl+Shift+M）を利用できます。
• 📚 ドキュメントナレッジベース：PDF、Word ドキュメント、Markdown ファイル、プレーンテキスト、ウェブ URL を、永続的な参照資料としてアップロードできます。ドキュメントはチャンクに分割され、埋め込みが生成されて、専用の ChromaDB コレクションに保存されます。関連するドキュメントのスニペットは、セマンティックメモリーとともに、すべてのチャットに自動で挿入されます。Ctrl+Shift+K またはヘッダーの「KB」ボタンから開けます。
• 🧾 AI チャットの要約（オンデマンド）：LLM が作成する簡潔な要約を会話ごとに生成し、ピン留めしたチャットのコンテキストとして使用できます（ヒューリスティックは使用しません）。要約はユーザーが明示的に実行し、設定でモデルを選択できます。ピン留めできるチャットは最大 5 件です。
• 🎯 パーソナライズされた AI の回答：プロフィール情報とピン留めした会話履歴に基づいて AI がコミュニケーションスタイルや提案を調整し、より適切なアシスタンスを提供します。
• 💾 会話の永続化：チャット履歴は MongoDB に保存されるため、会話を再開できます。
• 🧠 複数プロバイダーの LLM：Ollama（ローカル）に加え、OpenAI、Anthropic、Google、OpenRouter、Groq、SambaNova に対応しています。API キー設定画面と統合モデルピッカーを備えています。
• 🔌 MCP 統合：バックエンドは、複数の MCP ツール（ウェブ、SQL、YouTube、HubSpot、Python）をバックグラウンドサービスとして管理します。
• 💻 モダンなウェブインターフェース：React で構築された、レスポンシブでインタラクティブなユーザー体験を提供します。
• 📊 構造化された検索結果：最適なコンテキストを得られるよう、ウェブ検索データを見やすく整形します。
• 🌐 強化されたコンテンツ抽出：trafilatura と BeautifulSoup を用いた複数の抽出方法と、信頼性を最大限に高めるためのフォールバック機能を備えています。
• ⚙️ バックエンド API：チャットと会話管理のための堅牢な API エンドポイントを提供する FastAPI バックエンドです。
• 🗃️ SQL クエリツール：スキーマのイントロスペクションとリトライロジックを備えた、読み取り専用の MySQL クエリ機能です。
• 🔄 会話管理：会話の一覧表示、名前変更、削除ができます。
• 📺 YouTube 文字起こしツール：YouTube の URL を貼り付けると、文字起こしが取得・保存され、複数ターンにわたるフォローアップに利用できます。
• 🧰 HubSpot ツール：OAuth で接続し、ガイド付きの JSON プロンプトを使ってマーケティングメールを作成・更新できます。
• 🐍 Python 分析ツール：CSV をアップロードして、データプロファイリング、フィルタリング、グループ化、外れ値検出、統計検定、型変換、可視化などの包括的な分析を実行できます。結果は画像と詳細な分析情報とともにストリーミングされます。
• ⚡ ストリーミング応答：フロントエンドでモデルの出力をトークンごとに表示し、ツールの使用状況も示します。
• 🗓️ 長時間実行タスク（計画と実行）：予算、リトライ、検証の機能を備え、複数ステップのワークフローを計画・実行する自律型タスクを作成できます。
• 📈 タスクの進行状況をリアルタイム表示：タスクの進行状況は SSE でストリーミングされ、各ステップの出力（表／画像／テキスト）は UI に表示されます。
• 🧩 LLM のみのステップ（MCP 不使用）：MCP ツールを使わずに、Ollama 上で直接実行するステップ（要約や推論など）をタスクに含められます。
• 🚦 優先度付きタスクキュー：メモリーを安全に管理しながらタスクを実行し、優先順位に従ってスケジュール済みタスクを先に実行し、ユーザーのタスクをその後にキューへ追加します。システムの過負荷を防ぐため、一度に実行するタスクは 1 件のみです。特に、ローカルで実行するメモリー容量に制約のあるシステムで重要です。
• 🎨 Canva デザインツール（MCP）：標準プリセット（Instagram、YouTube サムネイル、プレゼンテーション、A4 など）やカスタムサイズを使って、チャットまたはタスクから Canva デザインを作成できます。既存のデザインの参照、アセットのアップロード、ファイル（PDF／PPTX／DOCX／PSD）の編集可能なデザインへのインポート、さまざまなプラットフォーム向けのデザインのサイズ変更、ブランドテンプレートへの自動入力、PNG、JPG、PDF、PPTX、SVG、MP4、GIF へのエクスポートに対応しています。すべて Osoba から離れずに利用できます。Canva Connect API アクセストークンが必要です。
• 🖼️ Figma デザインツール（MCP）：Figma ファイルの構造の読み取り、ID による特定のノードの抽出、フレームやコンポーネントの画像へのエクスポート、コメントの一覧表示と投稿、デザインシステム全体（カラー、タイポグラフィ、スペーシングのトークンとコンポーネントカタログ）の抽出ができます。デザインレビューのワークフロー、デザインからコードへの引き継ぎ、自動デザイン監査に役立ちます。Figma Personal Access Token が必要です。
• 🤖 Poe AI モデル（MCP）：Poe プラットフォームを通じて数百種類の AI モデルを利用できます。最先端の LLM によるテキスト生成、GPT-Image-1.5、Flux、Stable Diffusion による画像生成（9:16／16:9 のアスペクト比を指定可能）、動画や音声の生成に対応しています。チャットまたは自律型タスクから利用できます。Poe API キーが必要です。
• ✨ Codex ワークスペース（MCP）：Codex を起動し、分離されたワークスペースでファイルを生成・編集できます。チャット内に実行状況が表示され、成果物はレビュー用に保存されます。利用には OpenAI キーが必要です。
• 🗓️ スケジュールタスク（タイムゾーン対応）：ローカルタイムゾーンに基づき、夏時間にも安全に対応した繰り返しの cron または 1 回限りのスケジュールを設定できます。1 回限りのスケジュールは初回実行後に自動で無効になります。モデルを上書きして「今すぐ実行」することもできます。

タスク実行とメモリ管理

タスクシステムの MCP ツールへのアクセス

タスクシステムは、チャットインターフェースで利用可能なすべての MCP ツールに完全にアクセスできるため、複雑なワークフローを自律的に実行できます。

利用可能なツール（合計 55 個）：

• ウェブ検索（5 個のツール）：基本検索、スマートコンテンツ抽出、画像検索、ニュース検索、URL 直接取得
• Python データ分析（17 個のツール）：データの読み込み、検査、クリーニング、変換、統計分析、可視化
• Canva デザイン（10 個のツール）：デザインの作成、デザイン一覧の取得、デザイン詳細の取得、ファイルへのエクスポート、アセットのアップロード、ブランドテンプレートへの自動入力、テンプレートフィールドの取得、デザインのインポート、デザインのサイズ変更、デザインページの取得
• Figma デザイン（6 個のツール）：ファイル構造の取得、ノードの取得、画像のエクスポート、コメント一覧の取得、コメントの投稿、デザインシステムの抽出
• Poe AI モデル（5 個のツール）：モダリティ別のモデル一覧、テキストチャット、画像生成（アスペクト比指定）、動画生成、音声生成
• HubSpot ビジネス（2 個のツール）：マーケティングメールの作成／更新（OAuth が必要）
• Codex ワークスペース（7 個のツール）：コード生成とワークスペース管理（OpenAI API キーが必要）
• データベース（1 個のツール）：読み取り専用の SQL クエリ
• YouTube（1 個のツール）：文字起こしの抽出
• LLM 専用（1 個のツール）：推論ステップ向けの LLM 直接生成

高度なタスク機能：

• スマートコンテンツ抽出による調査（スニペットだけでなく、ウェブページ全体のコンテンツを取得）
• 外れ値検出と統計的仮説検定を用いた高度なデータ分析
• Canva デザインのワークフロー：トピックを調査し、デザインを自動的に作成してエクスポート
• Figma デザインのワークフロー：デザイントークンの抽出、アセットのエクスポート、デザインからコードへの引き継ぎに向けたファイル構造の確認
• Poe AI のワークフロー：アスペクト比を指定して画像を生成し、Canva にアップロードするか、複数ステップのクリエイティブなパイプラインで使用
• HubSpot との統合によるマーケティングの自動化
• Codex ワークスペースのきめ細かな管理によるコード生成
• 検索、分析、デザイン、生成を組み合わせた複数ステップのワークフロー
• KB コンテキストの添付：タスクの作成時にインデックス化されたナレッジベースのドキュメントを 1～2 件添付し、参考資料をプランナーとすべての LLM ステップに取り込みます

優先度キューシステム

このアプリケーションは、システムの安定性を確保し、複数の LLM インスタンスによるメモリの過負荷を防ぐため、優先度ベースのタスクキューを使用します。

• 優先度 1（最高）：スケジュール済みタスクが常に最初に実行されます
• 優先度 2（標準）：ユーザーが作成したタスクは、スケジュール済みタスクの後にキューに入ります
• 一度に 1 つのタスク：メモリ不足によるクラッシュを防ぐため、同時に実行されるタスクは 1 つだけです
• キュー内の位置：ユーザーにはキュー内の順番が通知されます

メモリの安全性

• 過負荷を防止：複数の LLM インスタンスを同時に実行すると（例：Llama3.1 8B を 3 つ実行すると 24 GB）、RAM が限られたシステムがクラッシュする可能性があります
• 安全な実行：タスクを 1 つずつ実行することで、メモリ使用量をシステムの制限内に保ちます
• 自動キューイング：別のタスクの実行中にタスクが自動的にキューに入ります

タスクのスケジュール設定

• Cron ベースのスケジュール設定：柔軟なスケジュール設定に標準の cron 式を使用します
• システム要件：スケジュール済みタスクは、システムが起動しており、アプリケーションが実行中の場合にのみ実行されます
• 未実行タスクの実行：システムの復帰時に、期限を過ぎたタスクが直ちに実行されます

スケジュールタスクの信頼性

キャッチアップロジック（デフォルト）： バックエンドが停止後に起動したとき、またはコンピューターがスリープから復帰したとき、期限を過ぎたスケジュールタスクはすぐに実行されます。5 分を超えて遅延したタスクには、実行がどれだけ遅れたかを示す警告インジケーターが UI に表示されます（例：「⚠️ Last run: 45m late」）。繰り返しタスクは、遅延が連鎖するのを防ぐため、現在時刻を基準に次回の実行時刻を計算します。

遅延の内訳： システムは、次の 2 種類の遅延を区別します。

• システム遅延（スリープ）：コンピューターがスリープしていた時間、またはバックエンドが停止していた時間
• キュー遅延（キュー待ち）：ほかのタスクの完了を待っていた時間

UI には内訳が表示されます：「⚠️ Last run: 15m late (sleep: 10m, queued: 5m)」。これにより、遅延の原因がシステムのスリープなのか、タスクキューの混雑なのかを確認できます。メモリの安全性を確保するため、一度に実行されるタスクは 1 つだけなので、システムの復帰後、キャッチアップタスクの後ろにタスクがキューイングされる場合があります。

サービスとしての実行（任意）： 確実な実行と自動起動のため、Osoba のバックエンドをシステムサービスとして実行できます。これにより、バックエンドが常に実行中の状態で維持され、スケジュールタスクを時間どおりに実行できるようになります。macOS（Launch Agent）、Linux（systemd）、Windows（NSSM）用のセットアップスクリプトが用意されています。詳しいセットアップ手順については、scripts/README.md を参照してください。

スリープ解除のスケジュール設定（上級者向け）： 対応するシステムでは、スケジュールタスクの実行時にコンピューターがスリープから復帰するように設定できます。管理者／root 権限が必要です。また、バッテリーへの影響があるため、主にデスクトップマシンや電源に接続している場合に推奨されます。プラットフォーム別の手順：

• macOS：pmset を使用してスリープ解除イベントをスケジュールします
• Linux：RTC スリープ解除を使用します（ハードウェアの対応が必要です）
• Windows：スリープ解除タイマーを設定したタスクスケジューラを使用します

スリープ解除のスケジュール設定とトラブルシューティングの詳細については、scripts/README.md を参照してください。

要件

• Python 3.11+
• フロントエンド用の Node.js（v18+）と npm/yarn
• ローカルにインストールされ、実行中の Ollama
• Serper.dev の API キー（無料枠あり）
• MongoDB インスタンス（ローカルまたはクラウド）
• MySQL サーバー（任意。SQL クエリツール用）
• ウェブ検索とパッケージのダウンロードに必要なインターネット接続

セマンティックメモリとドキュメントナレッジベース用：

• nomic-embed-text モデルを使用する Ollama：ollama pull nomic-embed-text
• ChromaDB、tiktoken、pdfplumber（requirements.txt 経由で自動的にインストールされます）

任意（追加ツールを有効にする場合）：

• スマートウェブ検索：trafilatura、beautifulsoup4、lxml（自動的にインストールされます）
• Python データ分析：pandas、numpy、matplotlib、seaborn
• YouTube の文字起こし：youtube-transcript-api、pytube、yt-dlp、requests
• HubSpot OAuth：有効な OAuth アプリ（クライアント ID／シークレット）とリダイレクト URL
• Canva デザイン：Canva Connect API アクセストークン（セットアップ手順を参照）
• Figma デザイン：Figma Personal Access Token（Figma Account Settings → Security → Personal access tokens から取得）
• Poe AI モデル：Poe API キー（poe.com/api/keys から取得。Poe のサブスクリプションが必要です）
• Codex ワークスペース：Codex CLI が PATH 上で利用可能（または CODEX_BIN を設定）、OpenAI API キーが設定済み

インストール

1. リポジトリをクローンします：

   git clone https://github.com/redbuilding/osoba.git
   cd osoba
   

2. バックエンドのセットアップ：

   • バックエンドディレクトリに移動します：

     cd backend
     

   • 仮想環境を作成して有効化します：

     python3 -m venv mcp
     source mcp/bin/activate  # On Windows: mcp\Scripts\activate
     

   • Python の依存関係をインストールします：

     pip install -r requirements.txt
     

   • backend ディレクトリに .env ファイルを作成します。バックエンドと、バックエンドが管理する MCP サービスは、このファイルから環境変数を読み込みます。プロバイダーの API キーを安全に保存するには、安定した暗号化キー（Fernet）を生成し、SETTINGS_ENCRYPTION_KEY に設定する必要があります：

     • インストール：pip install cryptography
     • 生成（いずれかを選択）：
       • python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
       • Python REPL で実行：from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())
     • キーを .env に貼り付けて、SETTINGS_ENCRYPTION_KEY=... と設定します

     
     # モデルプロバイダーの設定モーダルで入力した API キーを暗号化するための設定
     SETTINGS_ENCRYPTION_KEY=<paste_generated_fernet_key_here>
     
     # スマートウェブ検索用（server_search.py）
     SERPER_API_KEY=your_serper_api_key_here
     
     # スマート抽出の設定（任意）
     SMART_EXTRACT_MAX_URLS=3
     SMART_EXTRACT_MAX_CHARS_PER_URL=2000
     SMART_EXTRACT_MAX_TOTAL_CHARS=5000
     SMART_EXTRACT_REQUEST_DELAY=1.0
     
     # MongoDB 用（main.py）
     MONGODB_URI=mongodb://localhost:27017/
     MONGODB_DATABASE_NAME=mcp_chat_db
     
     # MySQL データベースへのクエリ用（server_mysql.py）
     DB_HOST=localhost
     DB_USER=your_db_user
     DB_PASSWORD=your_db_password
     DB_NAME=your_db_name
     
     # 任意：Canva デザインツール（backend/server_canva.py）
     # トークンの取得先：https://www.canva.com/developers/
     CANVA_API_TOKEN=your_canva_personal_access_token_here
     
     # 任意：Figma デザインツール（backend/server_figma.py）
     # Figma アカウント設定 → セキュリティ → 個人用アクセストークンからトークンを取得します
     FIGMA_ACCESS_TOKEN=your_figma_personal_access_token_here
     
     # 任意：Poe AI モデル（backend/server_poe.py）
     # https://poe.com/api/keys からキーを取得します（Poe のサブスクリプションが必要）
     POE_API_KEY=your_poe_api_key_here
     
     # 任意：HubSpot OAuth（backend/auth_hubspot.py）
     HUBSPOT_CLIENT_ID=your_hubspot_client_id
     HUBSPOT_CLIENT_SECRET=your_hubspot_client_secret
     HUBSPOT_REDIRECT_URI=http://localhost:8000/auth/hubspot/oauth-callback
     FRONTEND_URL=http://localhost:5173
     
     # 任意：YouTube 文字起こしサーバー（backend/server_youtube.py）
     # YTA_PROXY=https://user:pass@host:port
     # YTA_LOG_LEVEL=INFO
     
     # 任意：バックエンドのデフォルト設定
     DEFAULT_OLLAMA_MODEL=llama3.1
     OLLAMA_REPEAT_PENALTY=1.15
     
     # Codex MCP のデバッグ状態
     CODEX_DEBUG=false
     

   • 追加のツールを使用する場合は、任意の依存関係をインストールします：

     # スマートウェブ検索のコンテンツ抽出（推奨）
     pip install trafilatura beautifulsoup4 lxml
     
     # YouTube 文字起こしツール
     pip install youtube-transcript-api pytube yt-dlp requests
     
     # Python 分析ツール
     pip install pandas numpy matplotlib seaborn scipy
     

3. フロントエンドのセットアップ：

   • フロントエンドディレクトリに移動します：

     cd ../frontend
     

     （backend/ にいる場合は上記のコマンドを実行します。それ以外の場合は、プロジェクトのルートから cd frontend を実行してください）
   • Node.js の依存関係をインストールします：

     npm install
     # または
     # yarn install
     

   • 任意：カスタム API URL を指定する場合は、frontend/.env を作成します（デフォルトは http://localhost:8000/api です）：

     echo 'VITE_API_URL=http://localhost:8000/api' > .env
     

4. Ollama がインストールされ、モデルを利用できることを確認します： アプリケーションでは、特定のモデル（例：llama3.1）がデフォルトに設定されている場合があります。使用するモデルをプルします：

   ollama pull llama3.1
   # or your preferred model like llama3, mistral, etc.
   

   モデルは UI で選択するか、バックエンドの .env ファイルで DEFAULT_OLLAMA_MODEL を設定してデフォルトを指定できます。

セキュリティに関する考慮事項

⚠️ Osoba はローカルでの単一ユーザー利用を想定して設計されています。 API には認証レイヤーがありません。信頼できないネットワーク（例：ngrok、ポートフォワーディング、0.0.0.0 へのバインド）にポート 8000 を絶対に公開しないでください。

• ネットワークへの公開：バックエンドはデフォルトで 127.0.0.1 にバインドされます。リスクを理解していない場合は、0.0.0.0 に変更しないでください。
• 暗号化キー：backend/.env で SETTINGS_ENCRYPTION_KEY に安定した Fernet キーを設定してください。設定しない場合、プロバイダーの API キーは再起動のたびに失われます。
• MongoDB：デフォルトの接続では認証を使用しません。機密データを扱う場合は、MongoDB 認証を有効にし、認証情報を含む接続文字列を使用してください。
• プロバイダーの API キー：キーは Fernet で保存時に暗号化され、API から返されることはありません。.env ファイルを安全に保管し、バージョン管理に含めないでください。
• MySQL クエリ：クエリは読み取り専用の SELECT 文として検証され、自動的に最大 1000 行に制限されます。接続タイムアウトと読み取りタイムアウトにより、クエリの暴走を防ぎます。
• CSV のアップロード：アップロードはデコード後のサイズが 50 MB までに制限され、メモリ内の DataFrame ストアには最大 10 個のデータセットが保持されます（最も古いものから削除されます）。

使い方

1. 前提条件のサービスが実行中であることを確認します：

   • Ollama：実行中である必要があります。
   • MongoDB：MongoDB インスタンスにアクセスできる必要があります。
   • MySQL Server（SQL ツールを使用する場合）：MySQL サーバーが実行中であり、.env に指定した認証情報でアクセスできる必要があります。

2. バックエンドサーバーを起動します： backend ディレクトリに移動し、FastAPI アプリケーションを実行します：

   # From the backend directory
   uvicorn main:app --reload --port 8000
   

   通常、バックエンド API は http://localhost:8000 で利用できます。 FastAPI アプリケーションは、lifespan manager を使用して、すべての MCP サービス（Web、SQL、YouTube、HubSpot、Python、Codex）をバックグラウンドプロセスとして自動的に起動・管理します。MCP サーバーを個別に実行する必要はありません。

3. フロントエンドの開発サーバーを起動します： frontend ディレクトリに移動し、次を実行します：

   npm run dev
   # or
   # yarn dev
   

   通常、Web インターフェースには http://localhost:5173（または Vite で指定された別のポート）からアクセスできます。

アプリケーションの操作

• ブラウザーでフロントエンドの URL（例：http://localhost:5173）を開きます。
• チャットインターフェースからメッセージを送信します。ツールの実行中はインジケーターが表示され、応答がリアルタイムで配信されます。
• ✨ ツールセレクターをクリックして、スマートウェブ検索、データベース、YouTube、HubSpot、Python、Canva、Figma、Poe、Codex（OpenAI の設定が必要）のいずれかを有効にします。
• Settings（ヘッダー）からプロバイダーの API キーを設定し、Ollama 以外のモデルと Codex を利用できるようにします。
• ユーザープロフィールを設定する：Settings → User Profile で、役割、専門分野、現在のプロジェクト、コミュニケーションの好みを追加すると、AI アシスタンスをパーソナライズできます。
• 目標を設定する：Settings → Goals & Priorities で、短期、中期、長期の目標を定義します（最大 2000 文字）。AI はこれらの目標を利用して、状況に応じたアシスタンスや先回りしたインサイトを提供します。
• 先回りしたインサイトを有効にする：Settings → Goals & Priorities → Heartbeat Settings でハートビートサービスを設定すると、進捗、障害、提案について AI が定期的に生成するインサイトを受け取れます。ヘッダーのベルアイコン（🔔）をクリックすると、インサイトを確認できます。
• 会話をピン留めする：サイドバーの会話にカーソルを合わせ、ピン留めボタンをクリックすると、今後のチャットのコンテキストに含められます。
  • 会話に要約がない場合は、ピン留めする前に要約を生成するよう求められます。要約の作成中は UI がブロックされ、完了後にピン留めされます。
  • ピン留めできる会話は最大 5 件です。上限を超える操作はブロックされ、サイドバーに「X/5 pinned」と表示されます。
  • 要約は選択したモデル（Settings → Summaries を参照）によって必要に応じて生成され、再利用できるよう保存されます。コンテキストには保存済みの要約のみが使用されます。
• YouTube の場合：動画の URL を貼り付けます。文字起こしが取得され、後続のやり取りに利用できるよう会話に保存されます。
• HubSpot の場合：「Connect HubSpot」をクリックして OAuth を完了し、作成または更新するメールについて説明します。
• Canva の場合：.env で CANVA_API_TOKEN を設定し、デザインの作成（例：「AI in 2025」という名前の YouTube サムネイルを作成）、デザインの一覧表示、アセットのアップロード、ファイルのインポート、デザインの PDF へのエクスポートを AI に依頼します。
• Figma の場合：.env で FIGMA_ACCESS_TOKEN を設定し、Figma ファイルの読み取り（例：「Figma ファイル ABC123 の構造を取得」）、特定のフレームの画像へのエクスポート、デザインシステムのトークンの抽出、コメントの一覧表示や投稿を AI に依頼します。
• Poe の場合：.env で POE_API_KEY を設定し、画像の生成（例：「山に夕日が沈む 16:9 の横長画像を生成」）、最先端モデルとのチャット、動画や音声の生成を AI に依頼します。
• Python の場合：プロンプトが表示されたら CSV ファイルをアップロードします。読み込まれた DataFrame は後続の質問でも再利用され、フィルタリング、グループ化、外れ値検出、統計検定、可視化などの高度な分析に利用できます。
• サイドバーから会話を管理します（新規作成、選択、名前変更、削除、コンテキスト用にピン留め）。

長時間実行タスク（計画と実行）

• タスクパネル（ヘッダーの［Tasks］ボタン）を開くと、次の操作ができます。
  • 大まかな目標を入力して、新しいタスクを作成します。
  • 進捗（ライブ SSE ストリーム）を監視し、ステップの出力（テーブル、画像、テキスト）を確認して、一時停止／再開／キャンセルします。
  • ユーザーのチャットメッセージから「タスクに昇格」を選択すると、目標が事前入力され、タスクが会話にリンクされます。
  • 専用のコピーボタンを使用して、タスク結果全体または個々のステップの出力をコピーします。
  • 完了、失敗、またはキャンセルされたタスクを削除して、タスクリストを整理します。
  • バックエンドは各タスクを構造化 JSON（ステップ、ツール、パラメーター、成功条件）として計画し、その後、次の設定でステップを順番に実行します。
  • 実行予算：最大実行時間と最大ツール呼び出し回数。
  • ステップごとのタイムアウトと、バックオフを伴う上限付き再試行。
  • 成功条件に基づく出力の検証。
• 完了時：最後のステップが終了すると、タスクのステータスは COMPLETED になります。失敗、タイムアウト、または予算超過の場合、ステータスは FAILED になります。簡潔な概要がリンク先の会話に投稿されます。
  • OpenAI キーが設定されている場合、プランナーは足場の構築や作成を目的とするタスクで codex.run ステップを提案することがあります。キーが設定されていない場合、そのようなステップは自動的に無効化されます。

API：

• タスクの作成：POST /api/tasks { goal, conversation_id?, dry_run? }
• タスクの一覧表示：GET /api/tasks
• タスクの詳細：GET /api/tasks/{id}
• タスクストリーム（SSE）：GET /api/tasks/{id}/stream
• 一時停止／再開／キャンセル：POST /api/tasks/{id}/pause|resume|cancel
• タスクの削除：DELETE /api/tasks/{id}
• ステータス：GET /api/status には tasks.active の件数が含まれます

LLM のみのステップ（MCP なし）：

• プランナーは、MCP サーバーを介さずに Ollama から直接実行する llm.generate ステップに対応しています。prompt が省略された場合は、そのステップの instruction が使用されます。これらのステップも、実行予算、タイムアウト、検証の対象となります。

従来のクライアント（削除済み）

元の chat_client.py（ターミナル）と chat_frontend.py（Gradio）は、現在の FastAPI バックエンドアーキテクチャとの互換性がなくなったため、リポジトリから削除されました。すべての機能は、現在の React フロントエンドから利用できます。

Python データ分析ツール

Python MCP サーバーは、次のツールを通じて包括的なデータ分析機能を提供します。

基本的なデータ操作

• load_csv - Base64 エンコードされた文字列から CSV データを読み込みます
• get_head - DataFrame の先頭 N 行を表示します
• get_data_info - DataFrame の包括的な情報（データ型、メモリ使用量、欠損値でない件数）を表示します
• get_descriptive_statistics - 数値列の統計的要約を表示します

データ品質とクリーニング

• check_missing_values - 列ごとの欠損値を特定します
• handle_missing_values - 欠損データを処理します（削除、補完、補間）
• convert_data_types - 安全にデータ型を変換します（日時、カテゴリ、数値）
• detect_outliers - IQR または Z スコアの手法で外れ値を検出します

データの加工と分析

• filter_dataframe - セキュリティ検証を伴う pandas クエリ構文でデータをフィルタリングします
• group_and_aggregate - 列でグループ化し、集計関数を適用します
• query_dataframe - 新しい DataFrame を作成する高度な DataFrame クエリを実行します
• rename_columns - DataFrame の列名を変更します
• drop_columns - 指定した列を削除します

統計分析

• get_correlation_matrix - 数値列の相関行列を計算します
• get_value_counts - カテゴリ列の度数分析を行います
• perform_hypothesis_test - 統計的仮説検定を実行します：
  • 2 標本 t 検定
  • Pearson 相関検定
  • カイ二乗独立性検定

データの可視化

• create_plot - さまざまな種類のプロットを生成します：
  • 散布図
  • ヒストグラム
  • 棒グラフ
  • 箱ひげ図
  • Web 表示用の Base64 エンコード画像を返します

すべてのツールは、メモリ内の DataFrame ストアを通じてセッション状態を維持するため、1 回の会話内で複雑な複数ステップの分析ワークフローを実行できます。

ユーザープロファイルとコンテキストに応じた AI アシスタンス

このアプリケーションでは、ユーザープロファイルと会話コンテキストの管理を通じて、パーソナライズされた AI アシスタンスを提供します。

ユーザープロファイルの設定

• 個人情報：役職、専門分野、現在のプロジェクト、コミュニケーションの好みを設定できます
• コンテキストの理解：AI があなたの背景を理解し、それに応じて回答を調整します
• 設定との連携：設定 → ユーザープロファイルから簡単に設定できます

会話コンテキストシステム

• 選択的なピン留め：今後のチャットのコンテキストとして含める会話を選択できます
• 視覚的な操作：直感的な操作で、サイドバーから直接会話をピン留め／ピン留め解除できます
• 自動要約：必要に応じて、システムがピン留めされた会話の要約を自動生成します
• ハイブリッド要約方式：コンテキストを完全に把握できるよう、ユーザーの質問とアシスタントの解決策の両方を記録します
• コンテキストの継続性：AI は以前の問題と解決策の両方を参照して、一貫性のあるアシスタンスを提供できます
• スマートな上限：コンテキストは合計約 2700 文字（プロフィール 200 文字＋ピン留めされた要約で最大 2500 文字）に収まるよう調整されます
• 永続ストレージ：生成された要約は保存され、再生成を避けるために再利用されます

パーソナライズされた AI の回答

AI はプロフィール情報とピン留めされた会話のコンテキストを組み合わせ、次の内容を提供します。

• 関連性の高い提案：役職や現在のプロジェクトに基づく提案
• 適切な複雑さ：専門知識のレベルに合った技術的な深さ
• 一貫したコンテキスト：以前の作業を参照し、会話の継続性を保つ機能
• 解決策の把握：すでに試した方法を認識し、それを基に対応する機能
• 適応型コミュニケーション：好みに合わせた回答スタイル

ユーザープロファイルと AI の設定

• ユーザープロファイル：あなたについての情報（役職、プロジェクト、好み）。AI が対話相手を理解するのに役立ちます
• AI プロファイル：AI の動作や性格の設定。AI がどのように振る舞うべきかを定義します
• 組み合わせによる効果：あなたがどのような人か、また AI がどのように応答すべきかの両方を把握した、パーソナライズされた対話を実現します

技術的な実装

• 要約の自動生成：会話がピン留めされると、直近の 5 件のメッセージからオンデマンドで要約が生成されます
• ハイブリッド要約形式：ユーザーの質問と、アシスタントによる重要な解決策の両方が含まれます（例：「ユーザーの質問 | 解決済み：pandas、matplotlib」）
• スマートな解決策の抽出：アシスタントの回答からコード例、ツールの推奨事項、解決策のパターンを特定します
• ユーザーの分離：ユーザーごとに会話を絞り込み、ユーザー間でコンテキストが漏洩するのを防ぎます
• パフォーマンスの最適化：要約は一度だけ生成されて保存され、複数のチャットで再利用されます

セマンティックメモリシステム

Osoba は、高度なセマンティックメモリシステムを備えています。会話を無制限に保存し、インテリジェントなセマンティック検索を行うことで、5 件までの会話をピン留めする制限を超えて活用できます。

仕組み

自動インデックス作成：

• 5 件以上のメッセージを含む会話は、10 分間操作がないと自動的にインデックスが作成されます
• Ollama 経由で nomic-embed-text を使用し、ローカルでプライバシーを保護しながら埋め込みを生成します
• セマンティック検索用に、会話のチャンクを ChromaDB ベクトルデータベースに保存します
• チャットのパフォーマンスに影響しない、ノンブロッキングのバックグラウンド処理を行います

セマンティック検索：

• キーワードだけでなく意味に基づいて検索し、概念的に類似した会話を見つけます
• 関連度スコアで、検索結果がクエリにどの程度一致するかを表示します（例：「87% 一致」）
• 関連性の高い過去の会話を、新しいチャットに自動的に挿入します
• 検索結果がノイズにならないよう、類似度が 60% を超える会話のみを含めます

メモリブラウザー（Ctrl+Shift+M）：

• インデックスが作成されたすべての会話を対象に、全文セマンティック検索を実行します
• 関連度スコア付きのプレビュー用スニペットを表示します
• 個別の会話をメモリから削除します
• すばやくアクセスするためのキーボードショートカットを利用できます

主な機能

無制限のストレージ：

• 人工的な上限はありません。数千件の会話を保存できます
• インテリジェントなチャンク分割（512 トークン、50 トークンのオーバーラップ）でコンテキストを保持します
• 保持ポリシーに基づいて自動的にクリーンアップします（設定可能）

スマートなコンテキスト注入：

• 関連する過去の会話がチャットのコンテキストに自動的に追加されます
• 最も関連性の高い会話のみが含まれます（インデックス済みの会話すべてではありません）
• 関連性を最大限に高めながら、コンテキストウィンドウの上限を守ります

プライバシー優先：

• Ollama を使ったローカル埋め込み（外部 API 呼び出しはありません）
• すべてのデータは ChromaDB にローカル保存されます
• 会話データがマシンの外部に送信されることはありません

セマンティックメモリーの使用

手動保存：

• 「💾 Save to Memory」ボタンをクリックします（メッセージが 5 件以上ある会話に表示されます）
• 会話をすぐにインデックス化し、後から参照できるようにします

自動インデックス化：

• メッセージが 5 件以上あり、10 分間アイドル状態になった会話は自動的にインデックス化されます
• バックグラウンドサービスが 5 分ごとに、条件を満たす会話がないか確認します
• ユーザーによる操作は不要です

メモリーの検索：

1. Ctrl+Shift+M を押してメモリーブラウザーを開きます
2. 検索クエリを入力します（例：「Python pandas dataframe」）
3. 関連度スコアとプレビューテキストを含む結果を確認します
4. クリックして会話を表示または削除します

メモリーの管理：

• 設定 → セマンティックメモリーから統計情報とコントロールにアクセスします
• インデックス化された会話の合計数とストレージ使用量を確認します
• 自動インデックス化の確認を手動で実行します
• すべてのメモリーを消去します（確認が必要です）

技術的な詳細

埋め込みモデル：

• nomic-embed-text（768 次元の埋め込み）
• Ollama を介してローカルで実行されます
• API 費用やレート制限はありません

ベクトルデータベース：

• 永続的なベクトルストレージに ChromaDB を使用します
• 効率的な類似性検索（一般的なクエリで 100 ミリ秒未満）
• ディスクに自動保存されます

コンテキスト連携：

• セマンティックメモリーはプロフィールのコンテキストの後に注入されます
• 「Relevant past conversations」セクションとして書式設定されます
• 会話のタイトル、関連度スコア、プレビューテキストが含まれます

ピン留めより優れている点

機能	ピン留め（最大 5 件）	セマンティックメモリー
容量	5 件の会話	無制限
選択方法	手動	関連度に基づき自動
検索	なし	セマンティック検索
コンテキスト効率	5 件すべてを含む	関連する会話のみ
管理	手動でピン留め／解除	自動インデックス化

ドキュメントナレッジベース

ドキュメントナレッジベースでは、SOP、研究論文、仕様書、ドキュメントなどの永続的な参照資料をアップロードし、セマンティックメモリーが過去のチャットを活用するのと同じように、AI がすべての会話でその資料を自動的に活用できます。

対応フォーマット

フォーマット	拡張子	パーサー
プレーンテキスト	.txt	UTF-8 デコード
Markdown	.md	UTF-8 デコード
Word 文書	.docx	python-docx
PDF	.pdf	pdfplumber
Web ページ	URL	trafilatura

ドキュメントの最大サイズ：1 件あたり 200,000 文字。

仕組み

Upload (file / URL)
    ↓
document_parser.py  ← extracts plain text
    ↓
documents_crud.py   ← stores metadata + raw text in MongoDB ("documents" collection)
    ↓
document_indexing.py ← chunks text → embeds via nomic-embed-text → stores in ChromaDB ("documents" collection)
    ↓
kb_context.py       ← at chat time: embeds query, searches "documents", formats snippets
    ↓
chat_service.py     ← injects "=== Knowledge Base ===" section into system prompt

50,000 文字を超えるドキュメントはバックグラウンドでインデックス化されるため、アップロードはすぐに完了します。

ナレッジベースパネルを開く

• キーボードショートカット：Ctrl+Shift+K
• ヘッダーボタン：上部のナビゲーションバーにある「KB」をクリックします

ドキュメントタブ

• ドラッグ＆ドロップでアップロードするか、「Choose File」をクリックして .txt、.md、.docx、.pdf ファイルを選択します
• URL 取り込み：任意の URL を貼り付けて「Add URL」をクリックするか Enter キーを押すと、Web ページを取得してインデックス化します
• ドキュメントカードには、種類バッジ（色分け）、インデックス化ステータスのドット（緑＝準備完了、琥珀色＝保留中）、文字数、アップロード日、削除ボタンが表示されます
• ドキュメントはアップロード後すぐにインデックス化されます（大きなファイルはバックグラウンドで処理されます）

検索タブ

• クエリを入力すると、インデックス化されたすべてのドキュメントチャンクをセマンティック検索できます
• 検索結果には、ドキュメントのタイトル、関連度の割合、テキストの抜粋が表示されます

サイドバーのステータス

左サイドバーのフッターには、インデックス化されたドキュメントの現在の件数が表示されます。ドキュメントが 1 件以上利用可能になると、インジケーターのドットが緑色になります。

チャット連携

メッセージを送信すると、バックエンドは次の処理を行います。

1. nomic-embed-text を使用してクエリを埋め込みます
2. documents ChromaDB コレクションを検索し、関連性の高い上位5件のチャンク（スコア ≥ 0.4）を取得します
3. 検索結果を === Knowledge Base === セクションとして整形し、セマンティックメモリとともにシステムプロンプトに挿入します

各メッセージに手動で含めなくても、関連する場合はAIがドキュメントの内容を参照します。

タスクでのKBドキュメントの使用

タスクの作成時に、インデックス済みのKBドキュメントを1～2件明示的に添付して、プランナーやステップエージェントに参考資料を提供できます。これは完全にオプトインです。ドキュメントを添付しない場合、タスクはこれまでとまったく同じように動作します。

添付方法：

1. Tasks パネルを開きます（Ctrl+Shift+T、またはTasksヘッダーのボタン）
2. 目標を入力します
3. "Add KB Doc" をクリックします。インラインのドロップダウンに、インデックス済みのドキュメントがすべて表示されます
4. 最大 2 件のドキュメントを選択します。選択したドキュメントは、入力欄の下に削除可能なチップとして表示されます
5. 実行ボタンをクリックします。選択したドキュメントは、ペイロード内の kb_doc_ids として送信されます

内部での処理：

Task creation request (with kb_doc_ids)
    ↓
api/tasks.py  — fetches each doc from MongoDB, excerpts up to 4,000 chars each
    ↓ stores {kb_docs: [{id, title}], kb_context: "=== Knowledge Base ===\n..."} in task doc
         ↓                              ↓
task_planner.py              task_runner.py
(planning prompt includes     (every LLM step gets kb_context
 "Reference material" block)   as the 2nd message after system)

制限事項：

制約	値
タスクあたりの最大ドキュメント数	2
ドキュメントあたりの抜粋文字数の上限	4,000
KBコンテキスト文字列の合計上限	約9,000文字
選択可能なドキュメント	インデックス済みのもののみ
作成時点のコンテンツをスナップショットとして保存	はい — すべてのステップで一貫して使用
LLMのステップのみに挿入	はい — MCPツールのステップには挿入されません

タスク詳細ビュー： 添付ドキュメントはタスクヘッダーに小さなチップとして表示されるため、どのようなコンテキストが提供されたかをひと目で確認できます。

ヒント： 定められた手順に従うタスクには、SOPや仕様書を添付してください。プランナーはそのドキュメントの制約をステップの設計に取り込み、各LLM生成ステップで抜粋全体を利用できるようになります。

APIエンドポイント

メソッド	パス	説明
POST	/api/documents/upload	ファイルをアップロードします（base64エンコードされたJSON本文）
POST	/api/documents/url	URLから取り込みます
GET	/api/documents	すべてのドキュメントを一覧表示します
GET	/api/documents/{id}	ドキュメントの詳細を取得します（コンテンツを含む）
DELETE	/api/documents/{id}	MongoDBとChromaDBから削除します
GET	/api/documents/search?q=...	ドキュメントのチャンクを対象にセマンティック検索します
GET	/api/documents/stats	件数、文字数、チャンク数を取得します

アップロードペイロードの形式：

{
  "filename": "spec.pdf",
  "data_b64": "<base64 string>",
  "title": "Product Spec",
  "description": "Optional description",
  "user_id": "default"
}

バックエンドのファイル

ファイル	目的
backend/db/document_store.py	DocumentVectorStore — ChromaDBの"documents"コレクション
backend/db/documents_crud.py	ドキュメントメタデータのMongoDB CRUD
backend/services/document_parser.py	ファイル／URLからプレーンテキストを抽出
backend/services/document_indexing.py	チャンク分割、埋め込み、保存のパイプライン
backend/services/kb_context.py	クエリ実行時のコンテキスト構築
backend/api/documents.py	FastAPIルーター（/api/documents）

プロアクティブエージェントのハートビートシステム

Enhanced Heartbeat Systemは、自動的なインサイトの提示とタスクの作成により、プロアクティブなAI支援を提供します。目標、会話、プロジェクトの状態、システムの健全性を分析し、実行可能な次のステップを提案します。

主な機能

コンテキストの収集：

• セマンティックメモリ：会話履歴、インデックス済みの会話、ストレージ使用量
• Gitリポジトリ：現在のブランチ、未コミットのファイル、未プッシュのコミット、最近のコミット
• プロジェクトファイル：TODO／FIXMEコメント、最近変更されたファイル
• システムの健全性：ディスク使用量、サービスの状態

タスクの自動作成：

• インサイトから、追跡可能なタスクを自動的に作成できます
• 「Create Task」ボタンを使って手動で変換できます
• 追跡できるよう、タスクはインサイトに関連付けられます

ファイルベースの設定（上級ユーザー向け）：

• HEARTBEAT.md でハートビートタスクを定義します
• カテゴリー別にタスクを整理できます
• カスタムスケジュール（cron形式または間隔形式）を設定できます
• ファイルとUIを双方向に同期できます

仕組み

ハートビートサービスは、設定可能な間隔（デフォルト：2 時間ごと）でバックグラウンド実行されます。各ハートビートでは、次の処理が行われます。

1. コンテキストの収集：目標、会話、タスク、拡張コンテキスト（メモリ、Git、プロジェクト、システム）を収集します
2. AI による分析：選択した LLM にコンテキストを送信します（デフォルトは、ユーザー 1 人あたり 1 日約 $0.01 と費用対効果の高い Haiku です）
3. インサイトの生成：AI が実行可能なインサイトや提案を生成するか、障害となっている問題を特定します
4. スマートフィルタリング：「HEARTBEAT_OK」パターンを使用して、すべてが順調な場合は通知を抑制します
5. タスクの作成：必要に応じて、インサイトから追跡対象のタスクを作成します
6. 通知：ヘッダー右上のベルアイコンパネルにインサイトを表示します

クイックスタート

1. ハートビートを有効にする：

• 設定 → プロアクティブハートビート
• 「ハートビートを有効にする」を切り替えます
• チェック間隔（30m、1h、2h、4h、6h）を選択します

2. コンテキストソースを設定する：

• セマンティックメモリを有効にします（推奨）
• Git リポジトリを有効にします（推奨）
• 必要に応じて、プロジェクトファイルとシステムの正常性を有効にします

3. タスクの自動作成を有効にする（任意）：

• 「タスクを自動作成」を切り替えます
• インサイトから追跡対象のタスクが自動的に作成されます

4. 目標を設定する：

• 設定 → 目標と優先事項
• 目標を記載したドキュメントを入力します（最大 2000 文字）

HEARTBEAT.md の使用（上級ユーザー向け）

プロジェクトのルートに HEARTBEAT.md を作成します。

# Heartbeat Tasks

## Memory Management
Schedule: 0 2 * * *
Enabled: true
Prompt: Review semantic memory usage and suggest cleanup if storage exceeds 100MB
Context: memory

## Testing Reminders
Schedule: 0 9 * * 1
Enabled: true
Prompt: Check test coverage and suggest missing tests
Create_Task: true
Context: git,project

同期オプション：

• ファイルから読み込む：HEARTBEAT.md からタスクをデータベースにインポートします
• ファイルに保存する：設定済みのタスクを HEARTBEAT.md にエクスポートします

インサイトの使用

1. 通知を確認する：ヘッダーのベルアイコン（🔔）をクリックします

• バッジに未読インサイトの件数が表示されます
• ドロップダウンパネルに最近のインサイトが表示されます

2. インサイトを確認する：各インサイトには次の情報が含まれます

• タイトル：インサイトの簡単な要約
• 説明：詳細な提案または所見
• タイムスタンプ：インサイトが生成された日時
• タスク作成ボタン：インサイトを追跡対象のタスクに変換します

3. インサイトを非表示にする：「非表示」をクリックすると、対応済みのインサイトを削除できます

4. 手動で実行する：ハートビートチェックを今すぐ実行します。

curl -X POST "http://localhost:8000/api/heartbeat/trigger?user_id=default"

インサイトの例

進捗の確認：

タイトル：「認証機能の進捗」
説明：「今週、認証機能を完成させるとおっしゃっていました。直近の会話では、パスワードリセットに取り組んでいるようです。完了としてマークする前に、エッジケースをテストすることを検討してください。」

障害の特定：

タイトル：「デザインモックアップによるブロッカー」
説明：「目標には、デザインモックアップを待っていると記載されています。このブロッカーについて記録してから 3 日が経過しています。デザインチームに連絡するか、ご自身でワイヤーフレームを作成することを検討してください。」

タスクの提案：

タイトル：「API ドキュメントのリマインダー」
説明：「API エンドポイントに関する完了済みのタスクが 5 件ありますが、ドキュメント作成タスクはありません。新しいエンドポイントのドキュメントを作成するタスクを追加することを検討してください。」

HEARTBEAT_OK（通知なし）： すべて順調な場合、AI は「HEARTBEAT_OK」と応答し、通知は作成されません。そのため、不要な通知を減らせます。

費用に関する考慮事項

• デフォルトのモデル：Claude Haiku 4.5（入力トークン 100 万件あたり約 $0.25）
• 一般的な費用：2 時間間隔でユーザー 1 人あたり 1 日約 $0.01
• コンテキストサイズ：約 1500 トークン（目標 + 会話 3 件 + タスク 5 件）
• 1 日あたりのハートビート：1 日 12 回のチェック（2 時間間隔）＝約 18K トークン ＝ $0.0045

費用の最適化：

• 間隔を長く（3～4 時間）して、実行頻度を減らします
• 稼働時間の設定を使って、業務時間外は無効にします
• ホスト型プロバイダーの代わりに、ローカルの Ollama モデル（無料）を使用します
• 目標ドキュメントを簡潔に保ちます

プライバシーとデータ

• ローカル処理：すべてのコンテキストはシステム内にとどまります
• 外部ストレージなし：インサイトは MongoDB のみに保存されます
• ユーザーごとの分離：各ユーザーの目標とインサイトは完全に分離されています
• いつでもオプトアウト可能：設定で無効にするか、目標ドキュメントを削除します

トラブルシューティング

インサイトが表示されない場合：

1. 設定でハートビートが有効になっていることを確認します
2. アクティブ時間内であることを確認します
3. 目標ドキュメントが保存されていることを確認します
4. バックエンドのログにエラーがないか確認します

通知が多すぎる場合：

1. 間隔を長くします（例：2h → 4h）
2. アクティブ時間を勤務時間のみに調整します
3. 目標ドキュメントを見直し、より具体的にします

インサイトが関連性に欠ける場合：

1. 目標ドキュメントを現在の優先事項に合わせて更新します
2. 阻害要因と進捗について、より多くのコンテキストを追加します
3. 関連する会話をピン留めして、コンテキストを充実させます

API リファレンス

インサイトの取得：

GET /api/heartbeat/insights?user_id=default&dismissed=false

インサイトの却下：

POST /api/heartbeat/insights/{insight_id}/dismiss?user_id=default

設定の取得：

GET /api/heartbeat/config?user_id=default

設定の更新：

PUT /api/heartbeat/config?user_id=default
Content-Type: application/json

{
  "enabled": true,
  "interval": "2h",
  "active_hours": {
    "start": "09:00",
    "end": "18:00",
    "timezone": "America/New_York"
  }
}

手動での実行：

POST /api/heartbeat/trigger?user_id=default

スマートウェブ検索とコンテンツ抽出

スマートウェブ検索 MCP サーバーは、基本的な検索スニペットをはるかに超える高度なウェブ検索機能を提供します。

インテリジェントなコンテンツ抽出

• 複数の抽出方式：信頼性を最大限に高めるため、trafilatura を優先して使用し、失敗した場合は BeautifulSoup にフォールバックします
• ウェブページ全体のコンテンツ：検索スニペットだけでなく、記事全体を抽出します
• コンテンツのクリーニング：HTML タグを削除し、空白を正規化して、エンティティを処理します
• 構造の保持：見出し、段落、コンテンツの階層を維持します

URL の優先順位付けアルゴリズム

• 関連性のスコアリング：タイトルとスニペット内の検索語句の一致に基づいて URL をランク付けします
• 位置の重み付け：検索結果内の位置とドメインの権威性を考慮します
• スマートなフィルタリング：ドキュメント、チュートリアル、信頼できる情報源を優先します

礼儀正しく倫理的なクロール

• Robots.txt の遵守：robots.txt ファイルを自動的に確認し、その指示に従います
• レート制限：リクエスト間の遅延を設定できます（デフォルト：1 秒）
• 適切な識別：説明的な User-Agent ヘッダーを使用します
• タイムアウト処理：到達できないサイトからの復旧を適切に処理します

設定オプション

環境変数を使用して抽出動作を設定します：

SMART_EXTRACT_MAX_URLS=3              # Maximum URLs to extract (default: 3)
SMART_EXTRACT_MAX_CHARS_PER_URL=2000  # Character limit per webpage (default: 2000)
SMART_EXTRACT_MAX_TOTAL_CHARS=5000    # Total character limit (default: 5000)
SMART_EXTRACT_REQUEST_DELAY=1.0       # Delay between requests (default: 1.0s)

パフォーマンスと品質

• コンテキストが 8 倍に：基本的な検索スニペットよりも大幅に多くのコンテンツを提供します
• 高い成功率：複数の抽出方式によって、信頼性の高いコンテンツ取得を実現します
• メモリ効率：文字数制限により、コンテキストのオーバーフローを防ぎます
• 高速処理：礼儀正しい遅延を含め、3 件の URL を通常 3～5 秒で処理します

スマート検索機能は、すべてのウェブ検索で自動的に有効になります。追加の設定や UI の変更は必要なく、ユーザーはコンテンツ抽出の強化を利用できます。

モデルプロバイダーと設定

• 対応プロバイダー：ollama（ローカル）、openai、anthropic、google（Gemini）、openrouter、groq、sambanova。
• 設定モーダル（ヘッダー → Settings）を開き、プロバイダーごとに API キーを追加・検証します。キーは軽量なリクエストで検証されます（OpenAI では誤検出を避けるため、小さな max_tokens=16 のチェックを使用します）。
• モデルピッカーにはプロバイダーごとのモデルが表示されます。Ollama 以外のモデルは、プロバイダーの設定後にのみ表示されます。
• プロバイダーのモデル名／プレフィックス（例）：
  • Ollama：llama3.1（プレフィックスなし）。
  • OpenAI：openai/gpt-5.6-sol。
  • Anthropic：anthropic/claude-sonnet-5。
  • Google：gemini/gemini-flash-latest。
  • OpenRouter：openrouter/z-ai/glm-5.3。
  • Groq：groq/openai/gpt-oss-20b。
  • SambaNova：sambanova/Meta-Llama-3.3-70B-Instruct。

API エンドポイント：

• プロバイダーの一覧：GET /api/providers
• プロバイダーのモデル：GET /api/providers/models
• プロバイダーのステータス：GET /api/providers/{provider_id}/status
• API キーの保存：POST /api/providers/settings { provider, api_key }
• API キーの削除：DELETE /api/providers/{provider_id}/settings
• 検証（キーは返されません）：GET /api/providers/{provider_id}/validate
• すべてのモデル（プロバイダーを含むフラットな一覧）：GET /api/models
• モデルの診断チェック：POST /api/providers/test-models { conversation_id?, include_ollama } — 設定済みのすべてのモデルに対して最小限の実際の呼び出しを実行し、構造化された Model Diagnostics レポートをチャットの会話に投稿します。

モデル診断（ライブスモークテスト）： モデルピッカーから Test Models をクリックすると、設定済みのすべてのプロバイダーモデル（およびインストール済みの Ollama モデル）に対して、1 文の実際の呼び出しが実行されます。各モデルのステータス、レイテンシ、応答／エラーが、現在のチャットに投稿される構造化レポートに表示されます（会話が存在しない場合は、新しい Model Diagnostics の会話が作成されます）。レート制限を守るため、モデルは順番にテストされ、モデルごとに 30 秒のタイムアウトが設定されます。

注意：

• Codex MCP には有効な OpenAI API キーが必要です。OpenAI が設定されていない場合、UI では Codex ツールが無効になります。

プロバイダー API キーの暗号化（必須）：

• バックエンドは、backend/.env の SETTINGS_ENCRYPTION_KEY で設定した Fernet キーを使用して、プロバイダー API キーを保存時に暗号化します。
• キーを一度生成し、再起動後も同じ値を使用してください。変更すると、保存済みのキーが無効になり、再入力が必要になります。
• キーを生成して設定します：
  • pip install cryptography
  • python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
  • backend/.env に設定：SETTINGS_ENCRYPTION_KEY=<output>

Codex Workspace（MCP）

コード生成は、確認可能なマニフェストと成果物を備えた分離ワークスペースで実行されます。

• UI：✨ Tool Selector をクリックし、「Codex (Workspace)」を選択します。指示（例：「Vite + React アプリをスキャフォールディングする」）を入力します。アシスタントは、実行中の状態と完了時の簡潔な概要を表示するインラインの codex_run メッセージを挿入します。
• バックエンド：FastMCP サーバー（backend/server_codex.py）は、ワークスペースの作成、実行の開始・ポーリング・キャンセル、ファイルの読み取り、マニフェストの取得を行うツールを公開します。実行は非同期で、小規模なインメモリージョブトラッカーを使用します。成果物はワークスペース内の codex_artifacts/ に書き込まれます。
• セキュリティ対策：実行ごとに専用のワークスペースを用意し、HOME をワークスペース内に分離します。シンボリックリンクを拒否し、realpath による包含チェックを行います。実行後の出力ポリシー（許可する拡張子、ドットファイルの許可リスト、最大ファイル数／バイト数、バイナリ判定ヒューリスティック）も任意で設定できます。最も強固な分離を実現するには、ネットワーク接続のないコンテナー／VM でサービスを実行してください。
• 要件：Codex CLI が PATH 上で利用できること（または CODEX_BIN を設定すること）、および有効な OPENAI_API_KEY（Settings または環境変数経由）が必要です。キーは Codex サブプロセスにのみ渡されます。

エンドポイント：

• ワークスペースを作成：POST /api/codex/workspaces { name_hint, keep }
• 実行を開始（ワークスペースがない場合は自動作成）：POST /api/codex/runs { workspace_id, instruction, model?, timeout_seconds? }
• 実行状態を取得：GET /api/codex/runs/{run_id}
• 実行をキャンセル：POST /api/codex/runs/{run_id}/cancel
• マニフェストを取得：GET /api/codex/workspaces/{workspace_id}/manifest
• ファイルを読み取る：GET /api/codex/workspaces/{workspace_id}/file?relative_path=…

環境変数（任意、デフォルト値を表示）：

• CODEX_BIN=codex、CODEX_WORKSPACES_DIR=./.codex_workspaces、CODEX_MAX_CONCURRENCY=1、CODEX_RUN_TTL_HOURS=48
• CODEX_MAX_PROMPT_CHARS=20000、CODEX_MAX_STDOUT_CHARS=200000、CODEX_MAX_STDERR_CHARS=50000
• CODEX_MAX_OUTPUT_FILES=500、CODEX_MAX_OUTPUT_TOTAL_BYTES=20971520、CODEX_DEBUG=false

フロントエンドの UX に関する注意：

• Codex の実行は、会話履歴に保持されるチャットメッセージ（type='codex_run'）としてインライン表示されます。従来のフローティング実行カードは削除されました。
• サイドバーには Codex MCP の状態が表示されます。サービスの準備が整い、OpenAI が設定されている場合にのみ緑色で表示されます。
• マニフェスト／ファイル API を利用する File Viewer Modal は将来の利用に備えて用意されていますが、リンク切れを防ぐため自動では起動しません。

Canva Design Tools（MCP）

Osoba を離れることなく、Canva のデザインを作成、閲覧、インポート、サイズ変更、エクスポートできます。Canva MCP サーバーは OAuth 2.0 アクセストークンを使用して Canva Connect API に接続します。

セットアップ

1. canva.com/developers にアクセスしてログインします（MFA が必要です）。
2. Your integrations に移動し、Create an integration を選択します。
3. Scopes で、design:content（読み取りと書き込み）、design:meta（読み取り）、asset（読み取りと書き込み）を有効にします。自動入力を使用する場合は、brandtemplate:meta（読み取り）と brandtemplate:content（読み取り）も有効にします。
4. Authentication で、リダイレクト URL（例：http://127.0.0.1:3000/redirect）を追加します。
5. テストトークンを生成します。任意の API リファレンスページ に移動し、「Try it out」までスクロールして "Generate an access token" をクリックし、ブラウザー内の OAuth フローを完了して、トークンをコピーします。
6. トークンを backend/.env に追加します：

CANVA_API_TOKEN=your_access_token_here

Note: テストトークンの有効期限は 4 時間です。継続的に使用するには、リフレッシュトークンを使用する完全な OAuth 2.0 Authorization Code フローを実装する必要があります。

バックエンドは、他のすべての MCP サービスとともに Canva サービスを自動的に起動するため、別のプロセスは必要ありません。トークンを削除せずに無効化するには、.env で DISABLED_MCP_SERVICES=canva_service を設定します。

ツール

ツール	パラメーター	機能
create_design	title, preset?, width?, height?, unit?, template_id?	指定したサイズで新しい空白のCanvaデザインを作成します
list_designs	limit?, page_token?	ページネーションを使用して、アカウント内のデザインを一覧表示します
get_design	design_id	デザインのメタデータとエディターURLを取得します
get_design_pages	design_id	複数ページのデザインのページメタデータを取得します
export_design	design_id, format?, pages?	デザインをエクスポートし、ダウンロードURLを返します
upload_asset	name, url	公開URLから画像／動画をユーザーのCanvaライブラリにアップロードします
autofill_design	brand_template_id, data, title?	ブランドテンプレートにテキスト／画像データを入力してデザインを作成します（Enterprise）
get_brand_template_dataset	brand_template_id	ブランドテンプレート内の自動入力可能なフィールドを検出します（Enterprise）
import_design	title, url, mime_type?	URLからファイル（PDF、PPTX、DOCX、PSD、AI、Keynoteなど）を編集可能なCanvaデザインとしてインポートします
resize_design	design_id, width, height	既存のデザインのサイズを変更したコピーを作成します（Pro／Enterprise）

対応プリセット（create_design 用）：

プリセット	サイズ	用途
presentation	Canvaのネイティブ形式	スライド
instagram_post	1080×1080	正方形の投稿
instagram_story	1080×1920	ストーリー／リール
facebook_post	1200×630	フィード投稿
facebook_cover	820×312	ページカバー
twitter_post	1200×675	Twitter／Xの投稿
linkedin_banner	1584×396	プロフィールバナー
youtube_thumbnail	1280×720	動画サムネイル
a4	595×842	文書
us_letter	612×792	USレターサイズの文書
custom	ユーザー定義	ピクセル単位でwidthとheightの指定が必要です

エクスポート形式：png（デフォルト）、jpg、pdf、pptx、svg、mp4、gif

チャットでの使用

✨ ツールセレクターからCanvaツールを選択し、自然な言葉で依頼します：

• 「最近のCanvaデザインを一覧表示して」
• 「『The Future of AI』というタイトルのYouTubeサムネイルを作成して」
• 「デザインDABcd1234をPDFにエクスポートして」
• 「この画像をCanvaライブラリにアップロードして：https://example.com/photo.jpg」
• 「デザインDABcd1234のページを取得して」
• 「このプレゼンテーションをCanvaにインポートして：https://example.com/deck.pptx」

AIが適切なツールを選択して実行し、結果（エディターURL、ダウンロードリンク、アセットIDなど）を返します。

タスクでの使用

複数ステップの自律的なワークフローでは、タスクプランナーからCanvaツールを利用できます。プランナーは次のツールエイリアスを認識します：design、canva_create、export、canva_export、canva_list、canva_get、canva_upload、canva_autofill、canva_import、canva_resize、canva_pages。

タスク目標の例：

• 「2025年の主要なAIツールを5つ調査し、調査結果をまとめたLinkedInバナーを作成して」
• 「製品ローンチ用のプレゼンテーションスライドの構成を作成し、PDFとしてエクスポートして」
• 「Canvaのデザインをすべて一覧表示し、最も新しいプレゼンテーションを見つけて、PNGとしてエクスポートして」

プランナーはweb_search → llm.generate → create_design → export_designのステップを自動的に連携させ、各ステップの出力を次のステップの入力として使用します。

ファイル

ファイル	目的
backend/server_canva.py	FastMCPサーバー — MCPツール10個
backend/utils/canva_client.py	非同期httpxクライアント、Pydanticモデル、ポーリングロジック
backend/tests/test_canva_mcp.py	単体テスト77件（APIトークン不要）

Figmaデザインツール（MCP）

Osobaを離れることなく、Figmaのデザインを読み取り、確認し、エクスポートできます。Figma MCPサーバーは、パーソナルアクセストークンを使用してFigma REST APIに接続します。

セットアップ

トークンを backend/.env に追加します。

FIGMA_ACCESS_TOKEN=your_figma_personal_access_token_here

トークンは Figma → Account Settings → Security → Personal access tokens から取得します。バックエンドは、ほかのすべての MCP サービスとともに Figma サービスを自動的に起動するため、別のプロセスは必要ありません。トークンを削除せずに無効にするには、.env に DISABLED_MCP_SERVICES=figma_service を設定します。

すべてのツールで使用するファイルキーは、Figma ファイル URL 内の英数字の ID です。 figma.com/file/{file_key}/file-name

ツール

ツール	パラメーター	機能
figma_get_file	file_key, depth?	ファイル構造とメタデータ（ノードツリー、コンポーネント、スタイル）をすべて取得します
figma_get_nodes	file_key, node_ids, depth?	カンマ区切りの ID（例："1:2,3:4"）で指定したノードを取得します
figma_export_images	file_key, node_ids, format?, scale?	ノードを画像としてエクスポートし、一時的なダウンロード URL を返します
figma_get_comments	file_key	ファイル上のすべてのコメントを一覧表示します
figma_post_comment	file_key, message, node_id?, parent_id?	コメントを投稿します。ノードに紐付けたり、別のコメントへの返信にしたりできます
figma_get_design_system	file_key	カラートークン、タイポグラフィ、スペーシングトークン、コンポーネントカタログを抽出します

エクスポート形式（figma_export_images 用）：png（デフォルト）、jpg、svg、pdf

スケール（figma_export_images 用）：0.01～4.0、デフォルトは 1.0

注：figma_export_images が返すエクスポート URL は一時的なものです（Figma の CDN でホストされています）。数時間以内に期限切れになるため、速やかにダウンロードしてください。

レート制限

Figma の無料プランでは、1 時間あたり 1000 件のリクエストが許可されています。クライアントはスライディングウィンドウ方式のトークンバケットを使用して、この制限内に自動的に収まるようにします。より高い上限の有料プランをご利用の場合は、環境変数で上書きできます。

FIGMA_RATE_LIMIT_REQUESTS=5000   # requests per window (default: 1000)
FIGMA_RATE_LIMIT_WINDOW=3600     # window in seconds (default: 3600)

チャットでの利用

Figma サービスが稼働している状態で、AI に自然な言葉で依頼します。

• 「Figma ファイル ABC123 の構造を取得して」
• 「ファイル ABC123 のヒーローフレーム（ノード 1:23）を PNG としてエクスポートして」
• 「Figma ファイル ABC123 にはどんなコメントがある？」
• 「ブランドファイル XYZ789 からデザインシステムのトークンを抽出して」
• 「ファイル ABC123 のノード 5:10 にコメントを投稿して：『ここはコントラストを上げてください』」

AI は適切なツールを呼び出し、ノードツリー、エクスポート URL、コメントスレッド、トークン一覧などの結果をチャットに直接返します。

タスクでの利用

Figma ツールは、複数ステップの自律型ワークフロー向けにタスクプランナーから利用できます。プランナーは、次のツールエイリアスを認識します：figma_file、figma_nodes、figma_images、figma_comments、figma_comment、figma_design_system、figma_tokens。

タスク目標の例：

• 「Figma ファイル ABC123 を取得し、すべてのカラーとタイポグラフィのトークンを抽出してから、CSS 変数ファイルを生成して」
• 「Figma ファイル ABC123 のすべてのフレームを PNG 画像としてエクスポートし、ダウンロード URL を一覧表示して」
• 「Figma ファイル ABC123 のデザインシステムトークンを確認し、カラーパレットの概要を書いて」

プランナーは figma_get_design_system → llm.generate のステップを自動的に連結し、要求された成果物を作成します。

ファイル

ファイル	用途
backend/server_figma.py	FastMCP サーバー — MCP ツール 6 個
backend/utils/figma_client.py	Async httpx クライアント、Pydantic モデル、レートリミッター
backend/tests/test_figma_mcp.py	単体テスト 54 件（API トークン不要）

Poe AI Models (MCP)

Osoba を離れることなく、Poe プラットフォーム上の数百種類の AI モデルを利用できます。テキスト、画像、動画、音声を生成できます。Poe MCP サーバーは、API キーを使用して Poe OpenAI-compatible API に接続します。

セットアップ

1. poe.com/api/keys にアクセスします（Poe のサブスクリプションが必要です）。
2. API キーを生成します。
3. backend/.env に追加します。

POE_API_KEY=your_poe_api_key_here

バックエンドは、ほかのすべての MCP サービスとともに Poe サービスを自動的に起動するため、別のプロセスは必要ありません。キーを削除せずに無効にするには、.env に DISABLED_MCP_SERVICES=poe_service を設定します。

ツール

ツール	パラメーター	機能
poe_list_models	input_modality?, output_modality?, search?, limit?	利用可能なPoeモデルの一覧を表示します。モダリティ（text/image/video/audio）または名前で絞り込めます
poe_chat	prompt, model?, system?, temperature?, max_tokens?, image_urls?	任意のPoeモデルとテキストチャットを行います（デフォルト：Claude-Sonnet-4-6）
poe_generate_image	prompt, model?, system?, aspect_ratio?, download_media?	画像を生成し、URLと任意のbase64データを返します
poe_generate_video	prompt, model, system?, download_media?	動画を生成します（モデルの指定が必須です。poe_list_models を使ってモデルを探してください）
poe_generate_audio	prompt, model, system?, download_media?	音声／TTS／音楽を生成します（モデルの指定が必須です）

アスペクト比（poe_generate_image 用）：9:16（縦長、例：ストーリー／リール）、16:9（横長、例：YouTubeサムネイル）。モデルのデフォルト（通常は1:1の正方形）を使う場合は省略してください。

デフォルトの画像モデル：gpt-image-1.5（OpenAIの最新モデル）。その他の人気モデルには、Flux-Pro-1.1、DALL-E-3、SD3.5-Large などがあります。利用可能なモデルをすべて確認するには、poe_list_models(output_modality="image") を使ってください。

チャットでの利用

✨ Tool SelectorからPoeツールを選択し、自然な言葉で依頼します。

• 「Poeで利用できる画像生成モデルを一覧表示して」
• 「夕暮れの未来都市を16:9の横長画像で生成して」
• 「Flux-Proを使って、コーヒーショップ用のミニマルなロゴを作成して」
• 「ネオンに照らされた東京の路地を9:16の縦長画像で生成して」
• 「量子コンピューティングについてGPT-5.4とチャットして」

AIが適切なツールを選択して実行し、結果（画像URL、テキストの回答など）を返します。

タスクでの利用

Poeツールは、複数の手順からなる自律的なワークフローのために、タスクプランナーから利用できます。プランナーは次のツールエイリアスを認識します：poe、poe_models、poe_image、poe_video、poe_audio、poe_generate。

タスク目標の例：

• 「山に沈む夕日の16:9横長画像を生成し、Canvaライブラリにアップロードして」
• 「2025年の主要なAIトレンドを調査し、各トレンドを表す画像を生成して」
• 「Poeの画像モデルをすべて一覧表示し、比較のために同じプロンプトで3つの異なるモデルを使って生成して」

プランナーは poe_generate_image → upload_asset（Canva）→ autofill_design の手順を連鎖させ、生成した画像から一連のデザインワークフローを作成できます。

ファイル

ファイル	目的
backend/server_poe.py	FastMCP サーバー — 5つのMCPツール
backend/utils/poe_client.py	非同期httpxクライアント、Pydanticモデル、メディアのダウンロード
backend/tests/test_poe_mcp.py	87件のユニットテスト（APIキー不要）

動作の仕組み

1. ユーザーがReactフロントエンドを操作します。
2. フロントエンドは、チャットメッセージや会話管理などのリクエストをFastAPIバックエンドAPIに送信します。
3. チャットメッセージの場合、バックエンド（main.py）がリクエストを処理します。
   • プロバイダーレイヤーを介してLLMとやり取りすることがあります（デフォルトはOllamaです。その他のプロバイダーは設定で構成できます）。
   • ユーザーがUIからツール（例：ウェブ検索、SQLクエリ）を有効にした場合：
     • バックエンドは必要なコンテキストを準備します（例：SQL用のデータベーススキーマの取得）。
     • Ollamaモデルに、ツール固有の入力（例：SQLクエリやHubSpotのJSONペイロード）を生成するよう求める場合があります。
     • その後、バックエンドは該当するMCPサービスモジュール（サブプロセスとして管理：search、SQL、YouTube、HubSpot、Python、Codex）と通信します。
     • MCPサービスモジュールがツールを実行します（例：Serper.dev APIの呼び出し、MySQLへのクエリ）。
     • MCPサービスモジュールからの結果がバックエンドに返されます。
     • バックエンドは、最終的で十分な情報に基づいた回答を生成するため、ツールの結果を使ってOllamaに再度プロンプトを送る場合があります。
4. バックエンドは、MongoDBから会話履歴を保存／取得します。
5. 最終的な回答がフロントエンドにストリーミングされ、ユーザーに表示されます。

コンテキスト用 AI 要約

• 目的：ピン留めした会話から短い LLM 生成の要約をシステムプロンプトに追加し、以降のチャットで会話の全文を送信せずに過去の作業を参照できるようにします。
• 生成：
  • オンデマンドでユーザーが開始します（ヒューリスティックではありません）。要約のないチャットをピン留めすると、アプリは先に要約を生成するよう求め、完了するまでピン留めを保留します。
  • バックエンドは最近の会話を最大約 1000 語分（HTML を除去）まとめ、選択したモデルに、最大約 750 文字の単一段落の要約を生成するよう指示します。
  • 保存済みの要約は再利用され、自動再生成は行われません。
• 制限と適用：
  • ピン留めできる会話は最大 5 件です。バックエンドが上限を適用し、上限に達すると UI でピン留めが無効になります。
  • ピン留め数は UI に表示されます（例：「X/5 件をピン留め済み」）。
• モデルの選択：
  • Settings → Summaries → Select Model でモデルを選択します。チャットと同じプロバイダーのモデルカタログを使用します。
  • 要約用のモデルが設定されていない場合、モデルを選択するまで生成は失敗します。
• コンテキストの組み立て：
  • コンテキスト用にシステムプロンプトへ含められるのは保存済みの要約のみです。ヒューリスティックによる要約や自動要約は使用されません。
  • コンテキストサービスは、プロフィールのプロンプトと合わせて要約用の領域を確保します。
• メンテナンス：
  • 要約を一括削除したり、すべてのチャットのピン留めを解除したりして、状態をリセットする管理者用ユーティリティが用意されています。本番環境では慎重に使用してください。

API（参照）：

• 要約の設定：GET /api/summaries/settings、POST /api/summaries/settings { model_name }
• 要約の生成：POST /api/summaries/generate { conversation_id }
• ピン留め：POST /api/user-context/pin-conversation { conversation_id, pinned }（上限を適用）
• ピン留め数：GET /api/user-context/pin-stats → { count, max }

スケジュールタスク（タイムゾーンと一回限りの実行）

• Tasks パネル → Scheduled タブからスケジュールを作成します。
• モードは 2 種類あります。
  • 繰り返し：cron 式とタイムゾーンを指定します。次回の実行時刻は、選択したタイムゾーンの現地時刻に基づいて計算され（夏時間に対応）、UTC で保存されます。
  • 一回限り：日時とタイムゾーンを設定します。初回の実行後、自動的に無効になります。
• 「Run now」を実行でき、実行ごとにモデルを任意で上書きできます。

詳しくは TASKS_USER_GUIDE.md を参照してください。

カスタマイズ

• モデルプロバイダー：ヘッダーの Model Picker でプロバイダー／モデルを選択します。Settings でプロバイダーの API キーを設定してください。Ollama 以外のモデルは、設定後にのみ表示されます。
• Ollama モデル：利用可能なローカルモデルから選択するか、DEFAULT_OLLAMA_MODEL を設定します。コーディングに適したモデルは、SQL でより適切に動作する場合があります（例：codestral）。
• 検索結果：backend/main.py で処理する検索結果の数を調整します。
• データベーススキーマのコンテキスト：backend/main.py の MAX_TABLES_FOR_SCHEMA_CONTEXT を変更して、LLM に送信するテーブルスキーマの数を調整します。
• プロンプトエンジニアリング：backend/main.py で Ollama に送信するシステムプロンプトを変更し、応答と SQL 生成を調整します。
• スタイル：CSS ファイル、または frontend/src/ 内の React コンポーネントのスタイルを変更して、フロントエンドの外観をカスタマイズします。

セットアップと使い方（クイックスタート）

1. バックエンド：cd backend && uvicorn main:app --reload --port 8000
2. フロントエンド：cd frontend && npm install && npm run dev
3. アプリ内：
   • モデルを選択します（ヘッダー → モデルピッカー）。
   • 任意：設定を開いて、OpenAI などのプロバイダーキーを追加します。
   • ✨ ツールセレクターを使って、Smart Web Search、Database、YouTube、Python、HubSpot、Poe、Codex を実行します。
   • Canva の場合：backend/.env に CANVA_API_TOKEN を設定し、デザインの作成、インポート、またはエクスポートを AI に依頼します。
   • Figma の場合：backend/.env に FIGMA_ACCESS_TOKEN を設定し、ファイルの読み取りを AI に依頼します（例：「Figma ファイル ABC123 の構造を取得」）。
   • Poe の場合：backend/.env に POE_API_KEY を設定し、画像の生成や最新モデルとのチャットを AI に依頼します。
   • タスクパネルでは、アドホックタスクとスケジュール済みタスクをサポートしています。

前提条件：

• ローカルモデルを使う場合は Ollama が起動していること（モデルをプルします。例：ollama pull llama3.1）。
• MongoDB に接続できること（履歴／タスク用）。
• Canva の場合：Canva Connect API アクセストークン（セットアップ手順を参照）。
• Figma の場合：Figma のアカウント設定 → セキュリティ → Personal access tokens で取得したパーソナルアクセストークン。
• Poe の場合：poe.com/api/keys で取得した Poe API キー（Poe のサブスクリプションが必要です）。
• Codex の場合：Codex CLI をインストールし、実行を開始する前に OpenAI API キーを設定します（設定または環境変数を使用）。

更新

既存のデータ（MongoDB、ChromaDB、.env）に影響を与えずに最新バージョンへ更新するには：

# 1. Pull latest code
git pull origin main

# 2. Update backend dependencies
cd backend
pip install -r requirements.txt

# 3. Rebuild frontend
cd ../frontend
npm install
npm run build

# 4. Restart the backend
# Manually:
cd ../backend
uvicorn main:app --host 127.0.0.1 --port 8000

# macOS Launch Agent:
launchctl stop com.osoba.backend && launchctl start com.osoba.backend

# Linux systemd:
sudo systemctl restart osoba-backend

データは安全です：MongoDB（会話、タスク、ドキュメント、設定）と ChromaDB（セマンティックメモリ、KB 埋め込み）は、コードの更新では変更されない外部サービスです。.env ファイルは gitignore に登録されており、上書きされることはありません。

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。