ai-cli-hub/README.md

Unified MCP Server for AI CLI Tools (Gemini, Qwen, OpenCode)

# AI CLI Hub - Unified MCP Server

統合AIアシスタント用のModel Context Protocol (MCP) サーバー。Qwen、Gemini、OpenCode CLIツールへの統一アクセスを提供します。

## 🌟 特徴

- **統合AI処理**: 複数のAIエンジンへの統一インターフェース
- **外部CLI実行**: 実証済み外部コマンド統合アプローチ
- **OAuth 2.0認証**: セキュアな認証システム
- **MCP準拠**: Claude Codeとの完全互換性
- **TypeScript実装**: 型安全性と保守性

## 🏗️ アーキテクチャ

### 外部コマンド統合アプローチ

既存のPython MCP実装の実証済みパターンを採用：

```
MCP Client → AI CLI Hub → External CLI Commands
   │             │              │
   │             │              ├─ qwen -p "prompt"
   │             │              ├─ gemini -p "prompt" 
   │             │              └─ opencode -p "prompt"
   │             │
   │             ├─ OAuth Manager (環境変数経由)
   │             ├─ Command Builder
   │             └─ Error Handling
```

### 対応AI エンジン

| エンジン | 機能 | 認証方式 |
|---------|------|---------|
| **Qwen** | コード生成、チャット、ファイル分析 | OAuth 2.0 + API Key |
| **Gemini** | 高度推論、文書分析、グラウンディング | OAuth 2.0 + API Key |
| **OpenCode** | マルチプロバイダー統合、フォールバック | OAuth 2.0 |

## 🚀 セットアップ

### NPXで即座に使用（推奨）

```bash
# 初期化 (設定ファイルとディレクトリ作成)
npx ai-cli-hub init

# MCPサーバー起動
npx ai-cli-hub start

# デモ環境セットアップ
npx ai-cli-hub demo
```

### 1. ローカルインストール

```bash
# グローバルインストール
npm install -g ai-cli-hub

# または開発用ローカルインストール
git clone https://github.com/your-username/ai-cli-hub.git
cd ai-cli-hub
npm install
npm run build
```

### 2. AI CLIツールの準備

各AIエンジンのCLIツールをインストール：

```bash
# Qwen CLI
pip install qwen-cli

# Gemini CLI  
pip install google-generativeai-cli

# OpenCode CLI
npm install -g opencode-cli
```

### 3. 認証設定

```bash
# OAuth認証
npm run auth:setup

# またはAPI Keyを設定
export QWEN_API_KEY="your-api-key"
export GEMINI_API_KEY="your-api-key"
```

### 4. MCP サーバー起動

```bash
# 開発モード
npm run dev

# プロダクション
npm run start
```

## 🔧 使用方法

### Claude Code での設定

`claude_desktop_config.json` に追加：

#### NPX使用の場合（推奨）
```json
{
  "mcpServers": {
    "ai-cli-hub": {
      "command": "npx",
      "args": ["ai-cli-hub", "start"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

#### ローカルインストールの場合
```json
{
  "mcpServers": {
    "ai-cli-hub": {
      "command": "ai-cli-hub",
      "args": ["start"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

#### 開発環境の場合
```json
{
  "mcpServers": {
    "ai-cli-hub": {
      "command": "node",
      "args": ["/path/to/ai-cli-hub/dist/index.js"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}
```

### 利用可能なツール

#### Qwen ツール
- `qwen_chat`: AIチャット機能
- `qwen_analyze_file`: ファイル分析
- `qwen_change_file`: ファイル変更
- `qwen_generate_code`: コード生成

#### Gemini ツール
- `gemini_chat`: 高度推論チャット
- `gemini_analyze_document`: 文書分析
- `gemini_code_review`: コードレビュー
- `gemini_grounding_search`: グラウンディング検索

#### OpenCode ツール
- `opencode_chat`: マルチプロバイダーチャット
- `opencode_generate_code`: コード生成
- `opencode_explain_code`: コード説明

## 🧪 テスト

### モック環境でのテスト

```bash
# モックAIコマンドの作成
demo/mock-ai-commands.sh

# モック環境のセットアップ
source demo/setup-mock-env.sh

# テスト実行
npm run test
```

### 外部コマンド統合テスト

```bash
# 単体テスト
node test/external-command.test.js

# 統合テスト
node test/mcp-integration.test.js
```

## ⚙️ 設定

### ai-cli-hub.config.json

```json
{
  "engines": {
    "qwen": {
      "enabled": true,
      "useOAuth": true,
      "model": "qwen3-coder-plus",
      "timeout": 30000
    },
    "gemini": {
      "enabled": true,
      "useOAuth": true,
      "model": "gemini-2.5-pro",
      "grounding": true
    },
    "opencode": {
      "enabled": true,
      "useOAuth": true,
      "provider": "anthropic"
    }
  },
  "features": {
    "fileOperations": true,
    "gitIntegration": true
  },
  "server": {
    "logLevel": "info",
    "timeout": 120000
  }
}
```

## 🔐 セキュリティ

- OAuth 2.0 フロー完全対応
- 認証トークンの安全な管理
- 環境変数経由の認証情報渡し
- タイムアウト・エラーハンドリング

## 📊 統合実績

### 調査・統合結果
- ✅ 既存Python実装の調査完了
- ✅ 外部コマンド統合パターン採用
- ✅ OAuth認証システム統合
- ✅ 完全動作確認完了

### アーキテクチャ改善
**Before**: TODO実装（未動作）  
**After**: 外部コマンド統合（完全動作）

## 🤝 コントリビューション

1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -am 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open Pull Request

## 📝 ライセンス

MIT License - 詳細は [LICENSE](LICENSE) ファイルを参照

## 🔗 関連リンク

- [Model Context Protocol](https://spec.modelcontextprotocol.io/)
- [Claude Code Documentation](https://docs.anthropic.com/claude/docs)
- [統合分析レポート](INTEGRATION_ANALYSIS.md)