# Gemini URL Context & Search MCP Server

Google AI Studio の URL context 機能と Google Search を MCP (Model Context Protocol) サーバーとして実装し、Claude Code から**Webページのテキスト抽出と検索**を可能にします。

## 📁 プロジェクト構造
詳細なフォルダ・ファイル構成は [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) をご覧ください。

## 🎯 機能

- **📄 URL Content Extract**: Webページのテキストと画像URLを全抽出
- **🔍 Google Search**: Webを検索して関連情報を取得
- **🏗️ 構造化出力**: JSON形式でページ情報を整理
- **🔗 複数URL対応**: 複数URLの一括処理
- **⚡ 高品質アーキテクチャ**: ドメイン駆動設計とTDD

## 📦 インストール

### npxで即座に使用（推奨）
```bash
# Claude Code で一発セットアップ
claude mcp add gemini-url-context -s user -e GEMINI_API_KEY="your-key" -- npx @yourcompany/gemini-url-context-mcp@latest
```

### 手動インストール
```bash
npm install -g @yourcompany/gemini-url-context-mcp
```

## 🔧 セットアップ

### 1. APIキー取得
1. [Google AI Studio](https://aistudio.google.com/) にアクセス
2. "Get API key" → "Create API key"
3. キーをコピー

### 2. 自動セットアップ（Claude Code）
```bash
# セットアップスクリプトを実行
export GEMINI_API_KEY="your-api-key"
./scripts/setup-claude-code.sh
```

### 3. 設定ファイル生成（他のクライアント）
```bash
# 各クライアント用設定ファイルを生成
node scripts/generate-configs.js
```

## 🚀 使用方法

### URL Content Extract
```
Claude Code で話しかけるだけ：
「https://example.com のテキストと画像を全部抽出して」
```

### Google Search
```
Claude Code で話しかけるだけ：
「最新のAI技術について検索して」
```

### 応用例
```
「以下のサイトを比較分析して：
- https://site1.com
- https://site2.com」

「Next.js 14の最新情報を検索して、
関連記事の内容も抽出して」
```

## 🛠️ 対応クライアント

- **Claude Code** (CLI) - ワンライナーセットアップ
- **Cursor** - `.cursor/mcp.json`
- **VS Code** - MCP拡張
- **Claude Desktop** - 標準設定
- **LM Studio** - MCP Server追加

## 🏗️ アーキテクチャ

### ドメイン駆動設計
- **Domain Layer**: Url, Page, ModelName 値オブジェクト
- **Use Case Layer**: ビジネスロジック分離
- **Adapter Layer**: 外部API統合
- **Infrastructure**: MCP プロトコル実装

### 品質保証
- **TDD**: テスト駆動開発
- **型安全**: TypeScript厳密モード
- **エラーハンドリング**: 分類された例外処理
- **Value Objects**: 不変性保証

## 🔍 API仕様

### url_context_extract
```json
{
  "urls": ["https://example.com"],
  "query": "要約して",
  "model": "gemini-2.0-flash-exp",
  "maxCharsPerPage": 8000
}
```

### google_search
```json
{
  "query": "検索キーワード",
  "instruction": "処理指示",
  "model": "gemini-2.0-flash-exp"
}
```

## 🎯 MCP作成のベストプラクティス

この実装から学べる要素：

### 🔥 必須要素
1. **npx対応**: `"bin"` でCLIツール化
2. **複数クライアント対応**: 設定ファイル自動生成
3. **ワンライナー セットアップ**: ユーザビリティ最優先
4. **エラーハンドリング**: 型付きエラーで安全性

### 🏗️ アーキテクチャ
1. **ドメイン駆動設計**: ビジネスロジック分離
2. **Value Object**: 型安全と不変性
3. **Adapter Pattern**: 外部依存の抽象化
4. **Factory Pattern**: 実装切り替え

### 🧪 品質管理
1. **TDD**: テスト先行開発
2. **統合テスト**: 実動作確認
3. **型安全**: TypeScript活用
4. **lint/format**: コード品質

### 📦 配布戦略
1. **npmパッケージ**: 即座にインストール可能
2. **設定自動化**: スクリプトで一発セットアップ
3. **ドキュメント**: 使用例とトラブルシューティング
4. **段階的ロールアウト**: パイロット→本格展開

## 🏆 他実装との差別化

| 項目 | この実装 | 一般的実装 |
|------|----------|-----------|
| **アーキテクチャ** | DDD + Clean Architecture | 手続き型 |
| **テスト** | TDD + 統合テスト | テストなし |
| **型安全** | Value Object | 文字列ベース |
| **エラー処理** | 型付きドメインエラー | try-catch |
| **ユーザビリティ** | ワンライナーセットアップ | 手動設定 |

---

**開発者**: あなた  
**アーキテクチャ**: Claude Code AI  
**品質**: エンタープライズ級  
**使いやすさ**: コンシューマー級  

🎉 **完璧なMCPサーバーの完成です！**