MCP性能分析服务器
一个全面的模型上下文协议(MCP)服务器,为信用卡和抵押贷款组合提供灵活的性能分析。
🎯 概述
该项目实现了 统一性能分析服务器 有3个专门的工具,为金融产品提供复古分析、日历趋势和当前性能快照。使用DuckDB构建,用于对Parquet文件进行快速SQL查询。
✨ 特性
-
3专用工具
-
get_vintage_performance()-基于MOB的生命周期分析 get_calendar_performance_trends()-日历月趋势-
get_current_cohort_snapshot()-最新性能仪表板 -
6综合指标
-
核销率(每个未结账户)
- 拖欠率(30+DPD)
- 平均余额
- 关闭率(每个未结账户)
- 提前还款率(仅抵押贷款)
-
信用卡使用率(仅限卡)
-
灵活的分析维度
-
时间:MOB与日历月
- 度量基础:单位vs美元
- 累计:期间与累计
- 比较:细分市场、复古季或两者兼而有之
🚀 快速开始
先决条件
- Python 3.10+
uv包管理器- VS代码(可选,用于开发)
安装```bash
Clone the repository
git clone
cd mcp-analyst
Install dependencies (automatically handled by uv)
uv pip install fastmcp duckdb pandas pyarrow numpy
### 运行测试```bash
# Run comprehensive test suite
cd "D:\October 2025\mcp\Code Examples\mcp-analyst"
uv run python tests\test_performance_analytics.py
# Run serialization validation test
uv run python tests\test_serialization.py
添加到Claude桌面
将此添加到您的 claude_desktop_config.json:```json
{
"mcpServers": {
"performance-analytics": {
"command": "uv",
"args": [
"--directory",
"D:\October 2025\mcp\Code Examples\mcp-analyst",
"run",
"python",
"servers/performance_analytics_server.py"
]
}
}
}
然后重新启动Claude Desktop。
## 📊 使用示例
### 示例1:复古性能分析```python
# Create cohort and analyze MOB-based writeoff rates
get_vintage_performance(
cohort_id="cohort_cmp_20251207",
product_type="card",
metric="writeoff_rate_per_open",
metric_basis="units",
cumulative=True,
comparison_dimension="segment"
)
示例2:日历趋势```python
Track delinquency rates across calendar months
get_calendar_performance_trends(
cohort_id="cohort_cmp_20251207",
product_type="card",
metric="delinquency_rate",
metric_basis="units",
comparison_dimension="segment"
)
### 示例3:当前仪表板```python
# Get latest performance snapshot across all metrics
get_current_cohort_snapshot(
cohort_id="cohort_cmp_20251207",
product_type="card",
comparison_dimension="segment"
)
🏗️ 建筑
统一服务器设计
单个服务器处理两种产品(卡和抵押贷款),无需重复工具:
product_type参数路由到正确的数据文件- 度量注册表集中了所有定义
- 基于参数的动态SQL生成
DuckDB优化
- 使用即时JOIN直接查询Parquet文件
- 不需要中间非标准化数据集
- 大型队列的查询时间低于1000毫秒
- 累积指标的高效窗口功能
文件夹结构```
mcp-analyst/
├── servers/
│ ├── performance_analytics_server.py # Main analytics server
│ ├── client_cohort_server.py # Cohort management
│ ├── card_origination_server.py
│ ├── mortgage_origination_server.py
│ └── ... (other servers)
├── tests/
│ ├── test_performance_analytics.py # Comprehensive test suite
│ ├── test_serialization.py # JSON serialization validation
│ └── ... (other tests)
├── docs/
│ ├── TEST_RESULTS_SUMMARY.md
│ ├── PERFORMANCE_TOOL_DESIGN.md
│ ├── SERIALIZATION_BUG_FIX.md
│ ├── QUICK_REFERENCE.md
│ └── ... (other documentation)
└── data/
├── card_performance_snapshots.parquet
├── mortgage_performance_snapshots.parquet
└── ... (data files)
## 🧪 测试覆盖率
**成功率:** 100%(8/8测试通过)\
**执行时间:** 约2秒
### 测试类别
- ✅ 指标注册表(6个指标)
- ✅ 参数验证(12种组合)
- ✅ 工具1:复古表演(卡片-8个场景)
- ✅ 工具1:复古表现(抵押贷款-3种情况)
- ✅ 工具2:日历趋势(卡片-2个场景)
- ✅ 工具2:日历趋势(抵押贷款-3种情况)
- ✅ 工具3:当前快照(卡-2种情况)
- ✅ 工具3:当前快照(抵押贷款-1场景)
## 📈 性能指标
|分析类型|查询时间|数据量|结果|
|--------------|------------|-------------|---------|
|复古性能(卡片)|50-84ms |48000张快照|✅ |
|复古性能(抵押贷款)|~80ms|3924张快照|✅ |
|日历趋势|32-50ms|每月汇总|✅ |
|当前快照|72-109ms|最新日期多指标|✅ |
**平均查询时间:** 约82毫秒
## 🛠️ 发展
### 关键技术
- **FastMCP** -MCP服务器框架
- **DuckDB** -高性能SQL引擎
- **熊猫** -数据操纵
- **PyArrow** -拼花文件处理
- **数值Python** -数值运算
### 运行开发服务器```bash
cd "D:\October 2025\mcp\Code Examples\mcp-analyst\servers"
fastmcp dev performance_analytics_server.py
添加新指标
- 将度量定义添加到
METRIC_DEFINITIONS在performance_analytics_server.py - 指定周期/累计和单位/美元的计算SQL
- 添加产品兼容性
- 在中创建测试用例
test_performance_analytics.py
📚 文档
- 快速参考 -使用指南和示例
- 性能工具设计 -架构和设计决策
- 测试结果总结 -全面的测试文档
- 序列化错误修复 -JSON序列化解决方案
- DuckDB优化 -性能优化详细信息
🐛 已知问题和解决方案
JSON序列化(已修复✅)
问题: 在Claude Desktop中导致序列化错误的Numpy类型\
解决方案: 在所有工具中显式转换为原生Python类型\
状态: 已修复并通过序列化测试进行了验证
🤝 贡献
这是一个用于投资组合分析的个人项目。如有疑问或建议,请联系存储库所有者。
📝 许可证
[在此处添加您的许可证]
🙏 致谢
- 采用FastMCP框架构建
- 用于高性能分析的DuckDB
- 模型上下文协议(MCP)规范
📞 联系
[在此处添加您的联系信息]
状态: ✅ 生产就绪\
最后更新时间: 2025年12月7日\
版本: 1.0.0
