jupyter-sage-mcp

jxta/jupyter-sage-mcp

3.1

If you are the rightful owner of jupyter-sage-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Jupyter SageMath MCP Server is a versatile environment supporting both SageMath and Python kernels, integrated with the Model Context Protocol (MCP) for enhanced computational capabilities.

🪐 ✨ Jupyter SageMath MCP Server

Binder License: MIT Python 3.11+ SageMath

SageMathとPythonカーネルの両方をサポートするModel Context Protocol (MCP) 対応Jupyter環境です。mybinder.orgとNII解析基盤の両方で利用可能です。

🚀 クイックスタート

🌐 MyBinder.org で即座に試す(推奨)

以下のボタンをクリックするだけで、ブラウザ上でSageMath対応MCP環境が起動します:

Binder

✨ 起動後の手順:

  1. 環境構築(3-5分)を待つ
  2. JupyterLabが自動で開く
  3. notebooks/test_mcp.ipynb でテスト実行
  4. 利用可能カーネル:
    • Python 3: データサイエンス、機械学習
    • SageMath: 数学計算、数論、暗号学

📝 注意事項:

  • セッション時間: 最大2時間
  • メモリ制限: 2GB
  • 重要なファイルは定期的にダウンロード保存を推奨

🏠 ローカル環境での実行

git clone https://github.com/jxta/jupyter-sage-mcp.git
cd jupyter-sage-mcp
conda env create -f environment.yml
conda activate jupyter-mcp-sage
chmod +x postBuild
./postBuild
jupyter lab

📋 特徴

✨ 主な機能

  • 🔬 SageMath統合: 数式処理、数論、代数、暗号学、グラフ理論
  • 🐍 Python データサイエンス: pandas, numpy, matplotlib, scipy統合
  • 🔄 マルチカーネル対応: SageMathとPythonの動的切り替え
  • 🌐 MCP互換: Claude Desktop, Cursor, VS Code等と連携
  • ⚡ リアルタイム実行: コード実行結果の即座表示
  • 🛠️ 外部MCP接続: 他のMCPサーバーとの連携

🎯 対応環境

環境状態特徴制限
🌐 mybinder.org即座利用可能、セットアップ不要2時間セッション
🏫 NII解析基盤永続化・高性能認証設定要
🏠 ローカル環境フル機能セットアップ要

📁 ファイル構成

jupyter-sage-mcp/
├── README.md                   # このファイル
├── environment.yml            # Conda環境設定(SageMath含む)
├── requirements.txt           # Python追加パッケージ
├── runtime.txt               # Python版指定(MyBinder用)
├── postBuild                 # Binder用セットアップスクリプト
├── start                     # Binder用起動スクリプト
├── src/
│   └── mcp_sage_helper.py    # MCPクライアント実装
├── notebooks/
│   ├── test_mcp.ipynb        # 基本テスト用
│   └── sage_mcp_demo.ipynb   # デモノートブック
├── config/
│   └── claude_config.json    # Claude Desktop設定例
└── docs/
    └── examples/             # 使用例集

🔧 セットアップ詳細

1. 依存関係

Conda環境(推奨)
conda env create -f environment.yml
conda activate jupyter-mcp-sage
手動インストール
# SageMath
conda install -c conda-forge sagemath

# Jupyter環境
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2
pip install datalayer_pycrdt==0.12.17

# MCP関連
pip install websockets requests nest-asyncio

2. カーネル設定

# SageMathカーネル登録
sage -python -m ipykernel install --user --name sagemath --display-name "SageMath"

# 確認
jupyter kernelspec list

3. Claude Desktop連携

~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jupyter-sage": {
      "command": "python",
      "args": ["path/to/src/mcp_sage_helper.py"],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "your_token"
      }
    }
  }
}

📝 使用方法

🌐 MyBinder.orgでの基本使用

  1. 環境起動

    • Binder をクリック
    • 環境構築完了まで3-5分待機
  2. テストノートブック実行

    # notebooks/test_mcp.ipynb を開く
    # 各セルを順次実行してテスト
    
  3. SageMath機能テスト

    # SageMathカーネルで実行
    factor(2^100 - 1)
    plot(sin(x), (x, 0, 2*pi))
    
  4. データサイエンステスト

    # Python 3カーネルで実行
    import pandas as pd
    import matplotlib.pyplot as plt
    
    df = pd.DataFrame({'x': range(10), 'y': [i**2 for i in range(10)]})
    df.plot()
    plt.show()
    

基本的なMCP機能

# MCPクライアントのセットアップ
from src.mcp_sage_helper import setup_sage_mcp
mcp = setup_sage_mcp()

# SageMathコードの実行
sage_result = mcp.execute_code("""
var('x y')
f = x^2 + y^2
solve(f == 25, x)
""", kernel_type="sagemath")

print(sage_result)

カーネル切り替え

# 現在のカーネル確認
print("Current kernel:", mcp.current_kernel)

# SageMathに切り替え
mcp.switch_kernel_context("sagemath")

# Pythonに切り替え
mcp.switch_kernel_context("python")

マルチカーネル処理例

# SageMathで数学計算
sage_result = mcp.execute_code("""
# 楕円曲線暗号
p = 23
E = EllipticCurve(GF(p), [1, 0])
print(f"Elliptic curve points: {E.order()}")
""", kernel_type="sagemath")

# Pythonでデータ可視化
python_result = mcp.execute_code("""
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 2*np.pi, 100)
plt.plot(x, np.sin(x))
plt.title('Sine Wave')
plt.show()
""", kernel_type="python")

🎯 実用例

1. 数学研究

# 数論的関数の解析
sage_code = """
# 完全数の研究
def is_perfect(n):
    return sum(divisors(n)[:-1]) == n

perfects = [n for n in range(2, 10000) if is_perfect(n)]
print("Perfect numbers up to 10000:", perfects)

# メルセンヌ素数
mersenne_primes = []
for p in primes(20):
    mp = 2^p - 1
    if mp.is_prime():
        mersenne_primes.append((p, mp))
        
print("Mersenne primes:", mersenne_primes)
"""

2. データサイエンス

# 統計分析とMCPの組み合わせ
analysis_code = """
import pandas as pd
import numpy as np
from scipy import stats

# データ生成
np.random.seed(42)
data = {
    'treatment': np.random.choice(['A', 'B'], 1000),
    'outcome': np.random.normal(50, 10, 1000)
}
df = pd.DataFrame(data)

# A/Bテスト
group_a = df[df['treatment'] == 'A']['outcome']
group_b = df[df['treatment'] == 'B']['outcome']

t_stat, p_value = stats.ttest_ind(group_a, group_b)
print(f"t-statistic: {t_stat:.4f}")
print(f"p-value: {p_value:.4f}")
"""

3. 暗号学研究

# 楕円曲線暗号の実装
crypto_code = """
# ECDH鍵交換のシミュレーション
p = 2^255 - 19  # Curve25519のp
F = GF(p)
E = EllipticCurve(F, [-1, 0])

# Alice の秘密鍵と公開鍵
alice_private = randint(1, E.order()-1)
alice_public = alice_private * E.random_point()

# Bob の秘密鍵と公開鍵  
bob_private = randint(1, E.order()-1)
bob_public = bob_private * E.random_point()

# 共有秘密の計算
shared_secret_alice = alice_private * bob_public
shared_secret_bob = bob_private * alice_public

print("ECDH key exchange successful:", shared_secret_alice == shared_secret_bob)
"""

🌐 外部MCP接続

外部のMCPサーバーと連携することも可能です:

import asyncio

async def connect_external():
    # 外部MCPサーバーへの接続
    connection = await mcp.connect_external_mcp(
        "wss://math-mcp-server.example.com/ws",
        auth_token="your_token_here"
    )
    
    if connection["status"] == "success":
        print("✅ External MCP connected!")
        # 外部ツールの使用
        result = await mcp.call_external_tool(
            connection["connection_id"],
            "solve_equation",
            {"equation": "x^2 + 2*x + 1 = 0"}
        )
        print("External result:", result)
    
# 実行
await connect_external()

📚 サンプルノートブック

  • 基本機能テスト
  • Python & SageMath動作確認
  • 簡単な数学計算例

  • MCPセットアップ
  • SageMath基本機能
  • Pythonデータ分析
  • カーネル切り替え
  • 高度な数学計算例

🛠️ 高度な設定

NII解析基盤での使用

# SSH接続後
module load miniconda3
conda env create -f environment.yml
conda activate jupyter-mcp-sage

# ポートフォワーディングでJupyterLab起動
jupyter lab --port 8888 --no-browser \
    --ServerApp.token='nii_mcp_token' \
    --ip=0.0.0.0

VS Code統合

VS Codeの.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "jupyter_token",
      "description": "Jupyter Token",
      "password": true
    }
  ],
  "servers": {
    "jupyter-sage": {
      "command": "python",
      "args": ["src/mcp_sage_helper.py"],
      "env": {
        "JUPYTER_TOKEN": "${input:jupyter_token}"
      }
    }
  }
}

🔧 トラブルシューティング

よくある問題

1. SageMathカーネルが見つからない
# 強制再インストール
sage -python -m ipykernel install --user --name sagemath --display-name "SageMath" --force
jupyter kernelspec list
2. MCP接続エラー
# デバッグモード有効化
import logging
logging.basicConfig(level=logging.DEBUG)

# 接続状態確認
print("System info:", mcp.get_system_info())
3. MyBinder環境でのタイムアウト
  • セッション時間制限(2時間)を考慮
  • 重要な作業は定期的にダウンロード保存
  • 長時間の計算は分割実行
4. パッケージ不足エラー
# 追加パッケージのインストール
pip install package_name

# 環境の再構築
conda env update -f environment.yml

🧪 テスト

自動テスト実行

# テストスイートの実行
python -m pytest tests/

# MCPクライアントのテスト
python src/mcp_sage_helper.py

手動テスト手順

  1. 環境確認

    from src.mcp_sage_helper import setup_sage_mcp
    mcp = setup_sage_mcp()
    print(mcp.get_system_info())
    
  2. SageMath機能テスト

    result = mcp.execute_code("factor(2^128-1)", "sagemath")
    print(result)
    
  3. Python機能テスト

    result = mcp.execute_code("import numpy; print(numpy.__version__)", "python")
    print(result)
    

📊 パフォーマンス

ベンチマーク結果

操作SageMathPython備考
基本計算~10ms~5ms小規模計算
因数分解~100msN/Afactor(2^64-1)
行列演算~50ms~30ms1000×1000行列
グラフ描画~200ms~150ms基本プロット

メモリ使用量

  • SageMath環境: ~500MB(基本)
  • Python環境: ~200MB(基本)
  • MCP オーバーヘッド: ~10MB

🔐 セキュリティ

セキュリティ対策

  1. コード実行の制限

    • 危険な操作(ファイルシステムアクセス等)の制限
    • サンドボックス環境での実行
  2. MCP通信の暗号化

    • WebSocket接続のTLS暗号化
    • 認証トークンの安全な管理
  3. アクセス制御

    • IP制限の設定可能
    • セッショントークンによる認証

推奨セキュリティ設定

# セキュアなMCP設定例
secure_config = {
    "max_execution_time": 30,  # 実行時間制限
    "allowed_modules": ["numpy", "matplotlib"],  # 許可モジュール
    "sandbox_mode": True,  # サンドボックス有効
    "log_all_executions": True  # 実行ログ記録
}

🤝 貢献

開発に参加する

  1. リポジトリをフォーク
  2. 機能ブランチを作成
    git checkout -b feature/amazing-feature
    
  3. 変更をコミット
    git commit -m 'Add amazing feature'
    
  4. ブランチにプッシュ
    git push origin feature/amazing-feature
    
  5. プルリクエストを作成

貢献ガイドライン

  • コードスタイル: PEP 8準拠
  • テスト: 新機能には必ずテストを追加
  • ドキュメント: 変更内容をREADMEに反映
  • コミットメッセージ: 明確で詳細な説明

バグレポート

GitHubのIssueでバグを報告してください:

  • 環境情報(OS、Pythonバージョン等)
  • 再現手順
  • 期待される動作
  • 実際の動作
  • エラーメッセージ

📄 ライセンス

このプロジェクトはMIT Licenseの下で公開されています。詳細は ファイルをご覧ください。

🙏 謝辞

📞 サポート

ヘルプが必要な場合

  1. ドキュメントを確認: README、ノートブック例
  2. GitHubのIssue: バグや機能要求
  3. ディスカッション: 使用方法に関する質問

よくある質問 (FAQ)

Q: Binderで2時間制限を回避できますか?
A: Binderの制限は変更できません。長時間の作業にはローカル環境またはNII解析基盤をご利用ください。

Q: 新しいSageMathパッケージを追加できますか?
A: environment.ymlを編集してパッケージを追加し、Binderを再起動してください。

Q: MCPサーバーが起動しない場合は?
A: ポート競合やファイアウォール設定を確認してください。デバッグモードで詳細情報を取得できます。


🎉 今すぐ試す: Binder