hatch-marimo-sandbox — 再現性のある AI ノートブック環境

なぜ Hatch ＋ marimo なのか

再現性のある Pipenv

pyproject.toml を依存の単一 source of truth に。env 別に分割した環境と lock 固定で、どのマシンでも同じ環境が再現できます。

1 コマンド起動

hatch run dev:marimo edit notebooks/<file>.py の 1 本でノートブックが起動。開発・テスト・デプロイ導線をすべて hatch に統一。

連携を部品化

MCP・A2A・Ollama をそれぞれモジュールに分離。hatch_marimo_sandbox.api を通して notebook から薄く呼ぶだけ。

変更耐性

環境を用途別（dev / llm / mcp / test）に分離しているので、連携を追加・削除しても開発環境が壊れません。

アーキテクチャ

hatch_marimo_sandbox.config

環境変数の読み取りを dataclass に集約。Ollama / MCP / A2A の URL とタイムアウトを一元管理。

hatch_marimo_sandbox.llm.ollama

ollama.Client 経由の疎通チェック・モデル一覧・チャット。

hatch_marimo_sandbox.mcp.client

MCP 公式 SDK を用いた SSE クライアント（ツール一覧・ツール呼び出し）。

hatch_marimo_sandbox.a2a.client

httpx + JSON-RPC 2.0 による A2A タスク送信・結果取得。

hatch_marimo_sandbox.api

notebooks から呼ぶ薄い API 層。全疎通確認を同期関数 1 本で。

hatch_marimo_sandbox.cli

hms コマンドで settings / Ollama / MCP / A2A の疎通を CLI から確認。

チュートリアル

リポジトリを取得する

git clone https://github.com/watanabe3tipapa/hatch-marimo-sandbox.git
cd hatch-marimo-sandbox

環境を作る（依存は lock 済み）

初回は env 作成が走ります。以降は hatch run だけで再現できます。

hatch env create
hatch run dev:marimo edit notebooks/llm_chat.py

外部サービスの疎通を確認する

デフォルト値はローカル。MCP_SERVER_URL / A2A_AGENT_URL は設定しないと空として扱われます。

export OLLAMA_BASE_URL=http://localhost:11434
export MCP_SERVER_URL=http://localhost:8080/mcp   # MCP サーバがある場合
export A2A_AGENT_URL=http://localhost:5000/a2a    # A2A エージェントがある場合

# CLI で疎通確認
hatch run dev:hms ollama health
hatch run dev:hms mcp tools

サンプル MCP サーバーで試す

このリポジトリには学習用の MCP サーバーが3本同梱されています。mcp env に全部入っているので、まずはコレで接続確認できます。

# 1. echo — stdio 最小構成（echo / add / now / sleep）
hatch run mcp:echo-server

# 2. url-fetch — SSE + httpx で URL を取得（fetch_url）
export MCP_PORT=8011 && hatch run mcp:fetch-server

# 3. browser — SSE + Playwright で Chromium を操作（navigate / extract_text / screenshot / evaluate_js）
export MCP_PORT=8012 && hatch run mcp:browser-server

初回のみブラウザバイナリを導入:

hatch run mcp:python -m playwright install chromium

notebook を起動する

notebooks/ にあるデモ（llm_chat.py など）をブラウザで開き、設定確認 → Ollama 疎通 → チャット → MCP ツール一覧 → A2A 送信を試せます。

hatch run dev:marimo edit notebooks/llm_chat.py

ヒント — notebook からは hatch_marimo_sandbox.api の同期関数だけを呼びます。 API 層が asyncio と env / URL の面倒を見るので、notebook のセルは 1 行で完結します。

解析・開発のヒント

ログは一元管理

hatch_marimo_sandbox.log がリクエスト/エンドポイント/例外を一箇所に集約。LOG_LEVEL で制御できます。

テストは全部モック

pytest + pytest-mock で外部依存に触れずに全機能を検証。CI でも再現できます。

URL はコードに埋めない

設定は環境変数に集約。hms config で解決後の値を確認できます。

サーバーの code は再掲できる

servers/ の3本は MCP 2.0(MCPServer)の最小形。Playwright は async API でなくては asyncio 内で動きません。

FAQ

Python 3.12 なのに test 環境が 3.14 で作られるのは？

hatch の python = "isolated" 設定により、インストール済みの最新 Python が選ばれることがあります。2026/8/10 時点で調査中です（DEV-MEMO 参照）。

MCP / A2A サーバは動くの？

このプロジェクトはクライアント専任です。ただし hatch run mcp:echo-server など学習用のサンプル MCP サーバー3本（echo / url-fetch / browser）を同梱しています。

Ollama が無くても notebook は動く？

動きます。疎通確認が False になるだけで、GUI とドキュメント機能はそのまま使えます。

テストはどう実行する？

hatch run test:pytest

こんなことが確認できるデモ

設定確認

show_config() が解決後の settings を表示。URL / モデル / ログレベルが一目でわかります。

Ollama 疎通

ollama_health_check() / ollama_list_models() / ollama_chat() でモデルの応答まで試せます。

MCP ツール

mcp_list_tools() で接続先のツール一覧を表示し、mcp_call_tool() で実行できます。

A2A タスク

a2a_send_task() でエージェントへタスクを送信し、結果を確認できます。

依存のブレを Hatch で封じ、MCP / A2A / Ollama を 1 コマンドで起動