南海所专家MCP服务器

项目概述

本项目是一个基于FastAPI的MCP（Model Context Protocol）服务器，专门为中国科学院南海海洋研究所设计。采用静态知识库模式，在服务器启动时一次性建立完整的知识库，为用户提供稳定可靠的海洋科学专业问答服务。

核心特性

🏗️ 静态知识库架构

• 一次性建库: 服务器启动时自动爬取南海所官网文章
• 本地存储: 所有文章存储在本地SQLite数据库中
• 稳定服务: 无需依赖外部网站的实时可用性
• 快速响应: 本地搜索，响应速度快

🤖 智能问答系统

• 专业回答: 基于通义千问API的海洋科学问答
• 上下文增强: 结合本地知识库提供更准确的回答
• 多维搜索: 支持标题、内容、摘要的全文搜索

📊 系统监控

• 健康检查: 实时监控服务状态和依赖项
• 统计信息: 提供知识库和问答记录的统计数据
• 日志记录: 完整的操作日志和错误追踪

📋 项目结构

nanhaisuo_mcp/
├── nanhai_expert_server.py    # 主服务器文件
├── nanhai_crawler.py          # 网站爬虫模块
├── database.py               # 数据库管理模块
├── qianwen_api.py           # 通义千问API接口
├── config.py                # 配置管理
├── requirements.txt         # Python依赖
├── .env.example            # 环境变量示例
└── README.md               # 项目说明

🚀 快速启动

1. 环境要求

• Python: 3.8 或更高版本
• 操作系统: Windows 10/11, Ubuntu 18.04+, CentOS 7+
• 内存: 至少 4GB RAM（推荐 8GB+）
• 存储: 至少 20GB 可用空间

2. 安装依赖

cd mcp_server/nanhaisuo_mcp
pip install -r requirements.txt

核心依赖包：

• fastapi
• uvicorn
• requests
• pydantic
• python-multipart

3. 配置环境

# 复制环境变量模板
cp .env.example .env

# 编辑配置文件
# 至少需要配置 QIANWEN_API_KEY

必需配置项：

# 通义千问API密钥（必需）
QIANWEN_API_KEY=your_qianwen_api_key_here

# 服务器配置
SERVER_HOST=127.0.0.1
SERVER_PORT=8002
DEBUG=true

# 静态知识库配置
STARTUP_CRAWL_ARTICLES=50
DATABASE_PATH=nanhai_knowledge.db

获取通义千问API Key：

1. 访问 阿里云百炼平台
2. 注册并登录账号
3. 创建应用并获取API Key

4. 启动服务器

# 直接启动
python nanhai_expert_server.py

服务器将在启动时自动：

1. 初始化数据库
2. 爬取南海所官网文章建立知识库
3. 启动API服务

5. 验证安装

访问以下地址验证服务器是否正常运行：

• 健康检查: http://localhost:8002/
• API文档: http://localhost:8002/docs
• 交互式文档: http://localhost:8002/redoc

📖 API 使用指南

核心接口

• GET / - 健康检查和服务状态
• POST /ask_expert - 专家问答
• POST /search_knowledge - 知识库搜索
• GET /knowledge_stats - 统计信息

专家问答

curl -X POST "http://localhost:8002/ask_expert" \
     -H "Content-Type: application/json" \
     -d '{
       "question": "什么是海洋酸化？",
       "context_limit": 3
     }'

响应示例：

{
  "answer": "作为南海所专家，我可以告诉您海洋酸化是指...",
  "confidence": 0.85,
  "sources": ["南海珊瑚礁生态系统保护研究进展"],
  "expert_role": "中国科学院南海海洋研究所专家"
}

知识库搜索

curl -X POST "http://localhost:8002/search_knowledge" \
     -H "Content-Type: application/json" \
     -d '{
       "keywords": "珊瑚礁",
       "limit": 5
     }'

🔧 常见问题

问题1：端口被占用

# 检查端口占用
netstat -ano | findstr :8002

# 修改端口（在.env文件中）
PORT=8003

问题2：API Key配置

如果不配置API Key，系统将使用模拟数据运行，但功能会受限。

问题3：网络连接

确保网络连接正常，能够访问南海所官网：

• 官网地址：https://scsio.cas.cn
• 科研动态页面：https://scsio.cas.cn/news/kydt/

如果网络连接异常，系统将使用模拟数据用于演示。

🔧 在Open WebUI中配置

在Open WebUI的工具服务器配置中填写：

• URL: http://localhost:8002
• 路径: /openapi.json
• 授权: 选择 "无"
• 密钥: 留空

技术栈

后端框架

• FastAPI: 现代、快速的Web框架
• Uvicorn: ASGI服务器
• Pydantic: 数据验证和序列化

数据存储

• SQLite: 轻量级关系数据库
• 本地文件存储: 简单可靠

外部服务

• 通义千问API: 大语言模型服务
• 南海所官网: 知识来源

工具库

• BeautifulSoup: HTML解析
• Requests: HTTP客户端

设计优势

1. 架构简洁

• 静态知识库避免复杂的增量更新逻辑
• 单体应用，部署简单
• 依赖最小化

2. 性能优异

• 本地数据库，查询速度快
• 异步处理，支持并发
• 合理的缓存策略

3. 稳定可靠

• 不依赖外部网站的实时可用性
• 完整的错误处理和日志记录
• 优雅的降级机制

4. 易于维护

• 代码结构清晰
• 配置集中管理
• 完整的文档和注释

使用场景

适用场景

• 海洋科学研究咨询
• 南海所内部知识查询
• 学术研究辅助
• 专业问答服务

扩展可能

• 支持更多海洋研究机构
• 集成更多知识来源
• 添加多语言支持
• 实现语义搜索

注意事项

使用限制

• 需要有效的通义千问API密钥
• 启动时需要网络连接爬取文章
• 知识库内容取决于南海所官网

最佳实践

• 定期备份数据库文件
• 监控API调用额度
• 合理设置爬取文章数量
• 关注日志文件大小

技术支持

如有问题，请检查：

1. 环境变量配置是否正确
2. 网络连接是否正常
3. API密钥是否有效
4. 日志文件中的错误信息

---

本项目采用静态知识库模式，确保服务稳定可靠，为海洋科学研究提供专业的AI问答支持。