Postgis Yukon MCP

🚀 PostGIS MCP 服務器

本項目基於 fastMCP 框架，實現了 PostGIS 工具的 MCP 服務器。它能通過 MCP 協議提供標準化的地理空間數據庫工具接口，還新增了 Text-to-SQL 功能，支持用自然語言查詢 PostGIS 數據庫。

🚀 快速開始

安裝依賴

pip install -r requirements.txt

配置說明

在使用前需要配置 PostGIS 數據庫連接信息：

# src/config/database.py
DB_CONFIG = {
    "host": "localhost",
    "port": 5432,
    "database": "your_database",
    "user": "your_user",
    "password": "your_password"
}

運行服務

python -m src.server

✨ 主要特性

🌟 新功能: Text-to-SQL

現在支持使用自然語言查詢 PostGIS 數據庫！無需編寫複雜的 SQL 語句，只需用中文或英文描述您的查詢需求。 示例：

• "查詢表:buildings 座標 120.5,30.2 附近 500 米的建築"
• "為表:roads 創建 100 米緩衝區"
• "計算表:parks 的面積" 詳細信息請查看 Text-to-SQL 文檔

各類工具功能

空間查詢工具（3 個）

• query_nearby - 根據座標查詢附近的地理要素
• query_bbox - 空間範圍查詢
• query_attribute - 根據屬性查詢要素

幾何操作工具（5 個）

• buffer_geometry - 創建幾何緩衝區
• get_area - 計算幾何面積
• get_length - 計算幾何長度
• transform_coords - 座標系統轉換
• simplify_geom - 簡化幾何對象

空間分析工具（5 個）

• measure_distance - 計算兩個幾何對象之間的距離
• test_intersection - 檢查幾何對象相交關係
• test_containment - 檢查幾何對象包含關係
• union_geoms - 合併多個幾何對象
• get_centroid - 計算幾何對象質心

數據庫管理工具（9 個）

• postgis_version - 獲取 PostGIS 版本信息
• list_extensions - 列出已安裝的數據庫擴展
• discover_spatial_tables - 發現包含空間字段的表
• table_info - 獲取表的詳細空間信息
• create_index - 為空間列創建 GIST 索引
• analyze - 分析表以更新統計信息
• vacuum - 清理表以回收空間
• spatial_extent - 獲取表的空間範圍
• validate_geometries - 檢查幾何對象有效性

高級空間分析工具（8 個）

• join_spatial - 執行空間連接操作
• find_nearest - 查找最近的 K 個鄰居
• cluster_spatial - 使用 DBSCAN 進行空間聚類
• compute_convex_hull - 計算凸包
• generate_voronoi - 生成 Voronoi 多邊形
• interpolate_line - 沿線段插值點
• snap_geometry - 將幾何對象捕捉到網格
• split_line - 使用點分割線段

Text-to-SQL 工具（2 個）

• nl_to_sql - 將自然語言轉換為 PostGIS SQL 語句
• execute_sql - 安全執行 SQL 查詢（需用戶確認）

共計 32 個專業 PostGIS 工具

📦 安裝指南

安裝依賴

pip install -r requirements.txt

配置數據庫

# src/config/database.py
DB_CONFIG = {
    "host": "localhost",
    "port": 5432,
    "database": "your_database",
    "user": "your_user",
    "password": "your_password"
}

💻 使用示例

基礎用法

通過 MCP 協議調用工具：

# 查詢指定座標附近的要素
result = await mcp_client.call_tool(
    "query_nearby",
    {
        "longitude": 120.123,
        "latitude": 30.456,
        "radius": 1000
    }
)

📚 詳細文檔

項目結構

yukon_mcp_service/
├── src/
│   ├── __init__.py           # 包初始化
│   ├── server.py             # MCP 服務器主入口
│   ├── tools/                # 工具模塊
│   │   ├── __init__.py
│   │   ├── spatial_query.py  # 空間查詢工具
│   │   ├── geometry.py       # 幾何操作工具
│   │   └── analysis.py       # 空間分析工具
│   └── config/
│       ├── __init__.py
│       └── database.py       # 數據庫配置
├── tests/                    # 測試文件
│   ├── __init__.py
│   └── test_tools.py
├── pyproject.toml            # 項目配置
├── requirements.txt          # 依賴列表
└── README.md                 # 項目說明

開發指南

添加新工具

1. 在 src/tools/ 目錄下創建新的工具模塊
2. 使用 @mcp.tool() 裝飾器定義工具函數
3. 在 server.py 中註冊新工具

示例：

@mcp.tool()
async def my_spatial_tool(param1: str, param2: float) -> dict:
    """工具描述"""
    # 實現邏輯
    return {"result": "data"}

🔧 技術細節

本項目使用的技術棧如下：

• Python 3.8+
• fastMCP
• PostGIS
• psycopg2
• asyncio

📄 許可證

本項目採用 MIT License。