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代码（可选，用于开发）
安装
# Clone the repository
git clone
cd mcp-analyst
# Install dependencies (automatically handled by uv)
uv pip install fastmcp duckdb pandas pyarrow numpy运行测试
# 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:
{
"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：复古性能分析
# 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：日历趋势
# 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：当前仪表板
# 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 -数值运算
运行开发服务器
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序列化（已修复✅)
问题： 在Claude Desktop中导致序列化错误的Numpy类型\ 解决方案： 在所有工具中显式转换为原生Python类型\ 状态： 已修复并通过序列化测试进行了验证
🤝 贡献
这是一个用于投资组合分析的个人项目。如有疑问或建议，请联系存储库所有者。
📝 许可证
\[在此处添加您的许可证\]
🙏 致谢
- 采用FastMCP框架构建
- 用于高性能分析的DuckDB
- 模型上下文协议（MCP）规范
📞 联系
\[在此处添加您的联系信息\]
______________________________________________________________________
状态： ✅ 生产就绪\ 最后更新时间： 2025年12月7日\ 版本： 1.0.0