内容
# mfmcp
**v0.1.0** · MIT 许可证 · Python 3.11+ · Linux / macOS / Windows
**您的整个印度共同基金投资组合（每家资产管理公司，每个投资组合）都在您自己的机器上进行分析，配备或不配备 AI 助手。**
`mfmcp` 读取您的 **综合账户对账单（CAS）** PDF，丰富它以获取实时净值，并为您提供三种使用分析结果的方式：
1. **命令行报告**：一个命令，一个完整的文本报告在您的终端中。不需要 AI。
2. **交互式仪表盘**：一个本地网页，包含增长图表、税务规划、SIP/STP 检测等。不需要 AI（可选的聊天面板使用 Claude，如果您有的话）。
3. **MCP 服务器**：23 个工具，任何 AI 代理（Claude Desktop，Claude Code，Cursor，...）都可以通过自然语言调用："我的 XIRR 是多少？今年我可以无税收获多少长期资本利得？"
所有操作都在本地运行。您的对账单永远不会上传到任何地方。
## 它分析什么
- **收益**：投资组合和每只基金的 XIRR，根据您的实际现金流，绝对收益，1/3/5 年滚动收益率
- **基准阿尔法**：您的实际存款/取款重新投入到一个 Nifty 50 指数基金，回答：您的基金选择是否优于购买指数？
- **税务规划器**：已实现/未实现的短期资本利得和长期资本利得（FIFO），本财年的 ₹1.25L 股权长期资本利得豁免额度，损失抵消候选者，以及一个持有时间表，显示何时持有变成长期
- **资产配置**：按资产类别、市值（大盘/中盘/小盘...）、资产管理公司和类别划分，并附有集中度标志
- **SIP 和 STP**：从交易历史中检测系统性投资和基金间转移计划，包括已停止/暂停的计划
- **成本和卫生**：定期计划费用拖累与直接计划，同一子类别下的重叠基金，闲置赎回
- **风险**：每只基金的波动性和最大回撤
- **健康检查**：一个调用，运行所有检查并返回优先事项
## 为什么使用 CAS 而不是经纪人 API？
一个 CAS 涵盖 **每个** 资产管理公司和注册转让代理，免费提供一份对账单：通过任何平台、直接与资产管理公司或持有非流通股的账户购买的基金。经纪人集成只能看到您在该经纪人处购买的基金。
---
## 安装
需要 Python 3.11+。使用 [uv](https://docs.astral.sh/uv/)（推荐）：
```bash
git clone https://github.com/YashasviAsthana/mfmcp.git
cd mfmcp
uv sync # 创建虚拟环境并安装依赖
uv tool install --editable . # 可选：全局 `mfmcp` 命令
```
或使用普通 pip：
```bash
pip install -e .
```
验证：`mfmcp --version`（或 `uv run mfmcp --version`）。
## 步骤 1：获取您的 CAS
```bash
mfmcp fetch
```
这将在您的浏览器中打开 CAMS CAS 页面并打印步骤。请求 **详细** 的 "CAS - CAMS + KFintech" 对账单 **从您的最早投资日期** （需要完整历史记录的生命周期数据），设置 PDF 密码并下载电子邮件附件。`mfmcp` 监视您的下载文件夹，验证 PDF 并归档：无需手动文件处理。
> MF Central 自己的“详细报告”下载使用不同的 PDF 格式，尚不可解析；请使用 CAMS 路线。完整的操作指南：`docs/getting-your-cas.md`。
## 步骤 2：存储密码（一次）
将您的 CAS PDF 密码放入项目目录中的 `.env` 文件（gitignored）：
```bash
echo "MFMCP_CAS_PASSWORD=your-password" > .env
```
或在您的环境中导出 `MFMCP_CAS_PASSWORD`。之后，任何命令或 AI 工具都不需要密码：它不再出现在提示、代理对话和 shell 历史记录中。
## 步骤 3：使用它
### A. 终端报告（不需要 AI）
```bash
mfmcp analyze
```
打印完整报告：摘要，按基金分组的持有量，XIRR，资产配置，集中度标志和资本利得。
### B. 交互式仪表盘（不需要 AI）
```bash
mfmcp dashboard
```
在 `127.0.0.1`（仅限本地）上提供一个自包含的页面：摘要瓷砖，优先 **健康检查**，交互式 **增长图表**（将鼠标悬停在任何日期，1Y/3Y/All 范围），**基准卡片**，可悬停的资产配置圆环图（资产类别/市值/资产管理公司），以及“持有量”，“税务规划器”，“LTCG 日历”，“SIP 和 STP”，“重叠和成本”，“风险和收益”等的选项卡。每个表格都按任意列排序。
仪表盘包括一个可选的 **聊天面板**（“哪只基金拖累了我的收益？”），由本地沙盒 [Claude Code](https://claude.com/claude-code) 会话支持：
- 需要安装 `claude` 命令行工具；如果没有，请使用 `--no-chat`（其他功能都可以使用）。
- 沙盒通过工具拒绝列表隔离：聊天不能运行命令或触摸您的文件系统。
- 它可以研究基金事实的网络；禁用 `--no-web`。
- 您的（已清除个人身份信息）投资组合数据在聊天时发送到模型；`--no-chat` 完全避免这种情况。
### C. MCP 服务器（用于 AI 代理）
`mfmcp`（或 `mfmcp serve`）在标准输入/输出上运行一个标准的 MCP 服务器。
**Claude Code**（从项目目录）：
```bash
claude mcp add mfmcp --scope local -- mfmcp serve
```
**Claude Desktop**：添加到 `claude_desktop_config.json`
（macOS：`~/Library/Application Support/Claude/`，Windows：`%APPDATA%\Claude\`）：
```json
{
"mcpServers": {
"mfmcp": {
"command": "mfmcp",
"args": ["serve"],
"env": { "MFMCP_CAS_PASSWORD": "your-password" }
}
}
}
```
其他客户端（Cursor 等）：任何标准输入/输出 MCP 客户端配置都适用：参见 `docs/mcp-clients.md`。然后直接对话：
```
Load my CAS at ~/.mfmcp/statements/<file>.pdf
Run a health check. Am I beating the Nifty 50?
How much LTCG can I harvest tax-free this FY? Any stopped SIPs or STPs?
```
## MCP 工具
| 工具 | 返回内容 |
| --- | --- |
| `open_cas_portal(portal)` | 在浏览器中打开 CAS 门户；返回要遵循的步骤。 |
| `import_downloaded_cas(password, timeout)` | 等待下载的 CAS PDF，然后加载它。 |
| `load_cas(path, password)` | 解析 CAS PDF 并加载它（返回摘要，无个人身份信息）。 |
| `health_check(live, include_benchmark)` | 一次调用自动分析：优先事项。 |
| `portfolio_summary(live)` | 投资，当前价值，绝对回报，投资组合 XIRR。 |
| `list_holdings(include_zero, live)` | 每只基金的单位，成本，价值，收益，XIRR。 |
| `portfolio_xirr(live)` / `scheme_xirr(scheme, live)` | 资金加权年化回报。 |
| `allocation(by, live)` | 按 `category`，`amc`，`asset_class` 或 `market_cap` 划分的权重。 |
| `concentration_report(live)` | 单一计划/资产管理公司/类别的超额暴露标志。 |
| `capital_gains(fy, method, live)` | 已实现 + 未实现的短期资本利得/长期资本利得（FIFO 工作表）。 |
| `tax_harvesting(live)` | 本财年的股权长期资本利得豁免额和损失抵消候选者。 |
| `ltcg_calendar()` | 每个开放批次何时转为长期（12 个月股权 / 36 个月其他）。 |
| `sip_analysis(live)` | 检测到的 SIP：状态，节奏，平均分期付款，SIP XIRR。 |
| `stp_analysis()` | 检测到的 STP：基金间转移路线，状态，跳过月份。 |
| `overlap_report(live)` | 相同子类别下的重叠基金；定期计划费用拖累。 |
| `idle_money()` | 从未再投资的赎回/付款。 |
| `benchmark_comparison(benchmark_amfi_code, live)` | 您的现金流重新投入到基准指数基金；阿尔法。 |
| `portfolio_growth(step_days)` | 投资组合价值 + 累积投资随时间变化。 |
| `performance_stats(scheme)` | 1/3/5 年滚动收益率，波动性，最大回撤。 |
| `nav_lookup(scheme)` / `nav_history(scheme, from, to)` | 最新/历史净值。 |
| `list_transactions(scheme)` | 选择加入原始交易转储以获取某只基金。 |
`live=True`（默认）使用来自 mfapi.in 的实时净值，并优雅地降级为对账单自己的估值（离线时，并附有说明）。
## 隐私
- 您的 CAS PDF 和解析数据从未离开您的机器；没有托管后端。
- 工具和仪表盘输出是汇总数字，投资者的个人身份信息（姓名，PAN，投资组合编号）已被删除；逐行交易在明确选择加入的工具后面。
- 什么 **离开**：工具调用的结果发送到您连接的代理/模型，可选的聊天面板将清除个人身份信息的投资组合数据发送到 `claude` 命令行工具。跳过 MCP/聊天，完全不会与任何模型共享任何内容。
- 实时净值来自公共端点（mfapi.in，AMFI），仅由公共计划代码键控。
## 架构
```
CAS PDF -> [ingestion] casparser -> 标准化投资组合模型
-> [enrichment] AMFI/ISIN -> 实时 + 历史净值（缓存在磁盘上）
-> [analysis] 纯函数：XIRR，收益，税务，SIP/STP，风险，健康检查
-> [server] FastMCP 工具通过标准输入/输出 -> 任何代理
-> [dashboard] 自包含 HTML + 本地聊天后端
```
分析核心（`mfmcp.analysis`）是纯粹的，从未导入 casparser 或 MCP SDK，因此它也是一个普通的 Python 库。使用 `uv run pytest` 运行测试套件（离线，无需真实数据）。
## 不是财务或税务建议
所有输出：特别是资本利得和税收收获工作表：存在以帮助您了解您的投资组合，**不是** 作为已准备好的税务建议。持有期规则已简化，特殊情况未建模。请与合格的顾问核实任何重要的内容。
## 许可证
[MIT](LICENSE)。所有依赖项都是许可的，包括 PDF 后端（PDFium：BSD/Apache）。
## 更新日志
**v0.1.0**（2026-07-14）：第一个版本：CAS 提取（CAMS/KFintech 详细），实时净值增强，XIRR/收益/资产配置/集中度分析，税务规划器 + LTCG 日历，SIP 和 STP 检测，基准阿尔法，增长时间序列，风险统计，健康检查，23 个 MCP 工具，交互式仪表盘，带有可选沙盒聊天的辅助 CAS 提取。
