候鸟观测记录查询工具 (MCP 服务)

项目简介

本项目是一个基于FastAPI和PostGIS构建的地理空间查询API服务。它旨在作为一个功能强大的后端工具，被部署在魔搭（ModelScope）平台上，并最终由GEOGPT等智能体搭建平台进行调用。

当用户通过自然语言询问特定地点附近的候鸟信息时，智能体可以调用本工具，工具会连接到云端数据库进行实时地理空间查询，并将结构化的数据返回给智能体，由智能体组织成自然语言回答用户。

当前时间: 2025年7月28日
项目地点: 江西，南昌 (项目数据和示例主要围绕鄱阳湖候鸟保护区)

核心功能

• 动态地理空间查询: 基于用户提供的经纬度、半径和时间范围，在数据库中进行高效的圆形区域查询。
• 云端部署: 服务被设计为在魔搭（ModelScope）平台上通过代码仓库进行托管和部署。
• 云数据库集成: 使用部署在阿里云ECS上的PostgreSQL + PostGIS数据库，保证服务的稳定和数据的持久化。
• 智能体就绪 (Agent-Ready): API的接口和描述为大语言模型（LLM）调用进行了优化，方便智能体理解和使用。

技术架构

本项目采用了一个现代化的、解耦的云原生架构：

mermaid
graph LR
subgraph GEOGPT 智能体平台
A[用户提问] --> B[智能体(LLM)];
end

subgraph 魔搭 ModelScope 平台
    C[MCP Server (FastAPI 云服务)];
end

subgraph 阿里云 Alibaba Cloud
    D[云服务器 ECS];
    E[PostgreSQL + PostGIS 数据库];
    D -- "运行" --> E;
end

B -- "调用工具 (RESTful API)" --> C;
C -- "数据库查询 (TCP/IP)" --> E;
E -- "返回数据" --> C;
C -- "返回JSON" --> B;
B -- "生成回答" --> A;

项目部署指南

本指南记录了从零开始部署此服务的完整步骤。

1. 准备云数据库 (阿里云ECS)

1. 创建ECS实例:

   • 地域: 华东1 (杭州)
   • 操作系统: Ubuntu Server 22.04 LTS 64位
   • 网络: 分配公网IPv4地址。

2. 安装数据库软件:

   • 通过ECS Workbench或SSH登录服务器。
   • 执行以下命令安装PostgreSQL及PostGIS扩展：
     bash
     sudo apt update && sudo apt install -y postgresql postgresql-contrib postgis

3. 配置远程访问:

   • 修改 /etc/postgresql/14/main/postgresql.conf，将 listen_addresses 改为 '*'。
   • 修改 /etc/postgresql/14/main/pg_hba.conf，在末尾添加 host all all 0.0.0.0/0 md5。
   • 重启服务: sudo systemctl restart postgresql。

4. 创建用户和数据库:

   • 登录psql: sudo -u postgres psql。
   • 执行SQL命令创建数据库(bird_db)、用户(bird_admin)并为数据库启用PostGIS扩展(CREATE EXTENSION postgis;)。

5. 配置安全组:

   • 在阿里云ECS控制台的安全组规则中，添加入方向规则，允许TCP协议对5432端口的访问，授权对象设为0.0.0.0/0（仅供测试）。

2. 准备代码仓库 (Gitee)

1. 创建四个核心文件:
   • main.py: FastAPI应用主文件，定义了API端点。
   • database.py: SQLAlchemy数据库连接配置文件。
   • requirements.txt: 项目的Python依赖列表。
   • .gitignore: 指定Git应忽略的文件（如.env）。
2. 上传至Gitee: 创建一个公开的Gitee仓库，并将以上四个文件上传。

3. 部署到魔搭 (ModelScope)

1. 登录魔搭平台，进入“创空间” -> “创建MCP Server”。
2. 填写表单:
   • 来源地址: 填写第2步中创建的Gitee仓库地址。
   • 托管类型: 选择“平台托管”或类似的云端部署选项。
   • 环境变量配置:
     • DB_HOST: 您的ECS公网IP。
     • DB_PORT: 5432。
     • DB_USER: bird_admin。* DB_PASSWORD: 您的数据库密码。

• DB_NAME: bird_db。
• 服务配置 (JSON):
  json
  {
  "mcpServers": {
  "bird_service": {
  "command": "uvicorn main:app --host 0.0.0.0 --port 8080"
  }
  }
  }

1. 部署服务: 平台将自动拉取代码、安装依赖并根据配置启动服务。

4. 在GEOGPT中配置和使用

1. 获取URL: 从魔搭平台获取上一步部署成功的服务的官方URL。
2. 添加工具: 在GEOGPT平台中，选择“添加工具”（类型选择“其他”或通用API）。
3. 配置工具:
   • URL: 粘贴魔搭提供的URL，并在结尾加上API路径 /query-nearby-birds/。
   • 描述: 填入为LLM优化过的详细功能描述。
4. 开始使用: 向GEOGPT智能体发出自然语言提问，例如：“南昌鄱阳湖附近最近有什么候鸟？”

项目文件结构

.
├── .gitignore # 忽略不需要上传的文件
├── database.py # 数据库连接模块
├── main.py # FastAPI应用主逻辑
└── requirements.txt # Python依赖列表