GEMINI.mdの主要内容

核心機能

• デフォルトでPersistent Kernelを使用する（use_kernel=True）
• ユーザーが「リセット」と言ったときはreset_kernel()を使用する

会話開始時のチェックリスト

1. kernel_status() - カーネルの状態を確認する
2. recall() - 長期記憶を読み込む
3. list_files() - 既存のアセットを確認する

技術的な好み

• クローラーはrequests + BeautifulSoupを優先する
• ウェブページを開くにはwebbrowser.open()を使用する

### kernel_server.pyの説明
これはバックグラウンドで実行される**Persistent Kernelプロセス**で、手動で起動する必要はありません。

┌──────────────────┐ socket ┌──────────────────┐ │ PyRunner_MCP.py │ ◄───────────► │ kernel_server.py │ │ (MCP Server) │ 127.0.0.1:9999 │ (Python Kernel) │ └──────────────────┘ └──────────────────┘ │ ▼ global_namespace = {} （変数はすべてここに保存される）

** 安全防護（Auto-Safe Mode - "The Vaccine"）**：
- **Unified Process Core**：すべての子プロセス（Python/Pip/Shell）は統一されたコアによって駆動され、出力のリダイレクトと環境の浄化が強制されます。
- **Deadlock Immunity**：WindowsでのPipe Bufferの満杯やDLLのロックによるデッドロック問題を完全に解決します。
- **Auto Monkey Patch**：`yfinance`などのライブラリのマルチスレッド動作を自動的に攔截し、カーネルの安定性を確保します。

> 💡 **使用アドバイス**
> 
> 現在はすべてのタスクに`use_kernel=True`（Direct Kernel Mode）を使用することをおすすめします。システムには既に防護機能が組み込まれているため、デッドロックの心配はありません。

## ✨ 主な機能
PyRunner MCPは、[Model Context Protocol (MCP)](https://modelcontextprotocol.io) Serverであり、AIアシスタント（Gemini CLIなど）が以下のことを可能にします。
- **Pythonコードの実行** - 永続的なカーネルで実行され、変数は複数の実行にまたがって保持されます。
- **Pythonパッケージの管理** - 依存関係の迅速なチェックと自動インストール。
- **スクリプトの意味的な検索** - 記述やタグを使用して以前に作成したスクリプトを見つけます。
- **長期記憶** - ユーザーの好み、プロジェクトの背景、よく使用するコマンドを記憶します。
- **Shellコマンドの実行** - Git clone、pip install、システムコマンドなど。

### 核心機能：Persistent Kernel
**Jupyter Notebook**に似た体験をコマンドラインで提供します。
- 10GBのDataFrameを一度読み込むと、後続の分析で再読み込みする必要がありません。
- 大型のパッケージ（pandas、torch）を一度インポートすると、後続の実行は瞬時に開始されます。
- 変数、関数、クラスは持続的に存在します。

https://github.com/user-attachments/assets/4b63e67b-a7dc-4b75-ab78-07ea6aa67314

## 🔧 技術詳細
### なぜこれが必要なのか？
#### 2025年のAIツールは非常に強力です
| ツール | 能力 |
|------|------|
| **Gemini CLI** | コードの実行、会話の記憶、ファイルの読み書き、パッケージのインストール |
| **VS Code Copilot** | Agent Mode、@workspace、ファイル間の操作 |

**では、PyRunner MCPの価値は何でしょうか？**

#### 核心的な違い：Persistent Kernel

┌─────────────────────────────────────────────────────────────┐ │ Gemini CLI / Copilot PyRunner MCP │ │ ───────────────────── ──────────── │ │ 各実行 = 新しいプロセス 変数は実行をまたいで保持される │ │ │ │ x = 100 ──実行──► x は消える x = 100 ──実行──► x は残る │ │ print(x) ──実行──► エラー print(x) ──実行──► 100 │ └─────────────────────────────────────────────────────────────┘

### 機能比較
| 機能 | Gemini CLI | VS Code Copilot | **PyRunner MCP** |
|------|:----------:|:---------------:|:----------------:|
| Pythonの実行 | ✅ | ✅ | ✅ |
| パッケージのインストール | ✅ | ✅ | ✅ |
| ファイルの読み書き | ✅ | ✅ | ✅ |
| ファイル間の操作 | ✅ | ✅ | ✅ |
| **変数の実行をまたいでの保持** | ❌ | ❌ | ✅ |
| **カーネルの状態監視** | ❌ | ❌ | ✅ |
| **変数の表示/リセット** | ❌ | ❌ | ✅ |
| **長時間のタスクでの非ブロッキング** |  ブロックする可能性がある |  ブロックする可能性がある | ✅ |
| 意味的なスクリプト検索 |  ファイル名検索 |  @workspace |  metadata |

### 独自の優位性
#### 1. stdout/stderrのリダイレクト（ブロックしない）
**問題**：SSH接続、ping監視、ウェブクローリングなどの長時間のタスクを実行するとき、元のツールはpipe bufferがいっぱいになることでブロックする可能性があります。

**PyRunnerの解決策**：
```python
# 出力は自動的にファイルにリダイレクトされ、ブロックしません
stdout → temp/stdout.txt
stderr → temp/stderr.txt

適用シーン：

• SSHリモート実行（netmiko、paramiko）
• ネットワーク監視（ping、traceroute）
• 大量の出力を伴うクローリングタスク
• ループタスクとデーモン

2. パッケージのチェックが極めて高速（マイクロ秒単位）

# MCPプロセス内で直接チェックし、サブプロセスを起動しません
check_packages("pandas numpy torch")
# ✓ インストール済み: pandas, numpy
# ✗ 未インストール: torch

3. 記憶システム（構造化JSON）

remember("ユーザーの好み: Blackフォーマット", category="preference")
remember("Project XのAPI: https://api.x.com", category="project")

recall("API")  # 関連する記憶のみを検索

4. Shellコマンドのクリーンな環境

run_shell("git clone https://github.com/xxx/yyy")

自動処理：

• GIT_TERMINAL_PROMPT=0（対話型プロンプトを無効にする）
• GIT_LFS_SKIP_SMUDGE=1（大きなファイルをスキップする）
• 作業ディレクトリを統一する（BASE_DIR）

適用シーン

PyRunner MCPに適しているシーン

• データ分析：10GBのCSVを一度読み込むと、後続の分析で再読み込みする必要がありません。
• 機械学習：モデルを一度読み込むと、繰り返しテストや推論を行うことができます。
• 対話型開発：Jupyter Notebookに似たCLI体験を提供します。
• 大量の独立したスクリプト：メタデータを使用して管理と検索を行うことができます。

不適切なシーン（元のツールの方が良い）

• 完全なプロジェクト開発（src/、tests/構造がある）→ Copilot @workspace
• チーム協力、PRレビュー、CI/CD → GitHub Copilot Workspace
• 多言語プロジェクト → 元のGemini CLI

💻 使用例

基本的な使用法

Persistent Kernel

# 最初の実行
あなた: sales.csvを読み込む
AI: save_and_run("load.py", "import pandas as pd; df = pd.read_csv('sales.csv')", use_kernel=True)
✓ 成功

# 2回目の実行（dfはまだ存在！）
あなた: 最初の5行を表示する
AI: save_and_run("show.py", "print(df.head())", use_kernel=True)
✓ [DataFrameを表示]

# CSVを再読み込みする必要はありません！

カーネル管理ツール

# 状態を確認する
kernel_status()
# 🟢 KERNEL状態
# ├─ 実行時間: 15分32秒
# ├─ 変数の数: 8個
# └─ メモリ使用量: 45.2 MB

# 変数を確認する
inspect_kernel_vars()
# 📦 KERNEL変数（合計3個）
# ├─ df (DataFrame, 15.2 MB)
# ├─ model (Sequential, 102.5 MB)
# └─ config (dict, 1.2 KB)

# リセットする
reset_kernel()
# 🔄 カーネルがリセットされ、すべての変数がクリアされました

意味的な検索

search_workspace("PTTクローラー")
# → fetch_ptt.py (関連度:4) [crawler, ptt]
#   PTTの掲示板の最新記事をクロールする

📚 ドキュメント

🛠️ 完全なツールリスト

プロジェクト構造

PyRunner_MCP/
├── PyRunner_MCP.py       # MCP Serverのメインプログラム
├── kernel_server.py      # Persistent Kernelプロセス
├── GEMINI.md             # AI行動ガイド
├── workspace/            # スクリプトの保存場所
│   ├── *.py              # Pythonスクリプト
│   └── *.meta.json       # メタデータ（検索用）
├── temp/                 # 一時ファイル（stdout/stderr）
└── memory.json           # 長期記憶