项目管理系统数据库服务 (Project Analysis MCP)

参考技术安档网址: https://www.bilibili.com/opus/1075899615621939205

项目简介

本项目是一个基于 MCP (Model Context Protocol) 框架开发的项目管理系统数据库服务，提供项目信息查询、投资统计分析、数据可视化以及Excel导出等功能。系统通过 FastMCP 框架将数据库查询能力封装为标准化工具，支持通过 MCP 协议对外提供服务。

什么是 MCP？

Model Context Protocol (MCP) 是一个开放标准，用于在 AI 应用程序和外部数据源之间建立安全连接。MCP 允许 AI 助手访问实时信息、执行操作，并利用各种工具和资源，而无需直接集成每个服务。

本项目实现了 MCP Server，将项目管理系统的数据库操作封装为标准的 MCP 工具，可以被任何支持 MCP 协议的客户端（如 Claude Desktop、自定义 AI 应用等）调用。

核心特性

✅ 20+ 个标准化工具函数 - 覆盖项目查询、统计分析、数据导出等全流程
✅ MCP 协议标准实现 - 基于官方 MCP SDK，兼容所有 MCP 客户端
✅ 数据可视化 - 支持柱状图、折线图、饼图、散点图等多种图表类型
✅ Excel 导出 - 灵活的数据导出，支持自定义样式和格式
✅ 云存储集成 - 自动上传生成的文件到腾讯云 COS
✅ 类型安全 - 完整的 Python 类型提示，提高代码可维护性
✅ 错误处理 - 完善的异常处理机制，统一的错误返回格式

核心功能

1. 项目信息查询模块

基础查询功能

按项目编码查询 (get_project): 根据项目编码获取单个项目的详细信息
按单位编码查询 (get_projects_by_company): 获取指定单位下的所有项目列表
按年份查询 (get_projects_by_year): 根据项目年份筛选项目
按类别查询 (get_projects_by_category): 根据项目类别筛选项目
获取所有项目 (get_all_projects): 获取系统中所有项目信息
项目总数统计 (get_project_count): 统计项目总数
关键词搜索 (search_projects): 支持按项目名称或单位名称进行模糊搜索

2. 项目月报管理模块

单月月报查询 (get_monthly_report): 获取指定项目在特定年月的月报数据
项目所有月报 (get_project_monthly_reports): 获取指定项目的所有历史月报
日期范围查询 (get_monthly_reports_by_date_range): 根据日期范围查询月报数据

3. 单位季报管理模块

单季度季报查询 (get_quarterly_report): 获取指定单位在特定年度的季度报告
单位所有季报 (get_company_quarterly_reports): 获取指定单位的所有历史季报
日期范围查询 (get_quarterly_reports_by_date_range): 根据日期范围查询季报数据

4. 综合查询与分析模块

项目关联查询 (get_project_with_reports): 获取项目信息及其关联的所有月报数据
单位项目关联查询 (get_company_projects_with_reports): 获取单位下所有项目及其报表数据
投资统计分析 (get_investment_statistics): 按项目类别统计投资情况（项目数量、总投资额、平均投资额）
项目投资进度查询 (get_project_investment_progress): 查询所有项目的投资进度，包括：
- 累计投资额
- 总投资额
- 完成进度百分比
- 项目状态（已完成/即将完工/进行中）
月度投资趋势分析 (get_monthly_investment_trend): 分析月度投资趋势，包括：
- 月度总投资额
- 平均项目投资额
- 环比增长率

5. 数据可视化模块

通用可视化工具 (visualize_data): 支持多种图表类型的数据可视化

支持的图表类型:
- 柱状图 (bar): 适合展示分类数据对比
- 折线图 (line): 适合展示趋势变化
- 饼图 (pie): 适合展示占比关系
- 散点图 (scatter): 适合展示数据分布
功能特性:
- 自动中文字体支持（跨平台兼容）
- 自定义图表标题、坐标轴标签
- 可配置图表尺寸
- 支持自定义颜色或随机颜色生成
- 自动上传图表到腾讯云COS并返回HTML图片标签
- 高分辨率输出（300 DPI）

6. Excel导出模块

通用Excel生成工具 (excel_process): 支持将任意结构化数据导出为Excel文件

功能特性:
- 支持字典列表或Pandas DataFrame作为输入
- 自定义工作表名称
- 灵活的列宽设置（支持统一宽度、按列名设置、按列顺序设置）
- 可自定义标题行样式（填充色、字体、边框、对齐方式）
- 支持数字格式自定义
- 自动筛选功能
- 自动处理Decimal类型数据
- 生成的文件自动上传到腾讯云COS并返回URL

7. 自定义查询模块

自定义SQL查询 (custom_query): 支持执行自定义SQL查询语句，提供最大灵活性

技术架构

技术栈

核心依赖

Python版本: >= 3.11
MCP 框架:
- mcp[cli] >= 1.12.4: MCP 协议核心库，提供标准化的工具服务接口
- fastmcp: FastMCP 框架，简化 MCP Server 开发（基于 mcp 库）

Web 框架与服务器

starlette >= 0.47.2: 轻量级 ASGI Web 框架
uvicorn >= 0.35.0: 高性能 ASGI 服务器
sse-starlette >= 3.0.2: Server-Sent Events 支持（用于 MCP SSE 传输）
httpx >= 0.28.1: 现代 HTTP 客户端库
httpx-sse >= 0.4.1: SSE 客户端支持

数据处理

pandas: 数据处理和 Excel 生成（需单独安装）
openpyxl: Excel 文件格式化和样式设置（需单独安装）
numpy: 数值计算支持（需单独安装）

数据可视化

matplotlib: 图表生成和可视化（需单独安装）

数据库

pymysql: MySQL 数据库连接和操作（需单独安装）

云存储

qcloud_cos: 腾讯云对象存储（COS）SDK（需单独安装）

配置与工具

pydantic >= 2.11.7: 数据验证和设置管理
pydantic-settings >= 2.10.1: Pydantic 配置管理扩展
python-dotenv >= 1.1.1: 环境变量管理
typer >= 0.16.0: 现代 CLI 框架（MCP CLI 工具）
rich >= 14.1.0: 终端美化输出

其他依赖

anyio >= 4.10.0: 异步 I/O 抽象层
jsonschema >= 4.25.0: JSON Schema 验证
typing-extensions >= 4.14.1: Python 类型扩展支持

注意: 部分依赖（如 pandas、matplotlib、pymysql 等）需要在 pyproject.toml 或 requirements.txt 中单独声明。当前项目仅声明了 MCP 核心依赖。

系统架构

┌─────────────────────────────────────────┐
│         MCP Client (外部调用)           │
└─────────────────┬───────────────────────┘
                  │
┌────────────────────────────────────────┐
│         FastMCP Server (main.py)         │
│  - 工具函数注册与路由                     │
│  - 请求处理与响应                         │
└─────┬───────────────┬───────────┬───────┘
      │               │           │
┌───────────┐  ┌───────────┐  ┌─────────────┐
│ Database   │  │ Excel      │  │ COS File     │
│ Manager    │  │ Processor  │  │ Operation    │
│ (database) │  │ (excel)    │  │ (cosfile)    │
└─────┬──────┘  └─────┬──────┘  └─┬────────────┘
      │               │           │
┌───────────────────────────────────────────┐
│         MySQL Database                        │
│  - project_info (项目信息表)                  │
│  - project_monthly_report (项目月报表)        │
│  - company_quarterly_report (单位季报表)      │
└──────────────────────────────────────────────┘

模块设计

1. 数据库管理层 (`database.py`)

DatabaseManager类: 封装所有数据库操作
- 连接管理：自动建立和维护MySQL连接
- 查询执行：统一的查询执行接口，支持参数化查询
- 事务管理：自动处理提交和回滚
- 结果处理：统一返回字典列表格式

2. Excel处理层 (`excelprocess.py`)

generate_excel_bytes函数: 核心Excel生成函数
- 数据转换：自动将各种数据格式转换为DataFrame
- 样式配置：支持丰富的样式自定义选项
- 格式处理：自动处理Decimal类型，支持数字格式设置
- 内存优化：使用BytesIO实现内存中生成，无需临时文件

3. 文件存储层 (`cosfileoperation.py`)

upload_file_to_cos函数: COS文件上传封装
- 统一接口：接收文件对象和文件名
- 路径管理：自动构建COS存储路径
- 错误处理：完善的异常处理和返回信息

4. 配置管理层 (`config.py`)

配置分离: 将敏感配置信息集中管理
- 数据库配置：连接信息、认证信息
- COS配置：密钥、区域、存储桶信息
- MCP服务配置：服务地址和端口

数据库设计

核心数据表

project_info (项目信息表)
- 存储项目基本信息：项目编码、项目名称、单位信息、投资额、年份、类别等
project_monthly_report (项目月报表)
- 存储项目月度报告数据：投资额、累计投资额、进度百分比、报告日期等
company_quarterly_report (单位季报表)
- 存储单位季度报告数据：季度投资统计、报告日期等

安装与配置

环境要求

Python >= 3.11
MySQL数据库
腾讯云COS账户（用于文件存储）

安装步骤

克隆项目

git clone <repository-url>
cd project-analysis-mcp

安装依赖

给配置目录加权限
sudo chown -R $(whoami) /Users/taopeng/.config/fish

macOS 用户推荐用 brew 安装，更方便升级。使用 Homebrew 安装
如果你用 Homebrew 管理软件，可以这样：brew install uv
然后验证：uv --version

在uv里安装指定版本的python
uv python install 3.13

uv init mcp-server-demo

创建.venv
sudo chown -R $(whoami) /Users/taopeng/.cache
uv cache clean

source .venv/bin/activate
# 使用uv（推荐）
uv sync --active

# 或使用pip
pip install -r requirements.txt

配置环境变量

创建 .env 文件（或直接修改 config.py）:

# 数据库配置
DB_HOST=10.6.133.8
DB_PORT=9090
DB_NAME=test
DB_USER=report_user
DB_PASSWORD=Str3!

# COS配置
COS_SECRET_ID=your_secret_id
COS_SECRET_KEY=your_secret_key
COS_REGION=ap-beijing
COS_BUCKET=your_bucket_name
COS_FILE_URL=mcp_test/

# MCP服务配置
MCP_HOST=0.0.0.0
MCP_PORT=8003

安装额外依赖（如果使用 uv）

# 添加项目所需的其他依赖
uv add cos-python-sdk-v5
uv add pandas openpyxl matplotlib pymysql 
uv add fastmcp

或使用 pip：

pip install pandas openpyxl matplotlib pymysql cos-python-sdk-v5 fastmcp

启动服务

python main.py

或
uv run main.py妆“ad

MCP 客户端连接

安装Cherry Studio v1.6.7调试工具

地址: https://www.cherry-ai.com/download

服务将在配置的 host 和 port 上启动，默认使用 SSE (Server-Sent Events) 传输协议。

启动成功后，你会看到类似以下的日志：

INFO:__main__:启动MCP服务: host=0.0.0.0, port=8003
INFO:uvicorn.error:Started server process
INFO:uvicorn.error:Uvicorn running on http://0.0.0.0:8003 (Press CTRL+C to quit)

方式一：通过 HTTP SSE 连接

MCP Server 启动后，客户端可以通过 HTTP SSE 连接到服务：

http://localhost:8003/sse

方式二：Claude Desktop 配置

在 Claude Desktop 的配置文件中添加：

{
  "mcpServers": {
    "project-analysis": {
      "command": "python",
      "args": ["/path/to/project-analysis-mcp/main.py"],
      "env": {
        "DB_HOST": "10.6.133.8",
        "DB_PORT": "9090",
        "DB_NAME": "test",
        "DB_USER": "report_user",
        "DB_PASSWORD": "Str3!"
      }
    }
  }
}

方式三：通过 MCP CLI 工具

# 使用 MCP CLI 连接到服务器
mcp list-tools --server http://localhost:8003/sse

使用示例

1. 通过 MCP 客户端调用工具

Python 客户端示例

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio

async def main():
    # 连接到 MCP Server
    server_params = StdioServerParameters(
        command="python",
        args=["main.py"]
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # 初始化会话
            await session.initialize()
            
            # 调用工具：查询项目信息
            result = await session.call_tool(
                "get_project",
                arguments={"project_code": "PROJ001"}
            )
            print(result)
            
            # 调用工具：获取投资统计
            stats = await session.call_tool(
                "get_investment_statistics",
                arguments={}
            )
            print(stats)

asyncio.run(main())

HTTP 客户端示例

import httpx
import json

# 通过 HTTP SSE 连接
async with httpx.AsyncClient() as client:
    # 调用工具
    response = await client.post(
        "http://localhost:8003/tools/call",
        json={
            "name": "get_project",
            "arguments": {"project_code": "PROJ001"}
        }
    )
    result = response.json()
    print(result)

2. 工具函数使用示例

查询项目信息

# 按项目编码查询
result = get_project(project_code="PROJ001")

# 按单位查询
projects = get_projects_by_company(company_code="COMP001")

# 关键词搜索
search_results = search_projects(keyword="基础设施")

生成数据可视化图表

# 获取投资趋势数据
trend_data = get_monthly_investment_trend()

# 生成折线图
chart_html = visualize_data(
    data=trend_data['data'],
    x_field='年月',
    y_field='月度总投资额',
    chart_type='line',
    title='月度投资趋势分析',
    x_label='时间',
    y_label='投资额（万元）',
    width=12,
    height=6
)

# 生成柱状图
bar_chart = visualize_data(
    data=stats_data['data'],
    x_field='项目类别',
    y_field='总投资额',
    chart_type='bar',
    title='各类别投资统计',
    colors=['#4472C4', '#ED7D31', '#A5A5A5']
)

导出Excel报表

# 获取项目投资进度数据
progress_data = get_project_investment_progress()

# 导出为Excel（基础用法）
excel_url = excel_process(
    data=progress_data['data'],
    sheet_name='项目投资进度'
)

# 导出为Excel（高级用法：自定义样式）
excel_url = excel_process(
    data=progress_data['data'],
    sheet_name='项目投资进度',
    column_width={'项目名称': 30, '项目单位': 20, '累计投资额': 15},
    header_style={
        'fill': '4472C4',  # 蓝色背景
        'font': {'bold': True, 'color': 'FFFFFF', 'size': 12},
        'alignment': {'horizontal': 'center', 'vertical': 'center'},
        'border': {
            'left': {'style': 'thin', 'color': '000000'},
            'right': {'style': 'thin', 'color': '000000'},
            'top': {'style': 'thin', 'color': '000000'},
            'bottom': {'style': 'thin', 'color': '000000'}
        }
    },
    number_format={'累计投资额': '#,##0.00', '完成进度': '0.00%'}
)

3. 完整工作流示例

# 1. 查询单位下的所有项目
company_projects = get_projects_by_company(company_code="COMP001")

# 2. 获取项目及其报表数据
project_with_reports = get_company_projects_with_reports(company_code="COMP001")

# 3. 分析投资趋势
trend_analysis = get_monthly_investment_trend()

# 4. 生成可视化图表
chart = visualize_data(
    data=trend_analysis['data'],
    x_field='年月',
    y_field='月度总投资额',
    chart_type='line',
    title='月度投资趋势'
)

# 5. 导出完整报表
excel_report = excel_process(
    data=project_with_reports['data'],
    sheet_name='项目综合报表',
    column_width=15
)

工具函数完整列表

项目查询工具 (7个)

工具名称	功能描述	参数
`get_project`	按项目编码查询	`project_code: str`
`get_projects_by_company`	按单位编码查询	`company_code: str`
`get_projects_by_year`	按年份查询	`year: int`
`get_projects_by_category`	按类别查询	`category: str`
`get_all_projects`	获取所有项目	无
`get_project_count`	统计项目总数	无
`search_projects`	关键词搜索	`keyword: str`

月报管理工具 (3个)

工具名称	功能描述	参数
`get_monthly_report`	单月月报查询	`project_code: str, year: int, month: int`
`get_project_monthly_reports`	项目所有月报	`project_code: str`
`get_monthly_reports_by_date_range`	日期范围查询	`start_date: str, end_date: str`

季报管理工具 (3个)

工具名称	功能描述	参数
`get_quarterly_report`	单季度季报查询	`company_code: str, year: int, quarter: int`
`get_company_quarterly_reports`	单位所有季报	`company_code: str`
`get_quarterly_reports_by_date_range`	日期范围查询	`start_date: str, end_date: str`

综合分析工具 (5个)

工具名称	功能描述	参数
`get_project_with_reports`	项目关联查询	`project_code: str`
`get_company_projects_with_reports`	单位项目关联查询	`company_code: str`
`get_investment_statistics`	投资统计分析	无
`get_project_investment_progress`	项目投资进度	无
`get_monthly_investment_trend`	月度投资趋势	无

数据处理工具 (3个)

工具名称	功能描述	参数
`visualize_data`	数据可视化	`data, x_field, y_field, chart_type, ...`
`excel_process`	Excel导出	`data, sheet_name, column_width, ...`
`custom_query`	自定义SQL查询	`sql: str`

总计：21个工具函数

技术亮点

标准化接口: 基于 MCP 协议，提供标准化的工具接口，易于集成和扩展
模块化设计: 清晰的模块划分，职责单一，易于维护
类型安全: 使用 Python 类型提示，提高代码可读性和可维护性
错误处理: 完善的异常处理机制，所有工具函数都有统一的错误返回格式
跨平台支持: 中文字体自动检测和配置，支持 Windows、macOS、Linux
云存储集成: 自动将生成的文件上传到云存储，返回可访问的 URL
灵活的数据处理: 支持多种数据格式输入，自动转换和处理
SSE 传输协议: 使用 Server-Sent Events 实现实时通信，支持长连接
异步支持: 基于 Starlette 和 Uvicorn，支持高并发请求
配置灵活: 支持环境变量和配置文件两种配置方式

项目结构

project-analysis-mcp/
├── main.py                 # 主程序入口，MCP工具函数定义
├── database.py             # 数据库管理类
├── excelprocess.py         # Excel生成模块
├── cosfileoperation.py     # 腾讯云COS文件操作
├── config.py               # 配置文件
├── pyproject.toml          # 项目依赖配置
├── uv.lock                 # 依赖锁定文件
└── README.md               # 项目文档

开发指南

添加新的工具函数

在 main.py 中定义工具函数：

@mcp.tool()
def my_new_tool(param1: str, param2: int) -> dict:
    """
    工具函数描述
    
    Args:
        param1: 参数1说明
        param2: 参数2说明
    
    Returns:
        返回结果说明
    """
    try:
        # 实现逻辑
        result = db_manager.execute_query("SELECT * FROM table")
        return {
            "status": "success",
            "data": result,
            "count": len(result)
        }
    except Exception as e:
        return {
            "status": "error",
            "message": str(e)
        }

工具函数会自动注册到 MCP Server，无需额外配置

调试技巧

启用详细日志：

import logging
logging.basicConfig(level=logging.DEBUG)

测试单个工具函数：

# 在 main.py 中添加测试代码
if __name__ == "__main__":
    # 测试工具函数
    result = get_project(project_code="TEST001")
    print(result)

使用 MCP Inspector：

# 安装 MCP Inspector
pip install mcp-inspector

# 启动 Inspector
mcp-inspector python main.py

注意事项

安全性:
- 生产环境请使用环境变量管理敏感信息，不要将密钥硬编码在代码中
- 建议使用 .env 文件，并确保 .env 文件不被提交到版本控制系统
- 对 SQL 查询进行参数化，防止 SQL 注入攻击
数据库连接:
- 当前实现使用单例连接，生产环境建议使用连接池（如 SQLAlchemy）
- 考虑实现连接重试机制和健康检查
文件存储:
- 确保 COS 存储桶有足够的存储空间和访问权限
- 定期清理过期文件，避免存储成本增加
- 考虑实现文件访问权限控制
性能优化:
- 对于大数据量查询，建议添加分页功能
- 对频繁查询的数据添加缓存机制
- 优化 SQL 查询，添加必要的索引
日志记录:
- 系统已集成 logging 模块，可根据需要调整日志级别
- 生产环境建议使用结构化日志（如 JSON 格式）
- 考虑集成日志聚合服务（如 ELK、Loki）
错误处理:
- 所有工具函数都应返回统一的错误格式
- 避免向客户端暴露敏感错误信息
- 记录详细的错误日志用于调试
MCP 协议:
- 确保工具函数的参数和返回值符合 MCP 规范
- 工具函数名称应清晰、描述性
- 提供完整的工具函数文档字符串

故障排查

常见问题

服务启动失败
- 检查端口是否被占用：lsof -i :8003
- 检查 Python 版本：python --version（需要 >= 3.11）
- 检查依赖是否安装完整：pip list | grep mcp
数据库连接失败
- 检查数据库配置是否正确
- 检查网络连接：telnet DB_HOST DB_PORT
- 检查数据库用户权限
中文字体显示问题
- Windows: 确保系统安装了 SimHei 或 Microsoft YaHei
- macOS: 确保系统安装了 STHeiti 或 Songti SC
- Linux: 安装中文字体：sudo apt-get install fonts-wqy-microhei
COS 上传失败
- 检查 COS 配置（Secret ID、Secret Key、Region、Bucket）
- 检查 COS 存储桶权限设置
- 检查网络连接和防火墙设置
MCP 客户端连接失败
- 检查服务是否正常启动
- 检查 SSE 端点是否可访问：curl http://localhost:8003/sse
- 检查防火墙和端口配置

日志查看

# 查看服务日志
tail -f logs/mcp_server.log

# 查看错误日志
grep ERROR logs/mcp_server.log

性能优化建议

数据库优化
- 为常用查询字段添加索引
- 使用连接池管理数据库连接
- 对复杂查询进行优化，避免全表扫描
缓存策略
- 对频繁查询的静态数据添加缓存
- 使用 Redis 缓存热点数据
- 实现缓存失效和更新机制
异步处理
- 对耗时操作（如文件生成、上传）使用异步处理
- 使用消息队列处理批量任务
资源管理
- 及时释放数据库连接和文件句柄
- 对生成的文件实现自动清理机制
- 监控内存和 CPU 使用情况

未来改进方向

缓存机制: 添加 Redis 缓存，提高查询性能
权限控制: 实现基于角色的访问控制（RBAC）
API限流: 添加请求限流机制，防止服务过载
数据校验: 增强输入参数校验和 SQL 注入防护
单元测试: 补充完整的单元测试和集成测试
文档完善: 添加 API 文档和使用示例
监控告警: 集成 Prometheus 和 Grafana 进行监控
容器化部署: 提供 Docker 镜像和 Kubernetes 部署配置
多数据库支持: 支持 PostgreSQL、SQLite 等其他数据库
WebSocket 支持: 添加 WebSocket 传输协议支持
批量操作: 支持批量查询和批量导出功能
数据导入: 支持从 Excel、CSV 等格式导入数据

贡献指南

欢迎贡献代码、报告问题或提出建议！

贡献流程

Fork 本项目
创建特性分支：git checkout -b feature/AmazingFeature
提交更改：git commit -m 'Add some AmazingFeature'
推送到分支：git push origin feature/AmazingFeature
提交 Pull Request

代码规范

遵循 PEP 8 Python 代码规范
使用类型提示（Type Hints）
添加完整的文档字符串（Docstrings）
编写单元测试

更新日志

v0.1.0 (2025-11)

✨ 初始版本发布
✨ 实现 21 个 MCP 工具函数
✨ 支持项目查询、统计分析、数据可视化、Excel 导出
✨ 集成腾讯云 COS 文件存储
✨ 支持中文字体自动检测和配置
✨ 完整的错误处理和日志记录

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

项目维护者: [待补充]
问题反馈: GitHub Issues
功能建议: GitHub Discussions

** 如果这个项目对你有帮助，请给个 Star！**

MCP部署