mcp-test

MCP開発フレームワーク

カスタムツールを作成し、LLMとやり取りするための強力なMCP（Model Context Protocol）開発フレームワークです。このフレームワークは包括的なツールセットを提供し、Cursor IDEの機能を簡単に拡張できます。ウェブページのコンテンツ取得や、ファイル処理（PDF、Word、Excel）などの高度な機能を実現します。

主な機能

本フレームワークでは、以下の主要な機能を利用できます。

1. 包括的なファイル処理

fileツールを使用すると、ファイルの種類を自動的に識別し、PDF、Word、Excelファイルに適した処理方法を選択できます。

• 使い方: file /path/to/document
• 対応形式:
  • PDFファイル（.pdf）
  • Word文書（.doc、.docx）
  • Excelファイル（.xls、.xlsx、.xlsm）
• パラメーター: file_path - ファイルのローカルパス
• 戻り値: ファイルの種類に応じた処理結果を返します

2. PDF文書処理

pdfツールを使用すると、PDF文書を処理できます。次の2つの処理モードに対応しています。

• 使い方: pdf /path/to/document.pdf [mode]
• パラメーター:
  • file_path - PDFファイルのローカルパス
  • mode - 処理モード（任意）：
    • quick - クイックプレビューモード。テキストコンテンツのみを抽出します
    • full - 完全解析モード。テキストと画像のコンテンツを抽出します（デフォルト）
• 戻り値:
  • クイックプレビューモード：文書のテキストコンテンツ
  • 完全解析モード：文書のテキストコンテンツと画像
• 特徴:
  • PyMuPDFを使用して高品質なテキスト抽出と画像処理を実現します
  • 大容量ファイルを自動的に処理します
  • 画像の抽出と保存に対応しています

3. Word文書の解析

wordツールを使用すると、Word文書を解析して、テキスト、表、画像の情報を抽出できます。

• 使い方: word /path/to/document.docx
• 機能: Word文書を解析し、テキストコンテンツ、表、画像の情報を抽出します
• パラメーター: file_path - Word文書のローカルパス
• 戻り値: 文書のテキストコンテンツ、表、画像の情報
• 特徴: python-docxライブラリを使用して、高品質なテキストと表の抽出を実現します

4. Excelファイル処理

excelツールを使用すると、Excelファイルを解析して、表データと構造の情報をすべて取得できます。

• 使い方: excel /path/to/spreadsheet.xlsx
• 機能: Excelファイルのすべてのワークシートを解析します
• パラメーター: file_path - Excelファイルのローカルパス
• 戻り値:
  • ファイルの基本情報（ファイル名、ワークシート数）
  • 各ワークシートの詳細情報：
    • 行数と列数
    • 列名のリスト
    • 表データ全体
• 特徴:
  • pandasとopenpyxlを使用して、高品質な表データ処理を実現します
  • 複数ワークシートの処理に対応しています
  • データ型の変換を自動的に処理します

5. ウェブページのコンテンツ取得

urlツールを使用すると、任意のウェブページのコンテンツを取得できます。

• 使い方: url https://example.com
• パラメーター: url - コンテンツを取得するウェブサイトのURL
• 戻り値: ウェブページのテキストコンテンツ
• 特徴:
  • HTTPエラーを包括的に処理します
  • タイムアウトを管理します
  • エンコーディングを自動的に処理します

技術的な特徴

本フレームワークでは、ファイル処理のパフォーマンスを最適化するために、複数の技術を採用しています。

1. ファイルの種類をインテリジェントに識別

   • ファイル拡張子に応じて、適切な処理ツールを自動的に選択します
   • 統一されたファイル処理インターフェースを提供します

2. 効率的な文書処理

   • PDF処理：クイックプレビューと完全解析の2つのモードに対応しています
   • Word処理：テキスト、表、画像を正確に抽出します
   • Excel処理：大規模な表データを効率的に処理します

3. メモリの最適化

   • 一時ファイルを使用して大容量ファイルを管理します
   • 一時リソースを自動的にクリーンアップします
   • 大規模な文書を分割して処理します

4. エラー処理

   • 例外を包括的に捕捉して処理します
   • 詳細なエラー情報を返します
   • 適切な障害処理メカニズムを備えています

文書処理の技術詳細

PDF処理

1. 多段階処理戦略:

   • まずPyMuPDF（fitz）を使用してコンテンツの抽出を試みます（高速で高精度）
   • 失敗した場合は、PymuPDF4llm（LLM向けに最適化）に切り替えます
   • 最後に、最終的な代替手段としてPyPDF2を試します

2. パフォーマンスの最適化:

   • 処理する最大ページ数を制限します（完全モード：30ページ、クイックモード：50ページ）
   • 画像処理を最適化します（DPI調整、サイズ制限）
   • マルチスレッド処理で高速化します

3. エラー処理:

   • 詳細なエラー情報とヒントを提供します
   • サービスの安定性を確保するため、代替の処理方法を用意しています
   • タイムアウト保護機能を備えています（タイムアウトは5分に設定）

Word文書処理

1. 文書構造の解析:

   • 文書のプロパティ（タイトル、作成者、作成日時など）を抽出します
   • 元の書式を保持したまま段落の内容を抽出します
   • 表をMarkdown形式に変換します

2. 画像情報:

   • 文書内の画像数を表示します
   • 画像の参照関係を識別します

プロジェクト構成

本フレームワークは拡張と保守が容易なモジュール設計を採用しています。

mcp_tool/
├── tools/
│   ├── __init__.py        # 定义工具基类和注册器
│   ├── loader.py          # 工具加载器，自动加载所有工具
│   ├── file_tool.py       # 综合文件处理工具
│   ├── pdf_tool.py        # PDF解析工具
│   ├── word_tool.py       # Word文档解析工具
│   ├── excel_tool.py      # Excel文件处理工具
│   └── url_tool.py        # URL工具实现
├── __init__.py
├── __main__.py
└── server.py              # MCP服务器实现

開発ガイド

新しいツールの開発方法

1. toolsディレクトリにyour_tool.pyなどの新しいPythonファイルを作成します
2. 必要な依存関係と基底クラスをインポートします
3. BaseToolを継承したツールクラスを作成します
4. @ToolRegistry.registerデコレーターを使用してツールを登録します
5. ツールのexecuteメソッドを実装します

ツールテンプレートの例

import mcp.types as types
from . import BaseTool, ToolRegistry

@ToolRegistry.register
class YourTool(BaseTool):
    """您的工具描述"""
    name = "your_tool_name"  # 工具的唯一标识符
    description = "您的工具描述"  # 工具的描述信息，将显示给用户
    input_schema = {
        "type": "object",
        "required": ["param1"],  # 必需的参数
        "properties": {
            "param1": {
                "type": "string",
                "description": "参数1的描述",
            },
            "param2": {
                "type": "integer",
                "description": "参数2的描述（可选）",
            }
        },
    }
  
    async def execute(self, arguments: dict) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
        """执行工具逻辑"""
        # 参数验证
        if "param1" not in arguments:
            return [types.TextContent(
                type="text",
                text="Error: Missing required argument 'param1'"
            )]
          
        # 获取参数
        param1 = arguments["param1"]
        param2 = arguments.get("param2", 0)  # 获取可选参数，提供默认值
      
        # 执行工具逻辑
        result = f"处理参数: {param1}, {param2}"
      
        # 返回结果
        return [types.TextContent(
            type="text",
            text=result
        )]

デプロイガイド

Dockerによるデプロイ（推奨）

1. 初期設定：

# 克隆仓库
git clone https://github.com/your-username/mcp-framework.git
cd mcp-framework

# 创建环境文件
cp .env.example .env

2. Docker Composeを使用：

# 构建并启动
docker compose up --build -d

# 查看日志
docker compose logs -f

# 管理容器
docker compose ps
docker compose pause
docker compose unpause
docker compose down

3. サービスにアクセス：

• SSEエンドポイント: http://localhost:8000/sse

4. Cursor IDEの設定：

• 設定 → 機能 → MCP サーバーを追加
• 種類: "sse"
• URL: http://localhost:8000/sse

従来のPythonによるデプロイ

1. システム依存関係をインストール：

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y poppler-utils tesseract-ocr tesseract-ocr-chi-sim

# macOS
brew install poppler tesseract tesseract-lang

# Windows
# 1. 下载并安装Tesseract: https://github.com/UB-Mannheim/tesseract/wiki
# 2. 将Tesseract添加到系统PATH

2. Python依存関係をインストール：

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

3. サービスを起動：

python -m mcp_tool

設定

環境変数

.envファイルで設定します。

• MCP_SERVER_PORT: サーバーのポート（デフォルト: 8000）
• MCP_SERVER_HOST: バインドアドレス（デフォルト: 0.0.0.0）
• DEBUG: デバッグモード（デフォルト: false）
• MCP_USER_AGENT: カスタムUser-Agent

依存関係

主な依存関係：

• mcp: Model Context Protocolの実装
• PyMuPDF: PDF文書処理
• python-docx: Word文書処理
• pandasとopenpyxl: Excelファイル処理
• httpx: 非同期HTTPクライアント
• anyio: 非同期I/Oのサポート
• click: コマンドラインインターフェース

貢献ガイド

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

ライセンス

本プロジェクトはMITライセンスを採用しています。詳細はLICENSEファイルをご覧ください。