Qgistoolmcp

🚀 QGIS MCP服务 - 由大语言模型驱动的地理空间处理框架

这是一个完整的框架，用于构建由大语言模型（LLM）驱动的QGIS代理，涵盖14种专业MCP服务，拥有333种地理空间处理工具。

通过人工智能代理将自然语言转化为自动化的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. 运行演示代理

# 运行由大语言模型驱动的代理演示
python client_demo/agent.py http://localhost:32821/sse http://localhost:32822/sse

# 或者运行测试脚本
python client_demo/test_agent.py

✨ 主要特性

• 🤖 由大语言模型驱动的代理 - 将自然语言转换为QGIS操作，并智能选择工具
• 🎯 333个QGIS工具 - 通过模型上下文协议（MCP）提供完整的QGIS处理工具包
• 🔧 14种专业服务 - 涵盖矢量、栅格、GDAL、制图等多个领域
• 🌐 HTTP SSE通信 - 所有服务均可通过服务器发送事件（Server-Sent Events）访问
• 📦 模块化架构 - 仅加载你需要的服务
• 🛠️ 简单的Python API - 便于自定义代理开发的集成
• 🔌 后台服务管理 - 提供启动、停止和查看所有服务状态的脚本

🔧 技术细节

架构

┌─────────────────────────────────────────────────┐
│          LLM-Powered QGIS Agent                 │
│      (Natural Language → Tool Selection)        │
│              (client_demo/agent.py)             │
└─────────────────┬───────────────────────────────┘
                  │ HTTP SSE
    ┌─────────────┴──────────────┐
    │   14 Independent Services   │
    │  (services/qgis-*-mcp/)     │
    ├─────────────────────────────┤
    │ Each service runs on its    │
    │ own port (32821-32834)      │
    └─────────────┬───────────────┘
                  │
         QGIS Processing Engine
          (via shared executor)

📦 安装指南

安装步骤

# 克隆仓库
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

💻 使用示例

基础用法

示例1：使用由大语言模型驱动的代理

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 = """
    I have a shapefile at /path/to/input.shp with point features.
    Please create a 500 meter buffer around each point and save
    the result to /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: {result}")

    await agent.disconnect()

asyncio.run(main())

示例3：交互模式

# 以交互模式运行代理
python client_demo/agent.py http://localhost:32821/sse

# 然后输入自然语言查询：
# > Create a 1km buffer around the features in my_layer.shp
# > Simplify the geometries with tolerance 0.5
# > Calculate the area of each polygon

📚 详细文档

可用服务

总计：14个服务，共333个工具

客户端演示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",  # 使用的大语言模型
    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/              # 由大语言模型驱动的代理演示
│   ├── 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                 # 服务管理命令行界面
├── 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

端口冲突

如果遇到“端口已被使用”的错误，你可以：

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 处理算法
• 由 模型上下文协议（MCP） 提供支持

支持

• 📖 文档
• 🐛 问题跟踪
• 💬 讨论

为地理空间人工智能社区用心打造 ❤️