Ultimate64mcp

## 🚀 Commodore 64 Ultimate — MCP Server

このプロジェクトは、公式のモダンなCommodore 64コンピュータである**Commodore 64 Ultimate**用の**Model Context Protocol (MCP)**サーバーです。このサーバーを使用すると、ClaudeやChatGPT、CursorなどのAIアシスタントがUltimateのREST APIを介してCommodore 64を制御できます。

## 🚀 クイックスタート

### 前提条件
- Python 3.11以上
- ネットワーク上にある**Commodore 64 Ultimate**（またはUltimate 64/II+/II+L）
- UltimateのREST APIにアクセス可能であること（デフォルトで有効）

### インストール
```bash
# リポジトリをクローン
git clone https://github.com/yourusername/ultimate64-mcp.git
cd ultimate64-mcp/mcp_hosted

# 依存関係をインストール
pip install -r requirements.txt

サーバーの起動

オプション1: 環境変数（推奨）

# UltimateデバイスのIPアドレスを設定
export C64_HOST="192.168.1.64"

# サーバーを起動
python mcp_ultimate_server.py

オプション2: コマンドライン引数

python mcp_ultimate_server.py http://192.168.1.64

オプション3: 動的接続

最初はホストを設定せずに起動し、後でultimate_set_connectionツールを使用して接続を設定します。

python mcp_ultimate_server.py
# サーバーが起動した後、ultimate_set_connectionツールを使用して接続

サーバーはデフォルトでhttp://0.0.0.0:8000で実行されます。

✨ 主な機能

• 37のツール：Ultimateデバイスの主要な機能を網羅
• 2種類のトランスポートモード：STDIO（ローカル）とSSE（リモート/ホステッド）
• Dockerサポート：簡単なコンテナ化デプロイ
• 動的接続：実行時にC64の接続を設定可能
• Base64/URLを介したPRGのアップロード：どこからでもプログラムを実行可能
• デフォルトでセキュア：非ルートのDockerコンテナで実行

📦 インストール

リポジトリのクローン

git clone https://github.com/yourusername/ultimate64-mcp.git
cd ultimate64-mcp/mcp_hosted

依存関係のインストール

pip install -r requirements.txt

💻 使用例

基本的な使用法

サーバーの起動（環境変数を使用）

export C64_HOST="192.168.1.64"
python mcp_ultimate_server.py

サーバーの起動（コマンドライン引数を使用）

python mcp_ultimate_server.py http://192.168.1.64

高度な使用法

動的接続でサーバーを起動

python mcp_ultimate_server.py
# サーバーが起動した後、ultimate_set_connectionツールを使用して接続

📚 ドキュメント

これは何ですか？

Commodore 64 Ultimate

Commodore 64 Ultimateは公式のCommodore製品で、現代にふさわしい新しいCommodore 64です。内部では、Gideon's LogicのGideon Zweijtzerによって設計されたUltimate 64 FPGAメインボードの改訂版を使用しています。これはエミュレータではなく、サイクル精度が高く、現代の技術を用いて構築された本物のCommodore 64です。

Commodore 64 Ultimateには、USBストレージ、イーサネット、HDMI出力、およびリモート制御用の強力なREST APIが備わっています。このMCPサーバーは、そのREST APIを活用して、AIアシスタントが直接C64とやり取りできるようにします。

互換性のある他の製品

このサーバーは、Gideon's Logicの他の製品とも互換性があります。

すべてのUltimateデバイスは、このMCPサーバーが使用する同じREST APIを公開しています。

このMCPサーバーは何をするのですか？

このMCPサーバーは、AIアシスタントとCommodore 64 Ultimate（または他のUltimateデバイス）の間のブリッジとして機能し、自然言語コマンドをAPI呼び出しに変換します。これを使用すると、以下のことができます。

• C64プログラム（PRG、SID、MODファイル）をロードして実行する
• C64のメモリを直接読み書きする
• ディスクイメージ（D64、D71、D81）をマウントして作成する
• ドライブエミュレーションを制御する
• デバイスの設定を管理する
• オーディオ/ビデオをストリーミングする（Ultimate 64のみ）

利用可能なツール

接続管理

プログラム実行

オーディオ再生

メモリ操作

ドライブとディスク管理

マシン制御

設定

ファイル操作

ストリーミング（Ultimate 64のみ）

リモートでのプログラム実行

ultimate_run_prg_binaryツールは、Ultimateデバイスに保存されていないPRGファイルを実行するように設計されています。これは、AIアシスタントが外部ソースからプログラムをアップロードして実行する必要があるホステッドデプロイメントに不可欠です。

3つの入力方法

1回の呼び出しでは、1つのパラメータのみを指定する必要があります。

例: Base64エンコードされたPRG

AIは、コンパイルされたPRGプログラムをbase64にエンコードして直接送信することができます。

{
  "name": "ultimate_run_prg_binary",
  "arguments": {
    "prg_data_base64": "AQgLCJ4ACJ4ACQoAHgoAoCAKgBQKgP8f..."
  }
}

これは、AI生成のデモに特に強力です。AIは以下のことができます。

1. 6502アセンブリコードを記述する
2. （ツールが利用可能な場合）コンパイルするか、直接マシンコードを生成する
3. 結果のPRGをbase64にエンコードする
4. 実際のC64ハードウェアで実行するために送信する

例: URLダウンロード

インターネット上のどこにでもホストされているPRGを指定します。

{
  "name": "ultimate_run_prg_binary",
  "arguments": {
    "url": "https://csdb.dk/getinternalfile.php/12345/game.prg"
  }
}

MCPサーバーはファイルをダウンロードし、Ultimateデバイスにアップロードします。

例: サーバーローカルファイル

PRGがMCPサーバーのファイルシステム上にある場合

{
  "name": "ultimate_run_prg_binary",
  "arguments": {
    "file_path": "/workspace/demos/mydemo.prg"
  }
}

注意: Ultimateデバイスのストレージ（USB、SDカード）にすでにあるファイルには、代わりにultimate_run_programを使用してください。

トランスポートモード

SSEモード（デフォルト） — ホステッド/リモートアクセス用

デフォルトのモードは、永続的なHTTP接続に**Server-Sent Events (SSE)**を使用します。これは、以下の場合に最適です。

• ホステッドデプロイメント（クラウド、VPS）
• WebベースのAIアシスタント
• マルチクライアントシナリオ

エンドポイント:

SSE接続の流れ:

1. クライアントがGET /sseに接続する
2. サーバーがsession_idとエンドポイントURLを含む初期イベントを送信する
3. クライアントがPOST /messages?session_id={id}にJSON-RPCリクエストを送信する
4. レスポンスがSSEを介してストリーミングされる

STDIOモード — ローカル使用用

ローカルのMCPクライアント（CursorやClaude Desktopなど）の場合は、STDIOモードを使用します。

python mcp_ultimate_server.py --stdio
# または明示的なホストを指定する場合
python mcp_ultimate_server.py http://192.168.1.64 --stdio

Dockerデプロイメント

イメージのビルド

cd mcp_hosted
docker build -t ultimate64-mcp .

容器1� 1 コンテナ コン コン コン コン コン ン コン ン コン ン コン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン ン コン