inFakt MCP服务器
语言: 英语 | 波尔斯基(波兰语)
用于inFakt API的模型上下文协议(MCP)服务器-一个全面的波兰发票和会计服务。
概述
此MCP服务器提供与inFakt的REST API的无缝集成,使Claude等人工智能助手能够与您的inFakt帐户进行交互:
- 发票管理 -创建、读取、更新和删除增值税发票、更正发票和其他文档类型
- 客户管理 -管理客户数据库
- 产品管理 -维护产品/服务目录
- 成本跟踪 -访问费用文档
- 参考数据 -查询增值税税率、银行账户和其他配置数据
特性
- 发票、客户和产品的完整CRUD操作
- 异步发票创建与状态跟踪
- PDF生成和电子邮件传递
- 高级过滤、分页和排序
- 支持生产环境和沙盒环境
- 全面的错误处理
先决条件
- Node.js 18或更高版本
- inFakt帐户(生产或沙盒)
- inFakt API密钥
安装
- 克隆此存储库:```bash
git clone
cd infakt-mcp
2. 安装依赖项:```bash
npm install
- 构建项目:```bash
npm run build
## 配置
### 获取API密钥
#### 生产环境:
1. 登录 事实上
1. 导航到“设置”→ 其他选项→ API
1. 生成具有所需作用域的新API密钥
#### 沙盒环境:
1. 注册地址: 实际 沙箱
1. 导航到“设置”→ API
1. 生成测试API密钥
### 环境变量
创建一个 `.env` 文件或设置以下环境变量:```bash
# Required
INFAKT_API_KEY=your_api_key_here
# Optional
INFAKT_USE_SANDBOX=true # Set to 'true' for sandbox, omit or 'false' for production
INFAKT_BASE_URL=https://api.infakt.pl/api/v3 # Custom base URL (optional)
MCP客户端配置
对于Claude Desktop:
添加到您的 claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: `%APPDATA%\Claude\claude_desktop_config.json````json
{
"mcpServers": {
"infakt": {
"command": "node",
"args": ["/absolute/path/to/infakt-mcp/dist/index.js"],
"env": {
"INFAKT_API_KEY": "your_api_key_here",
"INFAKT_USE_SANDBOX": "false"
}
}
}
}
#### 对于其他MCP客户:
根据客户的文档进行配置,确保:
- 命令: `node dist/index.js`
- 环境变量设置正确
- 工作目录设置为项目根目录
## 可用工具
### 发票管理
#### `infakt_create_invoice`
异步创建新的增值税发票。
**参数:**
- `client_company_name` (必填):客户公司名称
- `payment_method` (必填):现金、转账、卡等。
- `services` (必填):一系列服务/产品
- `status`:草稿(默认)、已支付或打印
- `client_id`:使用现有客户端
- 新客户端的客户端详细信息(first_name、last_name、tax_code等)
- 其他字段:备注、发票日期、销售日期、付款日期等。
**退货:** 用于状态检查的任务参考号
#### `infakt_check_invoice_status`
检查异步创建的发票的状态。
**参数:**
- `task_reference_number` (必填):来自create_invoice的参考号
#### `infakt_list_invoices`
列出所有具有过滤和分页功能的发票。
**参数:**
- `offset`:分页偏移
- `limit`:每页结果(最多100个)
- `order`:排序顺序(例如,“invoice_date desc”)
- `number`:按发票号筛选
- `client_company_name`:按客户端名称筛选
- `status`:按状态筛选
- `invoice_date_from`, `invoice_date_to`:日期范围筛选器
- `fields`:要返回的逗号分隔字段
#### `infakt_get_invoice`
获取特定发票的详细信息。
**参数:**
- `invoice_uuid` (必填):发票UUID
- `fields`:可选字段选择
#### `infakt_update_invoice`
更新现有发票(仅草稿)。
**参数:**
- `invoice_uuid` (必填):发票UUID
- 要更新的字段(客户公司名称、付款方式、服务等)
#### `infakt_delete_invoice`
删除发票(仅限草稿)。
**参数:**
- `invoice_uuid` (必填):发票UUID
#### `infakt_download_invoice_pdf`
下载PDF格式的发票(base64编码)。
**参数:**
- `invoice_uuid` (必填):发票UUID
- `document_type`:原件、副本、复印件等。
- `locale`:pl、en或pe
#### `infakt_send_invoice_email`
通过电子邮件发送发票。
**参数:**
- `invoice_uuid` (必填):发票UUID
- `recipient_email`:自定义收件人(默认使用客户端电子邮件)
- `email_subject`:自定义主题
- `email_message`:自定义消息
#### `infakt_mark_invoice_paid`
将发票标记为已付款。
**参数:**
- `invoice_uuid` (必填):发票UUID
- `paid_date` (必填):付款日期(YYYY-MM-DD)
### 客户管理
#### `infakt_list_clients`
列出所有具有筛选功能的客户端。
#### `infakt_get_client`
按ID获取客户详细信息。
#### `infakt_create_client`
创建新客户端。
#### `infakt_update_client`
更新现有客户端。
#### `infakt_delete_client`
删除客户端。
### 产品管理
#### `infakt_list_products`
列出所有经过筛选的产品。
#### `infakt_get_product`
按ID获取产品详细信息。
#### `infakt_create_product`
创建新产品。
#### `infakt_update_product`
更新现有产品。
#### `infakt_delete_product`
删除产品。
### 参考数据
#### `infakt_get_vat_rates`
获取可用的增值税税率。
#### `infakt_get_bank_accounts`
获取已配置的银行账户。
#### `infakt_get_account_info`
获取帐户信息和限制。
### 成本管理
#### `infakt_list_costs`
列出成本文件。
#### `infakt_get_cost`
获取成本文档详细信息。
## 用法示例
### 示例1:创建发票```
Create a new invoice for client "ACME Corp" with:
- Payment method: bank transfer
- One service: "Website Development" for 5000 PLN net with 23% VAT
- Client tax code: 1234567890
- Client address: ul. Główna 1, 00-001 Warsaw, Poland
MCP服务器将:
- 异步创建发票
- 返回任务参考号
- 然后,您可以检查状态并检索发票UUID
示例2:列出最近的发票```
List the last 10 invoices from December 2024, sorted by date descending
### 示例3:通过电子邮件发送发票```
Send invoice via email to client
示例4:生成PDF```
Download PDF for invoice in Polish language
## API范围要求
对于要执行的操作,API键必须具有适当的作用域:
- `api:invoices:read` -阅读发票、客户、产品
- `api:invoices:write` -创建/更新/删除发票、客户、产品
- `api:costs:read` -阅读成本文件
- `api:costs:write` -管理成本
- `api:accounting:read` -读取会计数据
- `api:accounting:write` -管理会计操作
- `api:sensitive:bank_accounts:write` -管理银行账户
## 速率限制
inFakt API有以下费率限制:
- GET请求:每个IP每60秒300个请求
- 其他方法:每个IP每60秒150个请求
- 发票电子邮件发送:3000/天(付费账户),20/天(免费账户)
## 发展
### 以开发模式运行```bash
npm run dev
构建```bash
npm run build
### 观看模式```bash
npm run watch
测试
使用沙盒环境
集 INFAKT_USE_SANDBOX=true 要使用测试环境:
- 未创建真实发票
- 安全测试集成
- 限额:每月2500张发票
故障排除
身份验证错误(401)
- 验证您的API密钥是否正确
- 检查密钥是否具有所需的作用域
- 确保密钥未过期
需要付款(402)
- 您的计划不支持API访问或已超出文档限制
- 升级您的计划 事实上
速率限制错误(429)
- 请稍候,然后重试
- 实施指数回退
- 考虑缓存响应
验证错误(422)
- 检查是否提供了必填字段
- 验证数据格式(日期为YYYY-MM-DD,有效的增值税税率等)
- 查看响应中的错误消息
资源
- inFakt API文档
- inFakt网站
- 模型上下文协议文档
- MCP规范
许可证
麻省理工学院
支持
有关API问题,请联系inFakt支持,网址: pomoc@infakt.pl
对于MCP服务器问题,请在此存储库中打开问题。
