shell/docs/architecture.md

ai.shell Architecture

全体構成

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User Input    │     │   ai-shell CLI  │     │   MCP Server    │
│   (Terminal)    │────▶│     (Rust)      │────▶│    (Python)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                │                          │
                                │                          ▼
                                │                 ┌─────────────────┐
                                │                 │   Local LLM     │
                                │                 │   (Ollama)      │
                                │                 └─────────────────┘
                                │                          │
                                ▼                          ▼
                        ┌─────────────────┐     ┌─────────────────┐
                        │  File System    │     │  Code Analysis  │
                        │   Operations    │     │   & Generation  │
                        └─────────────────┘     └─────────────────┘

MCP Serverの主要な役割

1. LLMとの通信ハブ

• ローカルLLM（Ollama）との通信を管理
• プロンプトの最適化と前処理
• レスポンスの後処理とフォーマット

2. ツール実行エンジン

MCP Serverは以下のツール（関数）を提供：

# 既存の実装から
- code_with_local_llm()      # コード生成
- read_file_with_analysis()  # ファイル読み込み＆分析
- write_code_to_file()       # コード書き込み
- debug_with_llm()           # デバッグ支援
- explain_code()             # コード説明
- execute_command()          # シェルコマンド実行
- git_operations()           # Git操作

3. コンテキスト管理

• プロジェクトのコンテキスト保持
• 会話履歴の管理
• ファイルの依存関係追跡

4. セキュリティレイヤー

• コマンドのサンドボックス実行
• ファイルアクセス権限の管理
• 危険な操作の検証

Rust CLI ↔ MCP Server 通信

通信プロトコル

// Rust側のリクエスト例
struct MCPRequest {
    method: String,        // "code_with_local_llm"
    params: Value,         // {"prompt": "...", "language": "rust"}
    context: ProjectContext,
}

// MCP Server側のレスポンス
{
    "result": {
        "code": "fn main() { ... }",
        "explanation": "This creates a simple HTTP server...",
        "files_created": ["src/server.rs"]
    },
    "error": null
}

実装の流れ

1. ユーザー入力（Rust CLI）

   ai> create a web server in rust
   

2. リクエスト構築（Rust）

   • プロンプト解析
   • コンテキスト収集（現在のディレクトリ、プロジェクトタイプなど）

3. MCP Server処理（Python）

   • ツール選択（code_with_local_llm）
   • LLMへのプロンプト送信
   • コード生成
   • ファイル操作

4. レスポンス処理（Rust）

   • 結果の表示
   • ファイル変更の確認
   • 次のアクションの提案

なぜMCP Serverが必要か

1. 言語の分離

• Python: AI/MLエコシステムが充実
• Rust: 高速で安全なCLI実装

2. 拡張性

• 新しいLLMの追加が容易
• ツールの追加・変更が独立

3. 再利用性

• 他のクライアント（VS Code拡張など）からも利用可能
• APIとして公開可能

4. プロセス分離

• LLMの重い処理とUIの軽快な動作を分離
• クラッシュ時の影響を最小化