利润-财务分析和税务预测
一个混合Python应用程序，通过两者提供财务分析和税务预测工具 HTTP API 和 模型上下文协议（MCP） 接口。
______________________________________________________________________
🎯 特性
- 退税预测 -根据工资存根数据计算联邦所得税预测
- 多年支持 -2024年、2025年和2026年美国国税局税级
- 自动纳税年度检测 -根据报税季节使用适当的纳税年度
- 双接口 -通过HTTP API或Claude Desktop（MCP）访问
- 综合录井 -调试和监控的详细日志
______________________________________________________________________
🚀 快速开始
先决条件
- Python 3.13+
- 紫外线 包管理器
安装
# Clone the repository
cd /path/to/profit
# Install dependencies
uv pip install -e .______________________________________________________________________
💻 HTTP API
启动开发服务器
# Recommended: Using make
make dev
# Alternative: Using shell script
./dev.sh
# Manual
uv run python -m profit.servers.http_server访问权限：
- APIhttp://localhost:8000
- 交互式文档：http://localhost:8000/docs
- 重新记录：http://localhost:8000/redoc
热重载
当您对中的任何文件进行更改时，开发服务器会自动重新加载 src/profit/无需手动重启！
API调用示例
curl -X POST http://localhost:8000/api/project-tax-refund \
-H "Content-Type: application/json" \
-d '{
"gross_pay": 3000.00,
"federal_tax_withheld": 450.00,
"pay_period_start": "2024-10-01",
"pay_period_end": "2024-10-15",
"pay_frequency": "biweekly",
"filing_status": "single"
}'______________________________________________________________________
🔌 MCP服务器（克劳德桌面）
设置
- 更新Claude桌面配置
打开： ~/Library/Application Support/Claude/claude_desktop_config.json
添加：
{
"mcpServers": {
"profit": {
"command": "uv",
"args": [
"--directory",
"/Users/austin/Desktop/Projects/profit-mcp/profit",
"run",
"profit-mcp"
]
}
}
}⚠️ 重要提示： 更新路径以匹配您的实际项目位置！
- 重新启动克劳德桌面
- 完全退出（Cmd+Q） - 重新开放 - 寻找🔌 icon-应连接“利润”
- 测试IT
问克劳德：
> “我有一张工资单，总工资为3000美元，联邦预扣税款为450美元，工资期为10月1日至15日，每两周一次。我是单身。请出示我的退税单。”
可用工具
project_tax_refund
根据工资存根数据计算联邦退税预测。
参数：
gross_pay-发薪期总收入federal_tax_withheld-联邦预扣税款pay_period_start-开始日期（YYYY-MM-DD）pay_period_end-结束日期（YYYY-MM-DD）pay_frequency-每周、每两周、半月、每月filing_status-单身、已婚、分居、户主
看 MCP_SETUP.md 有关详细的设置说明。
______________________________________________________________________
📂 项目结构
profit/
├── src/profit/ # Main application package
│ ├── models/ # Data models (Pydantic)
│ │ └── paystub.py
│ ├── finance/ # Financial calculations
│ │ └── projections.py
│ ├── tax/ # Tax calculations
│ │ ├── calculators/ # Tax calculation logic
│ │ │ └── federal_income_tax.py
│ │ └── data/ # Tax tables and brackets
│ │ └── federal_brackets.py
│ └── servers/ # Server implementations
│ ├── http_server.py # FastAPI HTTP server
│ └── mcp_server.py # MCP server for Claude Desktop
├── tests/ # Test suite
├── Makefile # Development commands
├── dev.sh # Dev server script
└── pyproject.toml # Project configuration______________________________________________________________________
🛠️ 发展
命令
make dev # Start HTTP API with hot reload
make clean # Clean Python cache
make kill-server # Free port 8000
make test # Run tests
make install # Install dependencies开发工作流程
- 启动服务器：
make dev - 编辑代码： 对中的文件进行更改
src/profit/ - 自动重新加载： 服务器检测更改并自动重新加载
- 测试： 变化立即生效
常见问题
“地址已在使用中”
make kill-server
make dev缓存问题
make clean
make devMCP连接失败
______________________________________________________________________
🧪 税务计算明细
支持的纳税年度
- 2024 -美国国税局税级和标准扣除额
- 2025 -更新了带有通货膨胀调整的括号
- 2026 -投影括号（可能会更改）
自动纳税年度选择
系统会自动选择相应的纳税年度：
- 4月15日前：使用前一年（归档季节）
- 4月15日之后：使用当前年份（计划季节）
计算 方法
- 使用美国国税局第17号出版物第16行工作表
- 累进税级（每个申报状态7个级）
- 标准扣除额（不逐项扣除）
- 根据支付频率对收入进行年度化
支持的归档状态
- 单
- 夫妻合并申报
- 已婚分报
- 户主
______________________________________________________________________
📊 输出示例
Tax Refund Projection Analysis (2025)
============================================================
PAYSTUB DATA:
- Gross Pay: $3,000.00
- Federal Tax Withheld: $450.00
- Pay Period: 2024-10-01 to 2024-10-15 (15 days)
- Pay Frequency: Biweekly
- Filing Status: Single
ANNUALIZED PROJECTIONS:
- Pay Periods Per Year: 26
- Annualized Gross Income: $78,000.00
- Annualized Federal Withholding: $11,700.00
- Current Withholding Rate: 15.00%
TAX CALCULATION (2025 IRS):
- Standard Deduction: $15,000.00
- Taxable Income: $63,000.00
- Federal Tax Owed: $8,774.00
- Tax Bracket: $48,475 - $103,350
- Marginal Tax Rate: 22.0%
- Effective Tax Rate: 11.25%
============================================================
PROJECTED REFUND: $2,926.00
============================================================______________________________________________________________________
📚 文档
- QUICK_FIX_MCP.md -修复MCP连接问题
- MCP_SETUP.md -完整的MCP设置指南
- 测试_HOT_RELOAD.md -验证热重新加载是否正常工作
______________________________________________________________________
🔐 安全与隐私
- 没有数据持久性-计算是无状态的
- 没有外部API调用-所有计算都在本地完成
- 不记录敏感财务数据
- 仅适用于本地/私人部署
______________________________________________________________________
🤝 贡献
本项目使用：
- 快速API 用于HTTP API
- FastMCP 用于模型上下文协议
- 派丹蒂克 用于数据验证
- 优维康 ASGI服务器
- 紫外线 用于包管理
______________________________________________________________________
📝 许可证
\[在此处添加您的许可证\]
______________________________________________________________________
🆘 支持
有问题吗？
- HTTP API问题：请参阅README中的开发故障排除
- MCP问题：参见 QUICK_FIX_MCP.md
- 缓存问题：运行
make clean - 港口问题：运行
make kill-server
______________________________________________________________________
🎯 路线图
- \[\]州税计算
- \[\]额外税收抵免（EITC、CTC等）
- \[\]自雇税
- \[\]季度预估税计算器
- \[\]PDF付款存根解析
- \[\]多种工作场景
- \[\]历史纳税年度比较
______________________________________________________________________
内置❤️ 使用FastAPI、FastMCP和Python