Metadata-Version: 2.4
Name: ndlocr-lite-mcp
Version: 0.2.0
Summary: MCP server wrapping the NDLOCR-lite CLI
Project-URL: Homepage, https://github.com/HizZaniya/ndlocr-lite-mcp
Project-URL: Repository, https://github.com/HizZaniya/ndlocr-lite-mcp
Project-URL: Bug Tracker, https://github.com/HizZaniya/ndlocr-lite-mcp/issues
Author: HizZaniya
License: MIT License
        
        Copyright (c) 2026 HizZaniya
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: document,japanese,mcp,ndlocr,ocr
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Text Processing
Requires-Python: >=3.13
Requires-Dist: cairosvg>=2.7
Requires-Dist: fastmcp>=3.3.1
Requires-Dist: pillow-heif>=0.21
Requires-Dist: pillow>=11.0
Requires-Dist: pymupdf>=1.25
Description-Content-Type: text/markdown

# NDLOCR-lite MCP

> [NDLOCR-lite](https://github.com/ndl-lab/ndlocr-lite) のCLIの薄いラッパーとして機能するMCPサーバ

[![Ko-fi](https://img.shields.io/badge/Ko--fi-hizzaniya-ff5e5b?logo=ko-fi)](https://ko-fi.com/hizzaniya)

---

## 必要なもの

- **uv** — パッケージマネージャ。[公式インストール手順](https://docs.astral.sh/uv/getting-started/installation/)に従ってインストールしてください。

---

## MCPクライアント別の設定マニュアル

### Claude Desktop

1. 設定ファイルをテキストエディタで開きます。
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
2. `mcpServers` に以下を追加します。

   ```json
   {
     "mcpServers": {
       "ndlocr-lite": {
         "command": "uvx",
         "args": ["ndlocr-lite-mcp"]
       }
     }
   }
   ```

3. Claude Desktop を再起動します。

---

### Cursor

1. プロジェクトルートに `.cursor/mcp.json` を作成します（グローバル設定の場合は `~/.cursor/mcp.json`）。
2. 以下の内容を記述します。

   ```json
   {
     "mcpServers": {
       "ndlocr-lite": {
         "command": "uvx",
         "args": ["ndlocr-lite-mcp"]
       }
     }
   }
   ```

3. Cursor を再起動します。

---

### VS Code（GitHub Copilot）

1. プロジェクトルートに `.vscode/mcp.json` を作成します。
2. 以下の内容を記述します。

   ```json
   {
     "servers": {
       "ndlocr-lite": {
         "command": "uvx",
         "args": ["ndlocr-lite-mcp"]
       }
     }
   }
   ```

3. VS Code を再起動し、Copilot Chat から MCP ツールが利用可能になっていることを確認します。

---

## ツールリファレンス

### `ocr_file`

1つのファイルに対してOCRを実行します。

#### パラメータ

| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| `source` | string | 必須 | ファイルの絶対パスまたは相対パス |
| `viz` | boolean | false | 認識領域の可視化画像を生成するか |
| `enable_tcy` | boolean | false | 縦中横の読み取り改善を有効にするか |
| `output_dir` | string | null | 出力先ディレクトリ（省略時は一時ディレクトリ。`viz` を保持したい場合は指定） |

#### レスポンス

```json
{
  "source": "/path/to/image.webp",
  "pages": [
    {
      "page": 1,
      "text": "認識されたテキスト全文",
      "regions": [
        {
          "order": 0,
          "type": "本文",
          "text": "行のテキスト",
          "bbox": [100, 200, 400, 30],
          "conf": 0.942
        }
      ],
      "viz_path": "/path/to/output/viz_image.jpg"
    }
  ]
}
```

- `viz_path` は `viz=true` かつ `output_dir` を指定した場合のみ含まれます。
- PDF は1ページにつき1エントリが `pages` に追加されます（複数ページ PDF は `pages` の要素数がページ数と一致します）。

---

### `ocr_directory`

ディレクトリ内のすべての対応ファイルに対してOCRを実行します。

#### パラメータ

`source` にディレクトリパスを指定する点以外は `ocr_file` と同じです。

| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| `source` | string | 必須 | ディレクトリの絶対パスまたは相対パス |
| `viz` | boolean | false | 認識領域の可視化画像を生成するか |
| `enable_tcy` | boolean | false | 縦中横の読み取り改善を有効にするか |
| `output_dir` | string | null | 出力先ディレクトリ（省略時は一時ディレクトリ。`viz` を保持したい場合は指定） |

#### レスポンス

```json
{
  "source": "/path/to/dir",
  "files": [
    {
      "file": "image01.jpg",
      "pages": [{ "page": 1, "text": "...", "regions": [] }]
    },
    {
      "file": "broken.heic",
      "error": "conversion failed: ..."
    }
  ]
}
```

- 変換またはOCRに失敗したファイルは `pages` の代わりに `error` フィールドを持ちます。

---

## 対応フォーマット一覧

| フォーマット | 拡張子 | 備考 |
|---|---|---|
| JPEG | `.jpg` `.jpeg` | ネイティブ対応 |
| PNG | `.png` | ネイティブ対応 |
| TIFF | `.tiff` `.tif` | ネイティブ対応 |
| JPEG 2000 | `.jp2` | ネイティブ対応 |
| BMP | `.bmp` | ネイティブ対応 |
| WebP | `.webp` | 自動変換（Pillow） |
| GIF | `.gif` | 自動変換（Pillow、最初のフレームのみ） |
| AVIF | `.avif` | 自動変換（Pillow） |
| HEIC/HEIF | `.heic` `.heif` | 自動変換（pillow-heif） |
| SVG | `.svg` | 自動変換（cairosvg、要libcairo2） |
| PDF | `.pdf` | 自動変換（pymupdf、全ページ処理） |

---

## NDLOCR-lite 帰属表示

本プロジェクトは国立国会図書館が [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) ライセンスで公開している [NDLOCR-lite](https://github.com/ndl-lab/ndlocr-lite) を利用しています。

---

## ライセンス

MIT License
