Financial News and Notes MCP Server

# 港股财务数据模块 (companyPerformance_hk) ## 📊 功能概述 基于Tushare港股API接口，为FinanceMCP项目新增港股上市公司财务数据分析功能。支持港股利润表、资产负债表、现金流量表的完整财务分析。 ## 🏗️ 模块架构 ``` src/tools/ ├── companyPerformance_hk.ts # 港股主模块 └── companyPerformanceDetail_hk/ # 港股格式化器目录 ├── hkIncomeFormatters.ts # 利润表格式化器 ├── hkBalanceFormatters.ts # 资产负债表格式化器 └── hkCashflowFormatters.ts # 现金流量表格式化器 ``` ## 📋 支持的数据类型 | 数据类型 | Tushare接口 | 格式化器 | 状态 | |---------|------------|---------|------| | **income** | hk_income | ✅ hkIncomeFormatters | 已完成 | | **balance** | hk_balancesheet | ✅ hkBalanceFormatters | 已完成 | | **cashflow** | hk_cashflow | ✅ hkCashflowFormatters | 已完成 | ## 🔧 工具参数 ### 必需参数 - **ts_code**: 港股代码，如 `'00700.HK'`（腾讯控股） - **data_type**: 数据类型 `'income'|'balance'|'cashflow'` - **start_date**: 起始日期 `'YYYYMMDD'` - **end_date**: 结束日期 `'YYYYMMDD'` ### 可选参数 - **period**: 特定报告期 `'YYYYMMDD'`（指定时忽略start_date和end_date） - **ind_name**: 指定财务科目名称，如 `'营业额'`、`'毛利'` ## 💡 使用示例 ### 1. 获取腾讯控股2024年利润表 ```json { "name": "company_performance_hk", "arguments": { "ts_code": "00700.HK", "data_type": "income", "start_date": "20240101", "end_date": "20241231" } } ``` ### 2. 查询建设银行特定财务科目 ```json { "name": "company_performance_hk", "arguments": { "ts_code": "00939.HK", "data_type": "income", "start_date": "20230101", "end_date": "20231231", "ind_name": "营业额" } } ``` ### 3. 获取阿里巴巴2023年年报完整数据 ```json { "name": "company_performance_hk", "arguments": { "ts_code": "09988.HK", "data_type": "balance", "period": "20231231" } } ``` ## 📊 输出特色 ### 利润表 (Income Statement) - 📈 **智能分类**: 收入、成本、盈利、费用、财务、税收等分类显示 - 🔢 **关键指标**: 自动计算毛利率、净利率等关键财务比率 - 📋 **重要性排序**: 按财务科目重要性智能排序 - 📊 **多期对比**: 自动生成趋势分析 ### 资产负债表 (Balance Sheet) - 💰 **三大分类**: 资产、负债、所有者权益分类展示 - 📈 **关键指标**: 资产负债率、股东权益等核心指标 - 🏛️ **结构化显示**: 清晰的财务结构展示 ### 现金流量表 (Cash Flow) - 💼 **四大分类**: 经营活动、投资活动、筹资活动、其他项目 - 💰 **现金流分析**: 经营现金流、自由现金流等关键指标 - 🔄 **流动性评估**: 现金变动净额分析 ## 🌟 技术特色 ### 1. 港股数据适配 - **数据结构优化**: 适配Tushare港股API的键值对数据结构 - **货币格式**: 专门针对港币的金额格式化（万、亿、万亿） - **报告期智能识别**: 自动识别年报、中报、季报 ### 2. 智能数据处理 - **科目分类**: 基于关键词的智能财务科目分类 - **指标计算**: 自动计算关键财务比率和指标 - **多期对比**: 自动生成期间对比和趋势分析 ### 3. 用户体验优化 - **丰富的可视化**: 使用表格、图标等增强可读性 - **详细说明**: 每个报表都包含数据来源和更新说明 - **错误处理**: 完善的错误提示和处理机制 ## 🔗 接口映射 根据[Tushare港股财务数据接口文档](https://tushare.pro/document/2?doc_id=389)： | 数据类型 | 对应接口 | 输出字段 | |---------|---------|---------| | income | hk_income | ts_code, end_date, name, ind_name, ind_value | | balance | hk_balancesheet | ts_code, end_date, name, ind_name, ind_value | | cashflow | hk_cashflow | ts_code, end_date, name, ind_name, ind_value | ## 🚀 集成状态 ✅ **主模块注册**: 已在 `src/index.ts` 中注册 ✅ **工具列表**: 已添加到MCP工具列表 ✅ **请求处理**: 已添加到CallToolRequestSchema处理器 ✅ **编译验证**: TypeScript编译通过 ✅ **格式化器**: 三个主要财务报表格式化器已完成 ## 📝 开发备注 - **权限要求**: 需要Tushare API Token并开通港股数据权限 - **扩展性**: 模块化设计便于后续添加更多港股数据类型 - **一致性**: 与现有A股模块保持接口和风格一致 --- **🎯 作者**: 陈星宇 **📅 创建时间**: 2025年1月 **🔗 基于**: [Tushare港股财务数据API](https://tushare.pro/document/2?doc_id=389)