# DeepSeek-OCR Agent for Claude Code

Claude Code向けのDeepSeek-OCR統合実装。Modal Labs経由でGPU上でDeepSeek-OCRを実行し、高精度なOCR処理を提供します。

## 特徴

- **高精度OCR**: DeepSeek-OCRによる97-98%の精度
- **多言語対応**: 日本語、英語、中国語など100以上の言語
- **コスト最適化**: Modal Labsの無料枠（月$30）で個人利用をカバー
- **Claude Code統合**: MCPサーバー経由でシームレスに利用可能
- **Sub-Agent対応**: `ocr-specialist` エージェントで専門的なOCR処理

## アーキテクチャ

```
Claude Code (Mac)
  └─ MCP Server (Node.js/TypeScript)
      └─ Modal Labs API
          └─ Modal Functions (Python)
              └─ DeepSeek-OCR (GPU: T4, 8GB VRAM)
```

## 必要要件

### ソフトウェア

- **Python 3.12+**: Modal CLI実行用
- **Node.js 18+**: MCPサーバー実行用
- **Modal Labs アカウント**: [modal.com](https://modal.com)で無料登録

### システム要件

- macOS（Apple Silicon / Intel対応）
- インターネット接続（Modal Labs API利用）

## セットアップ

### 1. クイックスタート

```bash
# セットアップスクリプトを実行
./scripts/setup.sh
```

このスクリプトが以下を自動実行します:
- Python/Node.js環境の確認
- Modal CLIのインストール
- Modal認証
- Modal appのデプロイ
- MCPサーバーのビルド
- Claude Desktop設定のガイド

### 2. 手動セットアップ

#### Step 1: Modal CLIインストール

```bash
pip3 install modal
```

#### Step 2: Modal認証

```bash
modal token new
```

ブラウザが開くので、Modal Labsにサインイン/サインアップしてトークンを生成します。

#### Step 3: Modal Appデプロイ

```bash
cd modal_app
modal deploy main.py
```

#### Step 4: MCPサーバービルド

```bash
cd mcp-server
npm install
npm run build
```

#### Step 5: Claude Desktop設定

`~/Library/Application Support/Claude/claude_desktop_config.json` に以下を追加:

```json
{
  "mcpServers": {
    "deepseek-ocr": {
      "command": "node",
      "args": [
        "/Users/username/deepseek-ocr-agent/mcp-server/dist/index.js"
      ]
    }
  }
}
```

**重要**: パスを実際のプロジェクトパスに置き換えてください。

#### Step 6: Claude Desktopを再起動

設定を反映させるためClaude Desktopを再起動します。

## 使用方法

### Claude Codeでの基本的な使い方

1. **画像をMarkdownに変換**
   ```
   この画像をMarkdownに変換して: /path/to/document.png
   ```

2. **プレーンテキスト抽出**
   ```
   この領収書からテキストを抽出: receipt.jpg
   ```

3. **カスタムプロンプト**
   ```
   この画像から表データだけを抽出してCSV形式で: table.png
   ```

### Sub-Agentの使用

OCR専門タスクには `ocr-specialist` sub-agentを使用できます:

```
@ocr-specialist この文書をデジタル化して
```

詳細な使用方法は [USAGE.md](docs/USAGE.md) を参照してください。

## コスト

### Modal Labs料金

- **無料枠**: 月$30のクレジット
- **GPU (T4)**: $0.000164/秒

### 月間コスト試算

個人利用（1日100枚、月3,000枚）の場合:

```
処理時間: 3,000枚 × 3秒 = 9,000秒
コスト: $0.000164 × 9,000 = $1.48/月
無料枠: $30/月

→ 実質$0（無料枠内）
```

月10,000枚まで無料枠で処理可能です。

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

### Modal認証エラー

```bash
modal token new
```

トークンを再生成してください。

### MCPサーバーが認識されない

1. Claude Desktopを再起動
2. 設定ファイルのパスを確認
3. MCPサーバーがビルドされているか確認: `ls mcp-server/dist/index.js`

### OCR処理が失敗する

- 画像ファイルが存在するか確認
- 画像形式がサポートされているか確認（PNG, JPG, JPEG推奨）
- Modal appがデプロイされているか確認: `modal app list`

### 処理が遅い

- 初回実行時はコールドスタート（5-10秒）が発生します
- 2回目以降は2-3秒程度に短縮されます

## テスト

### 動作テスト

```bash
# テスト用画像を用意
./scripts/test-ocr.sh /path/to/test/image.png
```

### MCPサーバーテスト

```bash
cd mcp-server
npm run dev
```

## プロジェクト構造

```
deepseek-ocr-agent/
├── modal_app/              # Modal Functions（Python）
│   ├── main.py             # DeepSeek-OCR処理のメイン実装
│   └── requirements.txt    # Python依存関係
│
├── mcp-server/             # MCPサーバー（TypeScript）
│   ├── src/
│   │   ├── index.ts        # MCPサーバー本体
│   │   └── tools/
│   │       └── modal-ocr.ts # Modal API統合
│   ├── package.json
│   └── tsconfig.json
│
├── .claude/
│   └── agents/
│       └── ocr-specialist.md # OCR専門sub-agent
│
├── scripts/
│   ├── setup.sh            # セットアップスクリプト
│   └── test-ocr.sh         # テストスクリプト
│
├── config/
│   ├── claude_desktop_config.json  # Claude Desktop設定例
│   └── .env.example        # 環境変数サンプル
│
├── docs/                   # ドキュメント
│   ├── USAGE.md            # 使用方法ガイド
│   ├── DEPLOYMENT.md       # デプロイメントガイド
│   └── SUMMARY.md          # 実装サマリー
│
└── README.md
```

## 技術スタック

### バックエンド（Modal Functions）
- Python 3.12
- PyTorch 2.6.0
- Transformers 4.46.3
- DeepSeek-OCR（deepseek-ai/DeepSeek-OCR）
- Flash Attention 2.7.3

### MCPサーバー
- Node.js 18+
- TypeScript 5.7
- @modelcontextprotocol/sdk
- Axios

### インフラ
- Modal Labs（Serverless GPU）
- NVIDIA T4 GPU（8GB VRAM）

## ドキュメント

詳細なドキュメントは `docs/` ディレクトリにあります:

- **[USAGE.md](docs/USAGE.md)**: 使用方法と実用例
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)**: デプロイメントとモニタリング
- **[SUMMARY.md](docs/SUMMARY.md)**: 実装サマリー

## よくある質問

### Apple Silicon Macで動作しますか？
はい。ローカルではGPUを使用せず、Modal Labs経由でクラウドGPU（NVIDIA T4）を利用するため、Apple Silicon / Intelどちらでも動作します。

### オフラインで使用できますか？
いいえ。Modal Labs APIを使用するためインターネット接続が必要です。

### 商用利用は可能ですか？
DeepSeek-OCRはMITライセンスです。Modal Labsの利用規約も確認してください。

その他の質問は [USAGE.md](docs/USAGE.md) のFAQセクションを参照してください。

## ライセンス

MIT License

## 参考リンク

- [DeepSeek-OCR GitHub](https://github.com/deepseek-ai/DeepSeek-OCR)
- [Modal Labs](https://modal.com/)
- [Claude Code Documentation](https://docs.claude.com/claude-code)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## 貢献

Issue、Pull Requestを歓迎します。

## サポート

問題が発生した場合:
1. このREADMEのトラブルシューティングセクションを確認
2. GitHubでIssueを作成
3. Modal Labs [ドキュメント](https://modal.com/docs)を参照