Qgistoolmcp

🚀 QGIS MCPサービス - LLMベースの地理空間処理フレームワーク

🚀 14の専用MCPサービスを通じて333の地理空間処理ツールを備えた、LLMベースのQGISエージェントを構築するための完全なフレームワークです。

AIエージェントを使用して自然言語を自動化されたQGISワークフローに変換し、適切な地理空間ツールをインテリジェントに選択して実行します。

✨ 主な機能

• 🤖 LLMベースのエージェント - 自然言語をQGIS操作に変換し、インテリジェントなツール選択を行います。
• 🎯 333のQGISツール - モデルコンテキストプロトコル（MCP）を介した完全なQGIS処理ツールキットです。
• 🔧 14の専用サービス - ベクトル、ラスター、GDAL、カルトグラフィなどのサービスがあります。
• 🌐 HTTP SSE通信 - すべてのサービスはサーバー送信イベント（Server-Sent Events）を介してアクセス可能です。
• 📦 モジュール式アーキテクチャ - 必要なサービスのみをロードできます。
• 🛠️ シンプルなPython API - カスタムエージェント開発のための簡単な統合が可能です。
• 🔌 バックグラウンドサービス管理 - すべてのサービスの起動、停止、ステータス確認スクリプトが用意されています。

🔧 技術詳細

┌─────────────────────────────────────────────────┐
│          LLMベースのQGISエージェント                 │
│      (自然言語 → ツール選択)        │
│              (client_demo/agent.py)             │
└─────────────────┬───────────────────────────────┘
                  │ HTTP SSE
    ┌─────────────┴──────────────┐
    │   14の独立したサービス   │
    │  (services/qgis-*-mcp/)     │
    ├─────────────────────────────┤
    │ 各サービスは独自のポート（32821 - 32834）で実行されます。    │
    └─────────────┬───────────────┘
                  │
         QGIS処理エンジン
          (共有エグゼキューターを介して)

🚀 クイックスタート

1. 前提条件

• Python 3.10 - 3.11
• PythonバインディングがインストールされたQGIS 3.22以上
• 仮想環境（推奨）

2. インストール

# リポジトリをクローン
git clone <repository-url>
cd qgisToolMCP

# 仮想環境を作成してアクティブ化
python -m venv .venv
source .venv/bin/activate  # Windowsの場合は .venv\Scripts\activate

# すべてのサービスをインストール
pip install -e services/qgis-vector-geometry-buffer-mcp/
pip install -e services/qgis-vector-analysis-overlay-mcp/
# ... 必要に応じて他のサービスをインストール

# クライアントデモの依存関係をインストール
pip install openai mcp python-dotenv

3. 環境を構成

# 環境ファイルを作成
cp .env.example .env

# .envを編集し、OpenAI APIキーを設定
# OPENAI_API_KEY=your-api-key-here
# OPENAI_API_BASE_URL=https://api.openai.com/v1

4. サービスを起動

# 14のサービスをすべてバックグラウンドで起動
cd services
./run.sh

# サービスのステータスを確認
./status.sh

# 特定のサービスのログを表示
tail -f logs/qgis-vector-geometry-buffer-mcp.log

5. デモエージェントを実行

# LLMベースのエージェントデモを実行
python client_demo/agent.py http://localhost:32821/sse http://localhost:32822/sse

# またはテストスクリプトを実行
python client_demo/test_agent.py

📦 利用可能なサービス

合計: 14のサービスで333のツール

💻 使用例

例1: LLMベースのエージェントを使用する

import asyncio
from client_demo.agent import QGISAgent

async def main():
    # 複数のサービスに接続するエージェントを作成
    agent = QGISAgent(
        service_urls=[
            "http://localhost:32821/sse",  # バッファーサービス
            "http://localhost:32822/sse",  # ハルバウンドサービス
            "http://localhost:32824/sse",  # 分析オーバーレイサービス
        ],
        model="gpt-4-turbo-preview"
    )

    # サービスに接続
    await agent.connect()

    # 自然言語でタスクを記述
    task = """
    /path/to/input.shpにあるポイントフィーチャを持つシェイプファイルがあります。
    各ポイントの周りに500メートルのバッファーを作成し、
    結果を/path/to/output.shpに保存してください。
    """

    # エージェントが適切なツールをインテリジェントに選択して実行
    async for update in agent.process_task(task):
        print(update, end='', flush=True)

    await agent.disconnect()

asyncio.run(main())

例2: 直接ツールを実行する

import asyncio
from client_demo.agent import QGISAgent

async def main():
    agent = QGISAgent(
        service_urls="http://localhost:32821/sse"
    )

    await agent.connect()

    # 特定のツールを直接実行
    result = await agent.execute_tool('buffer', {
        'INPUT': '/path/to/input.shp',
        'DISTANCE': 500,
        'OUTPUT': '/path/to/output.shp'
    })

    print(f"結果: {result}")

    await agent.disconnect()

asyncio.run(main())

例3: インタラクティブモード

# エージェントをインタラクティブモードで実行
python client_demo/agent.py http://localhost:32821/sse

# 次に自然言語クエリを入力します。
# > my_layer.shpのフィーチャの周りに1kmのバッファーを作成する
# > 許容誤差0.5でジオメトリを単純化する
# > 各ポリゴンの面積を計算する

サービス管理

すべてのサービスを起動

cd services
./run.sh

これにより、14のサービスがすべてバックグラウンドでロギング付きで起動します。

サービスのステータスを確認

cd services
./status.sh

出力例:

サービス: qgis-vector-geometry-buffer-mcp    ステータス: RUNNING  PID: 12345  ポート: 32821
サービス: qgis-vector-geometry-hull-bounds-mcp  ステータス: RUNNING  PID: 12346  ポート: 32822
...

すべてのサービスを停止

cd services
./stop.sh

ログを表示

# 特定のサービスのログを表示
tail -f services/logs/qgis-vector-geometry-buffer-mcp.log

# すべてのログを表示
tail -f services/logs/*.log

# エラーを検索
grep -i error services/logs/*.log

クライアントデモAPI

client_demo/agent.pyは強力なエージェントフレームワークを提供します。

QGISAgentクラス

agent = QGISAgent(
    service_urls: List[str] | str,  # 接続するサービスURL
    openai_api_key: Optional[str] = None,  # OpenAI APIキー
    base_url: Optional[str] = None,  # APIベースURL
    model: str = "gpt-4-turbo-preview",  # 使用するLLMモデル
    max_retries: int = 3,  # 失敗した操作のリトライ回数
    verbose: bool = True  # 詳細なログを有効にする
)

主要なメソッド

• await agent.connect() - すべてのサービスに接続
• await agent.disconnect() - サービスから切断
• agent.list_tools() - 利用可能なすべてのツールのリストを取得
• agent.list_services() - 接続されたサービスのリストを取得
• agent.list_tools_by_service() - サービスごとにグループ化されたツールを取得
• await agent.execute_tool(name, params) - 特定のツールを実行
• async for update in agent.process_task(description) - 自然言語タスクを処理

プロジェクト構造

qgisToolMCP/
├── client_demo/              # LLMベースのエージェントデモ
│   ├── agent.py             # メインのQGISAgentクラス
│   ├── test_agent.py        # テストスクリプト
│   ├── test_direct_call.py  # 直接呼び出しの例
│   └── data/                # テストデータ
├── services/                 # 14の独立したMCPサービス
│   ├── run.sh               # すべてのサービスを起動
│   ├── stop.sh              # すべてのサービスを停止
│   ├── status.sh            # サービスのステータスを確認
│   ├── logs/                # サービスログ（実行時に作成）
│   ├── pids/                # サービスPIDファイル（実行時に作成）
│   └── qgis-*-mcp/          # 個々のサービス
│       ├── src/             # サービスのソースコード
│       ├── docs/            # サービスのドキュメント
│       ├── pyproject.toml   # サービスの設定
│       └── README.md        # サービス固有のドキュメント
├── shared/                   # サービス間で共有されるコード
│   ├── executor.py          # QGISアルゴリズムエグゼキューター
│   └── qgis_runner.py       # QGIS Python実行スクリプト
├── documentation/            # プロジェクトのドキュメント
│   ├── DEVELOPMENT.md       # 開発ガイド
│   ├── PROJECT_TRANSFORMATION.md  # アーキテクチャの概要
│   └── README.md            # ドキュメントのインデックス
├── scripts/                  # ユーティリティスクリプト
├── manage.py                 # サービス管理CLI
├── Makefile                  # ビルド自動化
└── README.md                 # このファイル

開発

サービスに新しいツールを追加する

1. サービスディレクトリに移動します。

cd services/qgis-vector-geometry-buffer-mcp/src/qgis_vector_geometry_buffer_mcp/tools/

2. ツール関数を追加します。

@mcp.tool()
def my_new_tool(
    input_layer: str,
    parameter: float,
    output: str
) -> dict:
    """ツールの説明"""
    params = {
        'INPUT': input_layer,
        'PARAMETER': parameter,
        'OUTPUT': output
    }
    result = executor.run_algorithm('native:algorithm_id', params)
    return {
        "output": result.get('OUTPUT'),
        "status": "success"
    }

3. tools/__init__.pyでツールを登録します。
4. サービスを再起動します。

cd services
./stop.sh
./run.sh

詳細な開発ガイドについては、DEVELOPMENT.mdを参照してください。

設定

環境変数

プロジェクトのルートに.envファイルを作成します。

# OpenAI API設定
OPENAI_API_KEY=your-api-key-here
OPENAI_API_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4-turbo-preview

# QGIS設定（サービス用）
QGIS_PYTHON_PATH=/usr/bin/python3
QGIS_PREFIX_PATH=/usr

サービス設定

各サービスは、サービス固有の設定のためにそのディレクトリに独自の.envファイルを持つことができます。

要件

サービスの実行に必要なもの

• Python 3.10 - 3.11
• PythonバインディングがインストールされたQGIS 3.22以上
• 必要なPythonパッケージ（自動的にインストールされます）:
  • fastmcp
  • python-dotenv

エージェントの使用に必要なもの

• Python 3.10以上
• OpenAI APIキー（または互換性のあるAPI）
• 必要なPythonパッケージ:
  • openai
  • mcp
  • python-dotenv

トラブルシューティング

サービスが起動しない場合

1. QGISが正しくインストールされていることを確認します。

python3 -c "from qgis.core import QgsApplication; print('QGIS OK')"

2. サービスのログを確認します。

tail -f services/logs/<service-name>.log

3. 仮想環境を確認します。

which python
# .venv/bin/pythonを指す必要があります。

ポートの競合が発生した場合

"port already in use"エラーが発生した場合は、以下の操作ができます。

1. ポートを使用しているものを確認します。

lsof -i :32821

2. プロセスを終了するか、services/run.shでポートを変更します。

エージェントがサービスに接続できない場合

1. サービスが実行中であることを確認します。

cd services
./status.sh

2. ポートがアクセス可能であることを確認します。

curl http://localhost:32821/sse

3. エージェントコード内のサービスURLが実行中のサービスと一致していることを確認します。

📚 ドキュメント

• 開発ガイド - 新しいサービスとツールを開発する方法
• プロジェクトの変換 - アーキテクチャと設計決定
• サービス管理 - 詳細なサービス管理ドキュメント
• クライアントデモ - エージェントの使用方法と例
• 共有コード - 共有ユーティリティのドキュメント

コントリビューション

コントリビューションは大歓迎です！以下のように支援することができます。

1. 新しいツールを追加する - 追加のQGISアルゴリズムを実装する
2. ドキュメントを改善する - ガイドと例を強化する
3. バグを修正する - 問題を報告して修正する
4. パフォーマンスを最適化する - 実行速度を向上させる
5. テストを追加する - テストカバレッジを増やす

コントリビューションガイドラインについては、DEVELOPMENT.mdを参照してください。

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

謝辞

• FastMCPフレームワークをベースに構築されています。
• QGISの処理アルゴリズムを使用しています。
• Model Context Protocol (MCP)によって動作しています。

サポート

• 📖 ドキュメント
• 🐛 問題追跡
• 💬 ディスカッション

地理空間AIコミュニティのために❤️ で構築されました