# CPBV MCP Server

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

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

## 功能特性

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

## 安装

### 前置要求

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

### 从 PyPI 安装

```bash
pip install cpbv-mcp-server
```

### 从源码安装

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

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

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

## 使用方法

### 作为 MCP 服务器运行

```bash
cpbv-mcp-server
```

或者使用 Python 模块方式：

```bash
python -m cpbv_mcp_server.server
```

### 在 Claude Desktop 中配置

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

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

### 使用 MCP Inspector 测试

```bash
# 启动服务器
cpbv-mcp-server

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

## 工具说明

### 1. list_industries

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

**返回格式：**
```json
{
  "name": "全国国有企业",
  "children": [
    {
      "name": "工业",
      "children": [...]
    }
  ]
}
```

### 2. get_performance_benchmarks

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

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

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

### 3. list_indicators

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

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

### 4. list_available_industries_and_scopes

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

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

**返回格式：**
```json
{
  "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              # 项目说明文档
```

## 开发

### 安装开发依赖

```bash
pip install -e ".[dev]"
```

### 代码格式化

```bash
# 格式化代码（使用 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](PACKAGING.md)。

### 快速开始

1. **安装构建工具**：
```bash
pip install build twine
```

2. **构建分发包**：
```bash
python -m build
```

3. **上传到 PyPI**：
```bash
# 测试 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！
