内容
# AbraFlexi MCP 服务器
<img src="debian/abraflexi-mcp-server.svg" alt="AbraFlexi MCP Server icon" width="96" height="96">
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://badge.fury.io/py/abraflexi-mcp-server)
一个全面的 Model Context Protocol (MCP) 服务器，用于 AbraFlexi 集成，使用 FastMCP 和 python-abraflexi。该服务器通过 MCP 兼容的工具提供对 AbraFlexi REST API 功能的完全访问。
## 功能
共 64 种工具，涵盖 python-abraflexi 暴露的全部 REST 接口：
专为最常见的凭证（发票、联系人、产品、银行交易）设计的专用工具，以及可用于任何 AbraFlexi 凭证的通用 `evidence_*` 工具。
### 📄 发票管理
- `invoice_issued_get` - 检索已发出的发票（faktura-vydana）
- `invoice_issued_create` - 创建新的已发出发票
- `invoice_issued_update` - 更新现有的已发出发票
- `invoice_issued_delete` - 删除已发出的发票
- `invoice_received_get` - 检索已接收的发票（faktura-prijata）
- `invoice_received_create` - 创建新的已接收的发票
### 💳 已发发票业务逻辑
- `invoice_issued_match_payment` - 将发票与付款单据匹配（Párování plateb）
- `invoice_issued_cash_payment` - 以现金支付发票（Hotovostní úhrada）
- `invoice_issued_deduct_advance` - 扣除预付发票（Odpočet záloh a ZDD）
- `invoice_issued_deduct_zdd` - 扣除预付税单，ZDD（Odpočet záloh a ZDD）
- `invoice_issued_link_zdd` - 将 ZDD 链接到收入付款（Vazby ZDD）
- `invoice_issued_unlink_zdd` - 删除 ZDD 绑定（Vazby ZDD）
- `invoice_issued_overdue_days` - 从到期日计算逾期天数（pure，无 API 调用）
- `invoice_issued_get_email` - 解析发票的最佳收件人邮箱
- `invoice_issued_get_recipients` - 解析发票的所有收件人邮箱
### 👥 联系人管理
- `contact_get` - 检索联系人和公司（adresar）
- `contact_create` - 创建新的联系人
- `contact_update` - 更新现有的联系人
- `contact_delete` - 删除联系人
### ☎️ 联系人便捷查询
- `contact_get_notification_email` - 最佳通知邮箱（primary/purpose-matching contact）
- `contact_get_cell_phone` - 使用的手机号码
- `contact_get_any_phone` - 任何可用的电话号码（优先使用移动电话而非座机）
- `contact_get_bank_accounts` - 注册的银行账户（s）用于联系人
### 📦 产品管理
- `product_get` - 从价格列表（cenik）中检索产品
- `product_create` - 创建新产品
- `product_update` - 更新现有产品
- `product_delete` - 删除产品
### 🏦 银行交易管理
- `bank_transaction_get` - 检索银行交易（banka）
- `bank_transaction_create` - 创建新的银行交易
### 🔧 通用凭证操作
- `evidence_get` - 从任何凭证中获取记录（filter、pagination、sorting、relations）
- `evidence_create` - 在任何凭证中创建记录
- `evidence_update` - 更新任何凭证中的记录（支持 `remove_external_ids`）
- `evidence_delete` - 从任何凭证中删除记录
- `evidence_list` - 列出所有可用的凭证
### 🔒 锁定、操作和批量操作
- `evidence_lock` / `evidence_unlock` / `evidence_lock_for_ucetni` - 锁定/解锁记录
- `evidence_storno` - 取消（storno）文档记录
- `evidence_perform_action` - 调用记录的专用业务操作（例如 `pay`）
- `evidence_mass_update` - 更新或操作匹配筛选器的每个记录（Dávkové operace）
- `evidence_batch_insert` / `evidence_batch_update` - 在一次请求中插入/更新多个记录
### 📎 附件
- `evidence_attach_file` - 将本地文件附加到任何记录
- `evidence_list_attachments` - 列出记录的附件
- `evidence_get_attachment` - 获取单个附件的元数据
- `evidence_download_attachment` - 将附件下载到本地文件
- `evidence_get_attachment_thumbnail` - 下载图像附件的缩略图
- `evidence_delete_attachment` - 删除附件
### 🧾 报告、二维码和用户查询
- `evidence_export_report` - 为记录或凭证列表导出 PDF/XLSX 报告
- `evidence_get_qr_code` - 获取文档的付款二维码（文件或 base64 数据 URI）
- `call_user_query` - 调用保存的用户定义查询（uživatelský dotaz）
### ℹ️ 凭证元数据和汇总
- `evidence_get_properties` - 列出凭证支持的字段
- `evidence_get_reports` - 列出凭证可用的可打印报告
- `evidence_get_relations_list` - 列出凭证可用的子凭证（relations）
- `evidence_get_sum` - 获取凭证的汇总（totals）
- `evidence_get_record_changes` - 获取单个记录的变更历史
### 🏷️ 标签（štítky）
- `evidence_get_labels` - 获取分配给记录的标签
- `evidence_set_label` - 添加标签
- `evidence_unset_label` - 删除特定标签（s）
- `evidence_unset_labels` - 删除所有标签
### 🔄 变更 API（公司范围的增量同步）
- `changes_enable` / `changes_disable` - 切换变更跟踪
- `changes_status` - 检查是否启用了变更跟踪
- `changes_get` - 获取自给定版本以来的记录变更
## 安装
### 先决条件
- Python 3.10 或更高版本
- 可以访问启用了 API 的 AbraFlexi 服务器
### 选项 1：从 PyPI 安装（推荐）
```bash
pip install abraflexi-mcp-server
```
然后运行服务器：
```bash
abraflexi-mcp
```
### 选项 2：AppImage（Linux）
从最新版本下载独立的 AppImage：
```bash
chmod +x AbraFlexi-MCP-Server-*-x86_64.AppImage
./AbraFlexi-MCP-Server-*-x86_64.AppImage
```
不需要 Python 或 pip。有关详细信息，请参见 [AppImage](#appimage) 部分。
### 选项 3：从源代码安装
1. **克隆仓库：**
```bash
git clone https://github.com/VitexSoftware/abraflexi-mcp-server.git
cd abraflexi-mcp-server
```
2. **使用 uv 安装（推荐）：**
```bash
uv sync
uv run python scripts/start_server.py
```
或使用 pip：
```bash
pip install -e .
abraflexi-mcp
```
## 云部署
一个测试部署可用于：
**🌐 https://abraflexi.fastmcp.app/mcp**
此云托管实例允许您在无需本地安装的情况下测试和使用 AbraFlexi MCP 服务器。配置您的 MCP 客户端使用 HTTP 传输连接到此端点。
**注意：** 这是一个测试部署。对于生产使用，我们建议使用上述安装方法之一自行托管。
### 配置
创建 `.env` 文件或设置环境变量：
```bash
cp .env.example .env
# 使用您的 AbraFlexi 服务器详细信息编辑 .env
```
## 配置
### 必需环境变量
- `ABRAFLEXI_URL` - 您的 AbraFlexi 服务器 URL（例如，`https://demo.flexibee.eu:5434`）
- `ABRAFLEXI_COMPANY` - 公司标识符（例如，`demo_de`）
### 身份验证（选择一种方法）
**方法 1：用户名/密码（推荐）**
- `ABRAFLEXI_LOGIN` - 您的 AbraFlexi 用户名
- `ABRAFLEXI_PASSWORD` - 您的 AbraFlexi 密码
**方法 2：会话 ID**
- `ABRAFLEXI_AUTHSESSID` - 您的 AbraFlexi 会话 ID
### 可选配置
- `READ_ONLY` - 设置为 `true`、`1` 或 `yes` 以启用只读模式（默认：`true`）
- `ABRAFLEXI_TIMEOUT` - 请求超时（秒）（默认：`300`）
### 传输配置
- `ABRAFLEXI_MCP_TRANSPORT` - 传输类型：`stdio`（默认）或 `streamable-http`
**HTTP 传输配置**（仅在 `ABRAFLEXI_MCP_TRANSPORT=streamable-http` 时使用）：
- `ABRAFLEXI_MCP_HOST` - 服务器主机（默认：`127.0.0.1`）
- `ABRAFLEXI_MCP_PORT` - 服务器端口（默认：`8000`）
- `ABRAFLEXI_MCP_STATELESS_HTTP` - 无状态模式（默认：`false`）
- `AUTH_TYPE` - 必须设置为 `no-auth` 以使用 streamable-http 传输
## 用法
### 运行服务器
**使用启动脚本（推荐）：**
```bash
uv run python scripts/start_server.py
```
**直接执行：**
```bash
uv run python -m abraflexi_mcp_server.server
```
**CLI 帮助：**
```bash
abraflexi-mcp --help
```
### 传输选项
服务器支持两种传输方法：
#### STDIO 传输（默认）
适用于 Claude Desktop 等 MCP 客户端的标准输入/输出传输：
```bash
# 在 .env 或环境中设置
ABRAFLEXI_MCP_TRANSPORT=stdio
```
#### HTTP 传输
适用于 Web 集成的基于 HTTP 的传输：
```bash
# 在 .env 或环境中设置
ABRAFLEXI_MCP_TRANSPORT=streamable-http
ABRAFLEXI_MCP_HOST=127.0.0.1
ABRAFLEXI_MCP_PORT=8000
ABRAFLEXI_MCP_STATELESS_HTTP=false
AUTH_TYPE=no-auth
```
### 测试
**运行测试套件：**
```bash
uv run python scripts/test_server.py
```
### 只读模式
当 `READ_ONLY=true`（默认）时，服务器将仅公开 GET 操作（检索数据）并阻止所有创建、更新和删除操作。这对于：
- 📊 监控仪表板
- 🔍 只读集成
- 🔒 安全敏感环境
- 🛡️ 防止意外修改
要启用写入操作，请在 `.env` 文件中设置 `READ_ONLY=false`。
### 工具调用示例
**获取所有已发出的发票：**
```python
invoice_issued_get(limit=10)
```
**按代码获取特定发票：**
```python
invoice_issued_get(kod="INV-2024-001")
```
**创建新联系人：**
```python
contact_create(
kod="CUSTOMER01",
nazev="Example Company s.r.o.",
email="info@example.com",
tel="+420123456789"
)
```
**获取产品：**
```python
product_get(nazev="Widget", limit=5)
```
**通用凭证查询（带有分页/排序）：**
```python
evidence_get(
evidence="faktura-vydana",
filter_expr="datVyst >= '2024-01-01'",
order="datVyst",
order_direction="D",
limit=20,
start=0
)
```
**将本地文件附加到任何记录：**
```python
evidence_attach_file(evidence="cenik", kod="PRODUCT01", filepath="/path/to/photo.jpg")
```
**锁定发票，然后导出其 PDF：**
```python
evidence_lock(evidence="faktura-vydana", kod="INV-2024-001")
evidence_export_report(
evidence="faktura-vydana",
kod="INV-2024-001",
output_path="/tmp/invoice.pdf",
report_name="dodaciList"
)
```
**批量更新来自供应商的每个价格列表项：**
```python
evidence_mass_update(
evidence="cenik",
filter_expr="dodavatel = 'code:SUPPLIER01'",
data={"stitky": "code:VIP"}
)
```
**通过变更 API 进行增量同步：**
```python
changes_enable()
page = changes_get(start=0, limit=500, evidences=["faktura-vydana"])
# page["changes"], page["next"], page["global_version"]
```
## MCP 集成
该服务器设计用于与 Claude Desktop 等 MCP 兼容的客户端配合使用。有关集成说明，请参见 [MCP_SETUP.md](MCP_SETUP.md)。
## OCI 容器
服务器可以作为 OCI 容器（Docker/Podman）运行 - 主机上不需要 Python 安装。
### 构建镜像
```bash
podman build -t abraflexi-mcp-server -f Containerfile .
```
### 运行容器
镜像默认为端口 **8000** 上的 `streamable-http` 传输。
**使用个别环境变量：**
```bash
podman run --rm -p 8000:8000 \
-e ABRAFLEXI_URL=https://demo.flexibee.eu:5434 \
-e ABRAFLEXI_COMPANY=demo_de \
-e ABRAFLEXI_LOGIN=winstrom \
-e ABRAFLEXI_PASSWORD=winstrom \
abraflexi-mcp-server
```
**使用 env 文件：**
```bash
podman run --rm -p 8000:8000 --env-file .env abraflexi-mcp-server
```
### 容器环境默认值
| 变量 | 默认值 |
|---|---|
| `ABRAFLEXI_MCP_TRANSPORT` | `streamable-http` |
| `ABRAFLEXI_MCP_HOST` | `0.0.0.0` |
| `ABRAFLEXI_MCP_PORT` | `8000` |
| `READ_ONLY` | `true` |
所有其他 [配置变量](#配置) 均可作为环境变量传递。
## AppImage
一个独立的、单一文件的 Linux 可执行文件 - 主机上不需要 Python、pip 或任何其他依赖项。
### 构建 AppImage
```bash
bash appimage/build-appimage.sh
```
脚本会自动下载便携式 CPython 和 `appimagetool`。生成的文件位于 `build/appimage/`：
```
build/appimage/AbraFlexi-MCP-Server-<version>-x86_64.AppImage
```
### 运行 AppImage
AppImage 会自动从当前工作目录加载 `.env` 文件（如果存在）。
**使用 .env 文件（推荐）：**
```bash
cp .env.example .env
# 使用您的凭证编辑 .env
./AbraFlexi-MCP-Server-*-x86_64.AppImage
```
**使用内联环境变量：**
```bash
ABRAFLEXI_URL=https://demo.flexibee.eu:5434 \
ABRAFLEXI_COMPANY=demo_de \
ABRAFLEXI_LOGIN=winstrom \
ABRAFLEXI_PASSWORD=winstrom \
./AbraFlexi-MCP-Server-*-x86_64.AppImage
```
## 开发
### 项目结构
```
abraflexi-mcp-server/
├── abraflexi_mcp_server/
│ ├── __init__.py
│ └── server.py # 主要服务器实现
├── appimage/
│ ├── AppRun # AppImage 入口点
│ ├── abraflexi-mcp-server.desktop
│ ├── abraflexi-mcp-server.svg
│ └── build-appimage.sh # AppImage 构建脚本
├── debian/ # Debian 打包
│ ├── abraflexi-mcp-server.svg # AppStream 库存图标
│ ├── abraflexi-mcp-server.install
│ └── cz.vitexsoftware.abraflexi-mcp-server.metainfo.xml
├── scripts/
│ ├── start_server.py # 带有验证的启动脚本
│ └── test_server.py # 测试脚本
├── Containerfile # OCI 容器构建
├── server.json # MCP 注册表清单
├── pyproject.toml # Python 项目配置
├── setup.py # 旧 setuptools 配置
├── requirements.txt # 依赖项
├── .env.example # 环境配置模板
├── .env # 您的配置（不在 git 中）
├── .gitignore # Git 忽略模式
└── README.md # 此文件
```
### 运行测试
```bash
# 测试服务器功能
uv run python scripts/test_server.py
# 使用特定环境进行测试
ABRAFLEXI_URL=https://your-server.com uv run python scripts/test_server.py
```
## 错误处理
服务器包括全面的错误处理：
- ✅ 认证错误会被明确报告
- 🔒 只读模式违规会被阻止，并附有描述性消息
- ✔️ 无效参数会被验证
- 🌐 网络和 API 错误会被正确格式化
- 📝 用于故障排除的详细日志记录
## 安全考虑
- 🔑 在 `.env` 文件中安全存储凭证（不要提交到 git）
- 🔒 启用只读模式以实现仅监视的使用场景
- 🛡️ 使用 HTTPS 连接到 AbraFlexi 服务器
- 🔄 定期轮换密码
- 📁 确保 `.env` 文件具有适当的权限（600）
## 故障排除
### 常见问题
**连接失败：**
- 验证 `ABRAFLEXI_URL` 是否正确且可访问
- 检查身份验证凭证
- 确保启用了 AbraFlexi API
- 检查防火墙/网络设置
**权限被拒绝：**
- 验证用户是否具有足够的 AbraFlexi 权限
- 检查是否在尝试修改数据时启用了只读模式
**找不到工具：**
- 确保所有依赖项都已安装：`uv sync`
- 验证 Python 版本兼容性（3.10+）
### 调试模式
设置环境变量以获取详细日志记录：
```bash
export DEBUG=1
uv run python scripts/start_server.py
```
## 依赖项
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP 服务器框架
- [python-abraflexi](https://github.com/VitexSoftware/python-abraflexi) - AbraFlexi Python 库
- [python-dotenv](https://github.com/theskumar/python-dotenv) - 环境变量管理
## 许可证
该项目在 MIT 许可证下获得许可。
## 致谢
- [AbraFlexi](https://www.abraflexi.eu/) 适用于会计平台
- [模型上下文协议](https://modelcontextprotocol.io/) 适用于集成标准
- [FastMCP](https://github.com/jlowin/fastmcp) 适用于服务器框架
## 支持
- 📖 [文档](README.md)
- 🐛 [问题跟踪器](https://github.com/VitexSoftware/abraflexi-mcp-server/issues)
- 💬 [AbraFlexi API 文档](https://podpora.flexibee.eu/cs/?q=API)
## 作者
**Vítězslav Dvořák**
- 邮箱：info@vitexsoftware.cz
- GitHub：[@VitexSoftware](https://github.com/VitexSoftware)
---
**用 ❤️ 为 AbraFlexi 和 MCP 社区制作**
<!-- mcp-name: io.github.Vitexus/abraflexi -->
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器