[](LICENSE) [](https://hatch.pypa.io) [](https://github.com/watanabe3tipapa/hatch-marimo-sandbox) [](https://github.com/watanabe3tipapa/hatch-marimo-sandbox/commits/main) [](https://watanabe3tipapa.github.io/hatch-marimo-sandbox/) [日本語](README.md) | [English](README_en.md) # hatch-marimo-sandbox Hatch で依存を再現可能に管理する marimo ノートブック環境と、MCP / A2A / Ollama 連携をモジュール化した個人利用向け AI 開発サンドボックスです。 - ランディング／チュートリアル: https://watanabe3tipapa.github.io/hatch-marimo-sandbox/ ## 概要 このリポジトリは、notebook 上での LLM / MCP / A2A 連携を「使い捨てコード」ではなく再現可能・保守しやすい形で扱うことを目的としています。 依存は Hatch の env / lock ファイルで固定し、連携の実装は src/hatch_marimo_sandbox/ 配下のモジュールに分離。notebook からは薄い API 層（hatch_marimo_sandbox.api）を呼ぶ構成になっています。 注: 本プロジェクトは MCP / A2A のクライアント実装を提供します。サーバ／エージェントは別途用意し、接続先は環境変数で指定してください。 ## 主な機能 - Hatch による環境分離（dev / llm / mcp / test など） - pylock による依存の固定化 - ノートブック向けの「薄い API 層」（show_config / ollama_* / mcp_* / a2a_* 系） - 疎通確認用 CLI（hms コマンド、ollama/mcp/a2a の疎通確認など） - 環境変数による設定集約（コード内ハードコードを排除） - 学習用のサンプル MCP サーバー（echo / url-fetch / browser） - モック中心のテスト（pytest + pytest-mock など） ## 対応環境 - Python 3.12（.python-version に記載） - macOS / Linux（開発コマンド例が主に想定） - hatch >= 1.x ## インストール（確認済みの手順） ```bash git clone https://github.com/watanabe3tipapa/hatch-marimo-sandbox.git cd hatch-marimo-sandbox # 環境作成（初回のみ。依存は pylock.*.toml に固定済み） hatch env create ``` ## クイックスタート ノートブックを起動する例: ```bash hatch run dev:marimo edit notebooks/llm_chat.py ``` 外部サービスの疎通を CLI で確認する例（環境変数は必要に応じて設定してください）: ```bash 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 エージェントがある場合 hatch run dev:hms config # 解決後の設定を表示 hatch run dev:hms ollama health # Ollama 疎通確認 hatch run dev:hms ollama models # Ollama のモデル一覧 hatch run dev:hms mcp tools # MCP のツール一覧 hatch run dev:hms a2a "タスク内容" # A2A タスク送信 ``` テスト実行: ```bash hatch run test:pytest ``` ## ノートブックから呼べる API（サマリ） - show_config() — 解決済み settings を表示 - ollama_health_check() — Ollama 疎通確認 (bool) - ollama_list_models() — モデル一覧取得 - ollama_chat(message, model?) — チャット応答 - mcp_list_tools() — MCP のツール一覧取得 - mcp_call_tool(name, args?) — MCP ツール呼び出し - a2a_send_task(task, metadata?) — A2A タスク送信 - a2a_get_result(task_id) — A2A 結果取得 （詳細は notebooks/ と src/hatch_marimo_sandbox/ を参照してください） ## サンプル MCP サーバー（学習用） このリポジトリには学習用のサンプル MCP サーバーが3本含まれます。各サーバーの起動コマンドは pyproject.toml の project.scripts で定義されています。 - echo: stdio ベース（ツール: echo / add / now / sleep） — 起動例: `hatch run mcp:echo-server` - url-fetch: SSE + httpx（ツール: fetch_url） — 起動例: `MCP_PORT=8011 hatch run mcp:fetch-server` - browser: SSE + Playwright（ツール: navigate / extract_text / screenshot / evaluate_js） — 起動例: `MCP_PORT=8012 hatch run mcp:browser-server` browser サーバーの初回起動時には Chromium を導入する必要があります（README に沿ったコマンドあり）。 ## 環境変数（要約） - OLLAMA_BASE_URL: デフォルト `http://localhost:11434`（Ollama のホスト） - OLLAMA_DEFAULT_MODEL: デフォルト `llama3`（ollama_chat の既定モデル） - MCP_SERVER_URL: MCP SSE サーバの URL（デフォルト無し） - MCP_TIMEOUT: デフォルト `30`（秒） - A2A_AGENT_URL: A2A エージェントの URL（デフォルト無し） - A2A_TIMEOUT: デフォルト `30`（秒） - LOG_LEVEL: デフォルト `INFO` （詳細はソースの config モジュールや notebooks を参照してください） ## ディレクトリ構成（概観） ``` hatch-marimo-sandbox/ ├── notebooks/ # marimo notebook (.py) │ ├── llm_chat.py # Ollama / MCP / A2A 連携デモ │ ├── news_scraper.py │ └── ... ├── src/hatch_marimo_sandbox/ │ ├── api.py # notebook 用薄い API 層 │ ├── cli.py # 疎通確認 CLI（hms コマンド） │ ├── config.py # 環境変数読み取り │ ├── log.py # ログ統一 │ ├── llm/ollama.py # Ollama 疎通・チャット │ ├── mcp/client.py # MCP クライアント │ └── a2a/client.py # A2A クライアント ├── servers/ # サンプル MCP サーバー（学習用） │ ├── echo/echo_server.py │ ├── fetch/fetch_server.py │ └── browser/browser_server.py ├── tests/ # モック中心のテスト ├── pyproject.toml # 依存の source of truth（env / scripts 定義あり） ├── pylock.*.toml # env 別 lock └── DEV-MEMO.md # 設計・仕様・作業ログ ``` ## 利用可能な CLI エントリポイント（pyproject.toml 記載） - hms (hatch_marimo_sandbox.cli:main) - echo-server (servers.echo.echo_server:main) - fetch-server (servers.fetch.fetch_server:main) - browser-server (servers.browser.browser_server:main) ## ドキュメント 設計・仕様・作業ログ: DEV-MEMO.md LP・チュートリアル: https://watanabe3tipapa.github.io/hatch-marimo-sandbox/ ## 開発・保守状況 - リポジトリのバッジは「Maintenance: Active」と表示されています。 - 依存管理・env 分離は Hatch（pylock.*.toml を含む）で管理されています。 ## 貢献方法 歓迎します。README に記載の一般的なワークフロー: 1. Fork する 2. フィーチャーブランチを作成する（例: git checkout -b feature/amazing-feature） 3. 変更をコミットする（例: git commit -m 'Add amazing feature'） 4. ブランチへ push する（例: git push origin feature/amazing-feature） 5. Pull Request を開く ## ライセンス MIT License — LICENSE ファイルを参照してください。 ## 連絡先 GitHub: https://github.com/watanabe3tipapa/hatch-marimo-sandbox