使用说明

利润-财务分析和税务预测

一个混合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 dev

MCP连接失败

看 QUICK_FIX_MCP.md

🧪 税务计算明细

支持的纳税年度

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