CPBV MCP Server

企业绩效标准值查询服务 (Enterprise Performance Benchmark Values MCP Server)

这是一个基于 Model Context Protocol (MCP) 的 Python 服务器，提供企业绩效标准值查询功能。

功能特性

1. 查询支持的行业 - 返回所有支持的行业层级结构
2. 查询绩效标准值 - 根据年份、行业和范围查询企业绩效标准值

安装

前置要求

• Python 3.8 或更高版本
• pip 或 uv 包管理器

从 PyPI 安装

pip install cpbv-mcp-server

从源码安装

# 克隆仓库
git clone <repository-url>
cd cpbv_mcp_server

# 安装依赖和包
pip install -e .

# 或者使用 uv
uv pip install -e .

使用方法

作为 MCP 服务器运行

cpbv-mcp-server

或者使用 Python 模块方式：

python -m cpbv_mcp_server.server

在 Claude Desktop 中配置

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

{
  "mcpServers": {
    "cpbv-mcp-server": {
      "command": "cpbv-mcp-server",
      "args": []
    }
  }
}

使用 MCP Inspector 测试

# 启动服务器
cpbv-mcp-server

# 在另一个终端运行 Inspector
npx -y @modelcontextprotocol/inspector

工具说明

1. list_industries

查询企业绩效标准值支持的行业。

返回格式：

{
  "name": "全国国有企业",
  "children": [
    {
      "name": "工业",
      "children": [...]
    }
  ]
}

2. get_performance_benchmarks

查询指定行业的企业绩效标准值。

参数：

• year (string): 年份，例如 "2024"
• industry (string): 行业名称，例如 "煤炭工业"
• scope (string): 范围，例如 "全行业"、"大型企业"、"中型企业"、"小型企业"

返回格式：

{
  "dimensions": [
    {
      "name": "盈利回报指标",
      "items": [
        {
          "name": "净资产收益率",
          "unit": "%",
          "benchmarks": {
            "excellent": 19.9,
            "good": 14.6,
            "average": 11.0,
            "low": 6.2,
            "poor": -0.6
          }
        }
      ]
    }
  ]
}

3. list_indicators

查询绩效标准值支持的指标。

返回格式：

{
  "绩效指标分类": [
    {
      "category": "盈利回报指标",
      "indicators": ["净资产收益率", "营业收入利润率", "总资产报酬率", "盈余现金保障倍数"]
    },
    {
      "category": "资产运营指标",
      "indicators": ["总资产周转率", "应收账款周转率", "流动资产周转率", "两金占流动资产比重"]
    },
    ...
  ]
}

4. list_available_industries_and_scopes

查询数据库中提供哪些行业和范围的绩效标准值。

参数：

• year (string, 可选): 年份，例如 "2024"。如果不提供，则返回所有年份的数据

返回格式：

{
  "year": "2024",
  "industries": [
    {
      "industry": "煤炭工业",
      "scopes": ["全行业", "大型企业"]
    }
  ],
  "all_scopes": ["全行业", "大型企业"],
  "total_industries": 1,
  "total_combinations": 2
}

项目结构

cpbv_mcp_server/
├── cpbv_mcp_server/
│   ├── __init__.py
│   └── server.py          # MCP 服务器主文件
├── config/
│   ├── industry_hierarchy.json  # 行业层级数据
│   ├── data.db                  # SQLite 数据库
│   └── create_industry_data.sql # 数据库创建脚本
├── pyproject.toml         # 项目配置文件
└── README.md              # 项目说明文档

开发

安装开发依赖

pip install -e ".[dev]"

代码格式化

# 格式化代码（使用 black）
black cpbv_mcp_server/

# 或使用 ruff 格式化（推荐，速度更快）
ruff format cpbv_mcp_server/

# 检查代码质量和风格问题
ruff check cpbv_mcp_server/

# 自动修复可修复的问题
ruff check --fix cpbv_mcp_server/

打包和发布到 PyPI

详细的打包和发布指南请参考 PACKAGING.md。

快速开始

1. 安装构建工具：

pip install build twine

2. 构建分发包：

python -m build

3. 上传到 PyPI：

# 测试 PyPI（TestPyPI）- 用于测试的独立环境
# TestPyPI 是 PyPI 的测试版本，允许你在不影响正式环境的情况下测试打包和发布流程
# 访问地址：https://test.pypi.org/
python -m twine upload --repository testpypi dist/*

# 正式 PyPI - 生产环境
# 这是用户实际安装包的地方，访问地址：https://pypi.org/
python -m twine upload dist/*

关于 TestPyPI：

• TestPyPI (Test Python Package Index) 是 PyPI 的测试环境
• 独立于正式 PyPI，用于测试打包和发布流程
• 需要单独注册账号：https://test.pypi.org/
• 包名可以与正式 PyPI 重复，不会冲突
• 建议先在这里测试，确认无误后再发布到正式 PyPI

注意：

• 需要在 PyPI 和 TestPyPI 分别注册账号并获取 API token
• 每次发布前需要更新版本号
• 建议先在测试 PyPI 上测试，确认打包正确后再发布到正式 PyPI

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！