v0.129.0 で App Settings へ移動

本ページの調整値は .env ではなく、アプリ内の App Settings 画面（サイドバー下部のスライダーアイコン）で設定し、app_settings.jsonc に保存されます。.env に残った値は無視され、起動ログにキー名が 1 度だけ列挙されます。既存の設定を引き継ぐには chatwalaau settings migrate --write を実行してください。機能の有効化ゲートと シークレットは .env のままです。詳細は設定 -> アプリケーション設定。

ナレッジと MCP

RAG パイプライン

PDF をアップロードし、ベクトル類似検索で内容について質問できます。

RAG にはモデルオファリングカタログ（model_offerings.jsonc）の embeddings オファリング が必要です。作成はアプリ内の App Settings 画面、chatwalaau models add、または手動で行えます:

{
  "id": "embed",
  "provider": "azure-openai",
  "operations": ["embeddings"],
  "model_ref": "text-embedding-3-small"
}

パイプラインの設定値は（モデルルーティングではないため）引き続き通常の .env の値です:

CHROMA_DIR=.chroma
RAG_COLLECTION_NAME=default
RAG_TOP_K=5
RAG_CHUNK_SIZE=800
RAG_CHUNK_OVERLAP=200
# RAG_CHUNK_MIN_SIZE=200   # 未設定 -> RAG_CHUNK_SIZE // 4、0 で末尾結合を無効化

embeddings オファリングが無い場合、RAG 検索・取り込みは追加を促す明確なメッセージを返します（アプリは通常どおり起動します）。

手順:

+ -> Attach PDF で文書をアップロード
取り込みジョブを投入 -- エージェントに 「この文書を取り込んで」 と依頼するか、 Pipelines ポータル（下記）を開いてファイルパスを指定し rag-ingest を投入
パイプラインジョブ実行: PDF 解析 -> チャンク化 -> 埋め込み -> ChromaDB 保存
質問: 「文書には X について何が書いてある？」
エージェントが出典付き（ファイル名・ページ）で回答

ポイント: ファイルベースの ChromaDB 保存、シングルトン埋め込みクライアント（資格情報解決と TLS ハンドシェイクはプロセスごとに 1 回）、末尾結合付きのオーバーラップチャンク化、メタデータによる出典、再取り込み時の自動重複排除、チャット内の PDF ファイルカード。取り込みは Pipeline ジョブエンジン（下記、組み込み）で実行されます。

v0.218.0 から、存在しないコレクションを検索すると Collection not found. と答え、何も作りません。検索範囲で、エージェントが検索するコレクションを限定し、その文書だけから答えさせることもできます。v0.220.0 からは、検索範囲を route に分け、 API のリクエストで、検索の前に決定モデルに1つを選ばせることもできます。

Pipeline ジョブ

データ処理タスク（現在は RAG 取り込み、今後ジョブ種別を追加）をインプロセスのパイプラインエンジンと専用の管理画面で実行します。サイドバー下部の Pipelines アイコン（Declarative Agents の隣）から:

ジョブ種別フォームから投入（例: rag-ingest に PDF パス）
プログレスバーで進捗をライブ表示
実行中ジョブのキャンセル、終了ジョブの削除
実行履歴の確認 -- 各実行は開いて見られる取得ログを保持

既定で有効（PIPELINE_ENABLED=true）。パイプラインジョブは curated なインプロセスジョブ種別（shell なし、CODING_ENABLED 不要）で、スケジュールスクリプト を実行し既定で無効の Cron スケジューラとは区別されます。設定:

# Pipeline ジョブ（インプロセスのデータ処理エンジン）
PIPELINE_ENABLED=true
PIPELINE_JOBS_DIR=.pipeline          # 1ジョブ1 JSON + output/{job}/{run}/ 実行ログ
PIPELINE_OUTPUT_MAX_BYTES=1048576    # 実行ごとの取得ログ上限
PIPELINE_MAX_CONCURRENT_JOBS=2

エージェントは manage_pipeline ツール（submit / list / get / cancel / delete）でもジョブを管理できます。エージェントツールと REST API（/api/pipeline/*）は同じエンジンとストアを共有するため、チャットとポータルが食い違うことはありません。

v0.188.0 から、ジョブ種類は処理を子プロセスで動かせます。中止やジョブ種類ごとの時間の上限で確実に止まり、ジョブ種類ごとに同時実行の枠も持てます。オントロジーはこれを、保存のたびに入る ontology-entailment ジョブに使います (同時に 1 件、既定の上限 600 秒)。ほかのジョブと同じくポータルに表示されます。 v0.189.0 から、SHACL の形状を持つオントロジーは、保存のたびに ontology-shacl ジョブが同じしくみで検証します (同時に 1 件、既定の上限 300 秒)。

`DEMO_MODE` での動作

デモホストではパイプラインは読み取り専用になります。ポータル・ジョブ一覧・実行履歴はそのまま利用できます（機能を隠すのではなく見せます）が、投入・キャンセル・削除は 409 で拒否され、manage_pipeline ツールはエージェントに提供されません。

理由は、すべての rag-ingest ジョブが、同梱デモコーパスを配信しているのと同じベクトルコレクションに書き込むためです。そのままでは、ある来訪者がアップロードした文書が別の来訪者の引用として返ってしまいます。REST エンドポイントだけを塞いでも不十分でした —— エージェントツールは同じエンジンを通して書き込むため、チャットで「この PDF を取り込んで」と言えば通ってしまいます。

MCP 連携

Model Context Protocol を介して外部ツールを接続します（Claude Desktop 互換設定）。ChatWalaʻau は同梱デフォルト（mcp_servers.default.jsonc）を持ち、オペレータ上書き（mcp_servers.jsonc、 gitignore 済み）を優先します。初回のコピーは不要です。

# 任意: 既定は mcp_servers.jsonc。空にすると MCP を無効化。
# MCP_CONFIG_FILE=mcp_servers.jsonc

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${EXAMPLE_API_TOKEN}" }
    }
  }
}

JSONC -- // と /* */ コメントを除去。厳密 JSON もそのまま受理するため、既存の Claude Desktop / Claude Code / Cursor 設定を再利用可能
stdio サーバ（command）は起動され、HTTP/SSE サーバ（url）は接続される
MCP ツールは組み込みツールと並び、Plug アイコンで表示
サーバのライフサイクルは自動管理（ゾンビプロセス防止つき）
任意のサーバ単位フィールド: "load_prompts": true（prompts/list 実装サーバ向け。既定 false）、"load_tools": false、"request_timeout": 30 (秒。省略すると呼び出しに時間制限はなく、Stop で終了できます)
${VAR} 参照（v0.206.0）-- env、headers、url の ${NAME} は、ファイルを読み込むときに .env（または環境変数）の値に置き換わります。トークンをファイルに書かずに済みます。未設定の変数を参照しているサーバは、変数名つきの警告とともに飛ばされ、ほかのサーバは起動します。平文の値も引き続き使えます。
"disabled": true（v0.206.0）-- サーバはファイルに残りますが接続されません（stdio サーバは起動しません）。"disabled_tools": ["名前", ...] で個別のツールを隠せます。どちらも MCP Servers 画面が書き込みます。

自作の Python MCP サーバ（MCP SDK 2、v0.203.0）

v0.203.0 から、ChatWalaʻau の Python 環境には MCP SDK 2.x が入っています（Microsoft Agent Framework 1.23 が要求するため）。影響があるのは、自作の Python MCP サーバを ChatWalaʻau 自身のインタプリタで動かしている場合（"command" が ChatWalaʻau の python を指している場合）だけです。 MCP SDK 2 では mcp.server.fastmcp が削除されたので、サーバを次のように書き換えてください。

# MCP SDK 1.x: from mcp.server.fastmcp import FastMCP; server = FastMCP("my-server")
from mcp.server.mcpserver import MCPServer

server = MCPServer("my-server")

デコレータ（@server.tool()、@server.resource(...)）と server.run() はそのままです。独自の環境で起動するサーバ（uvx、npx、別の仮想環境、バイナリ）は影響を受けません。構造化コンテンツを返したいツールには型付きの戻り値（TypedDict または Pydantic モデル）が必要です。素の dict はテキストとして返されます。

MCP サーバをアプリで管理する

サイドバーフッターの Plug（MCP） アイコンから MCP Servers 画面を開きます（フッターが混んでいる場合は右端の ... メニューを確認してください）。

v0.206.0 で変更

サーバをこの画面から追加・編集・テスト・削除できるようになりました。また、サーバやツールの無効化は mcp_servers.jsonc に保存され、再起動しても残ります。以前は、次の再起動までツールを無効にすることしかできませんでした。

サーバを追加・編集する

Add server をクリックします（またはサーバを選んで Edit）。
方式を選びます。stdio はサーバ機でコマンドを実行します（例: npx に -y とパッケージ名。引数は 1 行に 1 つ）。HTTP は URL に接続します。
環境変数（stdio）またはヘッダー（HTTP）を追加します。各行には**.env の変数名**を入れ、値は入れません。画面は ${NAME} として保存します（ヘッダーには方式を付けられ、 Bearer ${NAME} として保存されます）。行には、その変数が設定済みかどうかが表示されます。使う前に .env に変数を追加して再起動してください。
Test をクリックすると、そのサーバだけに接続してツールの一覧を表示します（何も保存しません）。
Save をクリックします。ファイルが書き換えられ、サーバが再接続されます。

知っておくこと:

保存するとファイルはコメントなしで書き換えられます。前のファイルは同じ場所に mcp_servers.jsonc.bak として残ります。mcp_servers.jsonc がまだない場合は、最初の保存で同梱の既定ファイル（変更されません）から作られます。
ファイルに手で書いた値（そのまま書いたトークン）は「kept」と表示され、サーバを編集してもそのまま残ります。.env に移して ${NAME} と書くことをおすすめします。
画面を開いた後にファイルが書き換えられていた場合、保存は拒否されます。画面を開き直してからやり直してください。
Remove は確認してから削除します。削除や名前変更をしたサーバを指定しているワークフローは、そのサーバに届かなくなります。

サーバとツールを無効にする

左でサーバ全体を、右で個別のツールを切り替えて（サーバが提供していればツールの説明も表示）、Save します。保存時は確認のうえ、適用中はブロッキングインジケータを表示します。
無効にしたツールは接続されたままですが、モデルには渡されません。毎ターンの入力トークン（各ツールの名前・説明・スキーマ）を節約できます。
無効にしたサーバは切断され（stdio サーバのプロセスは止まります）、「disabled」と表示されます。有効にして Save すると再び接続します。
Add・Edit・Remove は、切り替えの変更を保存か破棄するまで待ちます。
Reload は手で編集したファイルを読み直し、サーバを再接続します。設定済みだが未接続のサーバには「Reload to apply」のヒントが表示されます。

stdio サーバとほかの機械

stdio サーバは、バックエンドが自分の機械で起動するコマンドです。そのため ChatWalaʻau は、 stdio サーバの追加・編集・テストをその機械からだけ許します（Windows アプリと、同じ PC のブラウザは常に対象です）。LAN のスマートフォン、クラウドへのデプロイ、Docker コンテナへ接続したブラウザからは stdio がロックされて表示されます。HTTP サーバ、Remove、有効・無効の切り替えは、どこからでも使えます。

# ほかの機械からの stdio の編集を許可します。許可すると、API キー（スコープ api か admin）か Web ログインを持つ人が
# このサーバでコマンドを実行できます。LAN、クラウド、Docker では false のままにしてください。
# MCP_STDIO_REMOTE_EDIT=false

「その機械から」とみなすのは、loopback からの接続で、かつプロキシの転送ヘッダー（X-Forwarded-For、Forwarded、X-Real-IP、CF-Connecting-IP）がない場合だけです。同じ機械のトンネルやプロキシで外の人が同じ機械に見えないよう、リバースプロキシの X-Forwarded-For は残してください。
クラウドではリモート（HTTP）の MCP サーバを基本にしてください。コンテナで stdio サーバを使うには、イメージにその実行環境（npx なら node、uvx なら uv）が必要です。
この画面はオペレータ向け機能で、他の書き込み系エンドポイントと同じ認証で保護されます（localhost は除外）。設定はそのサーバの全ユーザに適用されます。

MCP Apps

MCP ツールが _meta.ui リソースを宣言すると、その HTML View がチャット内のインタラクティブ UI として、安全な二重 iframe サンドボックスで描画されます。 ChatWalaʻau は、正式な MCP Apps 仕様（2026-01-26）に従い、その公式 SDK で View を動かします（v0.204.0 から）。ほかの MCP Apps 対応クライアント向けに作られた View も、そのまま動きます。

# MCP_APPS_SANDBOX_PORT=8081   # 任意のサンドボックスプロキシポート

二重 iframe サンドボックス -- View は別オリジンで動作し、ホストの DOM・ Cookie・ストレージにアクセス不可。View のリソースが宣言しない外部リソースは CSP が遮断
監査可能 -- View からサーバへの通信はすべてホスト経由でプロキシ
ツール結果をそのまま渡す -- View はツールの入力と、structuredContent を含む結果全体を受け取る。View 自身の tools/call と resources/read には MCP プロトコル本来のキー（structuredContent、isError、mimeType、_meta）が返る
チャットとやり取りできる -- View はメッセージを送れる。それはあなたの次のターンになる（「Sent from the ... app」と表示。応答の生成中は断る）。また、チャットに表示せずに、次のターンでモデルに渡す文脈を View から渡せる
ツールの見え方 -- サーバーが app 専用としたツールはモデルに渡らず、View が呼べるのは app 向けのツールだけ
表示モード -- インラインとフルスクリーン。View は大きさを自分で合わせ、テーマにも追従する。 セッション永続化で、チャットを読み直しても View を作り直す
段階的強化 -- UI が使えない場合はテキストとして動作

設定不要で自動的に有効化され、サンドボックスプロキシは MCP サーバと同時に、アプリと同じホストで起動します。

別の PC や Docker から MCP Apps を使う

サンドボックスには、画面と同じホストの MCP_APPS_SANDBOX_PORT でつながります。ブラウザーが別の PC にあるときは、このポートにも届く必要があります。Docker では、ポートを公開し（-p 8081:8081）、ほかのネットワーク利用と同じく APP_HOST=0.0.0.0 を設定し、API キーを作ってください。サンドボックスが動いていないときは、View の場所にお知らせが出て、テキストの結果はそのまま残ります。

RAG パイプライン​

Pipeline ジョブ​

DEMO_MODE での動作​

MCP 連携​

自作の Python MCP サーバ（MCP SDK 2、v0.203.0）​

MCP サーバをアプリで管理する​

サーバを追加・編集する​

サーバとツールを無効にする​

stdio サーバとほかの機械​

MCP Apps​