互联网平台劳务报酬个税计算器 API
npm install tax-calculator-api3bash
克隆项目
git clone https://github.com/pengbo518/tax-calculator-mcp.git
cd tax-calculator-mcp
安装依赖
npm install
配置环境变量
cp env.example .env
开发环境运行
npm run dev
生产环境运行
npm start
`
$3
访问健康检查接口确认服务正常运行：
`bash
curl http://localhost:3000/health
`
📋 API 接口文档
$3
#### POST /api/tax/calculate
计算个税
请求体：
`json
{
"monthlyIncomes": [10000, 12000, 0, 15000, 0, 0, 18000, 20000, 0, 0, 0, 0]
}
`
参数说明：
- monthlyIncomes: 月收入数组，支持1-12个元素
- 数组长度对应月份：[10000] = 1月收入10000，其他月份为0
- 自动补全：不足12个月的数组会自动补全到12个月，未传月份默认为0
- 支持不连续月份：[200, 0, 300, 0] = 1月200，2月0，3月300，4月0，5-12月为0
响应示例：
`json
{
"success": true,
"message": "个税计算成功",
"data": {
"monthlyResults": [
{
"month": 1,
"income": 10000,
"totalIncome": 10000,
"totalFee": 2000,
"totalDeduction": 5000,
"taxableAmount": 3000,
"rate": 0.03,
"deduct": 0,
"tax": 90,
"afterTaxIncome": 9910,
"prevTaxPaid": 0,
"taxBurden": 0.9
}
],
"summary": {
"totalIncome": 75000,
"totalTax": 4500,
"totalAfterTax": 70500,
"totalTaxBurden": 6.0
}
}
}
`
#### GET /api/tax/rates
获取税率表
#### GET /api/tax/policy
获取个税政策信息
#### POST /api/tax/flexible-income
批量设置灵活就业收入
$3
#### GET /api/mcp
获取 MCP 插件信息
#### POST /api/mcp/calculate
MCP 个税计算接口
#### GET /api/mcp/rates
MCP 税率表接口
#### GET /api/mcp/policy
MCP 政策信息接口
#### POST /api/mcp/batch-calculate
MCP 批量计算接口
💡 使用示例
$3
`javascript
const response = await fetch('http://localhost:3000/api/tax/calculate', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
monthlyIncomes: [10000, 12000, 0, 15000, 0, 0, 18000, 20000, 0, 0, 0, 0]
})
});
const result = await response.json();
console.log(result.data.summary);
`
$3
`javascript
// 示例1: 只有1月份收入
const response1 = await fetch('http://localhost:3000/api/mcp/calculate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
monthlyIncomes: [10000] // 1月收入10000，2-12月默认为0
})
});
// 示例2: 前两个月收入
const response2 = await fetch('http://localhost:3000/api/mcp/calculate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
monthlyIncomes: [20000, 30000] // 1月20000，2月30000，3-12月默认为0
})
});
// 示例3: 不连续月份收入
const response3 = await fetch('http://localhost:3000/api/mcp/calculate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
monthlyIncomes: [200, 0, 300, 0] // 1月200，2月0，3月300，4月0，5-12月默认为0
})
});
`
$3
`javascript
const response = await fetch('http://localhost:3000/api/mcp/batch-calculate', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
calculations: [
{
name: '方案A',
monthlyIncomes: [10000, 12000, 0, 15000, 0, 0, 18000, 20000, 0, 0, 0, 0]
},
{
name: '方案B',
monthlyIncomes: [15000, 15000, 15000, 15000, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
name: '方案C',
monthlyIncomes: [20000, 30000]
},
{
name: '方案D',
monthlyIncomes: [50000]
}
]
})
});
const result = await response.json();
console.log(result.results);
`
⚙️ 配置说明
$3
复制 env.example 为 .env 并配置以下变量：
`bash
服务器配置
PORT=3000
NODE_ENV=development
跨域配置
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
日志配置
LOG_LEVEL=info
安全配置
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100
`
$3
- 每个 IP 15 分钟内最多 100 个请求
- 请求体大小限制 1MB
- 支持自定义限制配置
🧪 测试
$3
`bash
运行所有测试
npm test
运行 API 测试
npm run test:api
运行优化测试
npm run test:optimized
运行快速测试
npm run quick-test
`
$3
`bash
调试 MCP 功能
npm run debug:mcp
`
📁 项目结构
`
tax-calculator-mcp/
├── src/
│ ├── index.js # 服务器入口文件
│ ├── routes/ # 路由文件
│ │ ├── taxCalculator.js # 个税计算路由
│ │ └── mcp.js # MCP 插件路由
│ ├── services/ # 业务逻辑层
│ │ └── taxCalculator.js # 个税计算服务
│ ├── middleware/ # 中间件
│ │ └── errorHandler.js # 错误处理中间件
│ └── utils/ # 工具函数
│ └── logger.js # 日志工具
├── tests/ # 测试文件
│ └── taxCalculator.test.js
├── debug-mcp.js # MCP 调试脚本
├── env.example # 环境变量示例
├── package.json
└── README.md
`
🔒 安全特性
- CORS 保护：配置允许的跨域来源
- 请求限制：防止 API 滥用和 DDoS 攻击
- 输入验证：完整的参数验证和类型检查
- 安全头：使用 Helmet 设置安全头
- 错误处理：统一的错误响应格式，避免信息泄露
- 日志记录：完整的请求日志和错误追踪
📈 性能优化
- 高精度计算：使用 Decimal.js 避免浮点数精度问题
- 内存优化：合理的数据结构和算法设计
- 响应缓存：税率表等静态数据缓存
- 错误恢复：优雅的错误处理和恢复机制
- 并发处理：支持高并发请求处理
🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
$3
1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature`)