AbraFlexi

AbraFlexi MCP 服务

这是一个功能全面的 Model Context Protocol（MCP）服务，使用 FastMCP 和 python-abraflexi 集成 AbraFlexi。该服务通过兼容 MCP 的工具，完整提供 AbraFlexi REST API 的功能。

功能

共 69 个工具，涵盖 python-abraflexi 提供的完整 REST 接口： 为最常用的业务记录（发票、联系人、产品、银行交易）提供专用工具， 另有通用的 evidence_* 工具，可用于任意名称的 AbraFlexi 业务记录。

一个服务进程对应一家 AbraFlexi 公司。 运行中的服务在其整个生命周期内 都绑定到单家公司，该公司通过 ABRAFLEXI_URL/ABRAFLEXI_COMPANY 设置（参见配置）。 任何工具返回的记录都已属于该公司——无法通过此服务查询其他公司的数据。调用 server_info 可查看运行中的服务绑定到哪家公司/URL；主要的记录获取工具（invoice_issued_get、invoice_received_get、 contact_get、product_get、bank_transaction_get、evidence_get、 changes_get）也会在每个响应的 _context 块中返回这些信息， 并附带说明记录中任何交易对方字段的注释 （例如，发票的 nazFirmy 是客户/供应商，而不是开具/接收该发票的公司）。

ℹ️ 服务身份

• server_info - 报告此服务会话绑定到哪家 AbraFlexi 公司/URL

📄 发票管理

• 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 - 根据到期日计算逾期天数（纯计算，不调用 API）
• invoice_issued_get_email - 确定发票的最佳收件人邮箱
• invoice_issued_get_recipients - 获取发票的所有收件人邮箱

🏢 公司管理

• company_create - 创建全新的 AbraFlexi 公司（会计单位）——需要服务管理员/许可证的 REST 权限

👥 联系人管理

• contact_get - 获取联系人和公司（adresar）
• contact_create - 创建新联系人
• contact_update - 更新现有联系人
• contact_delete - 删除联系人

☎️ 联系人便捷查询

• contact_get_notification_email - 最适合通知的电子邮箱（主要联系人／用途匹配的联系人）
• contact_get_cell_phone - 可使用的手机号码
• contact_get_any_phone - 任意可用的电话号码（优先使用手机号码，而非固定电话）
• contact_get_bank_accounts - 联系人登记的银行账户

📦 产品管理

• product_get - 从价目表（cenik）获取产品
• product_create - 创建新产品
• product_update - 更新现有产品
• product_delete - 删除产品

🏦 银行交易管理

• bank_transaction_get - 获取银行交易（banka）
• bank_transaction_create - 创建银行交易

🔧 通用业务记录操作

• evidence_get - 获取任意业务记录（筛选、分页、排序、关联）
• evidence_create - 在任意业务记录中创建记录
• evidence_update - 更新任意业务记录中的记录（支持 remove_external_ids）
• evidence_delete - 删除任意业务记录中的记录
• evidence_list - 列出绑定公司中所有可用的业务记录（实时读取 evidence-list.json）

🧠 Python-abraflexi 桥接

• abraflexi_client_methods - 列出核心 python-abraflexi 客户端的公开方法（ReadOnly、ReadWrite、Changes、Adresar、FakturaVydana）
• abraflexi_client_call - 使用参数调用指定的公开客户端方法（写入方法仍遵循 READ_ONLY）

🔒 锁定、操作与批量处理

• 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）
• user_query_list - 列出已保存的用户自定义查询（uzivatelsky-dotaz）
• call_user_query - 调用已保存的用户自定义查询（uživatelský dotaz）

ℹ️ 业务记录元数据与汇总

• evidence_get_properties - 列出业务记录支持的字段
• evidence_get_reports - 列出业务记录可用的可打印报告
• evidence_get_relations_list - 列出业务记录可用的子业务记录（关联）
• evidence_get_sum - 获取业务记录的汇总（总计）
• evidence_get_record_changes - 获取单条记录的变更历史

🏷️ 标签（štítky）

• evidence_get_labels - 获取分配给记录的标签
• evidence_set_label - 添加标签
• evidence_unset_label - 移除指定标签
• evidence_unset_labels - 移除所有标签

🔄 变更 API（公司范围内的增量同步）

• changes_enable / changes_disable - 开启／关闭变更跟踪
• changes_status - 检查是否已启用变更跟踪
• changes_get - 分页获取指定版本以来记录的变更

安装

前提条件

• Python 3.10 或更高版本
• 可访问已启用 API 的 AbraFlexi 服务

选项 1：从 PyPI 安装（推荐）

pip install abraflexi-mcp-server

然后运行服务：

abraflexi-mcp

选项 2：AppImage（Linux）

从最新版本下载独立的 AppImage：

chmod +x AbraFlexi-MCP-Server-*-x86_64.AppImage
./AbraFlexi-MCP-Server-*-x86_64.AppImage

无需安装 Python 或 pip。详情请参阅 AppImage 部分。

选项 3：从源代码安装

1. 克隆代码库：

   git clone https://github.com/VitexSoftware/abraflexi-mcp-server.git
   cd abraflexi-mcp-server
   

2. 使用 uv 安装（推荐）：

   uv sync
   uv run python scripts/start_server.py
   

   或使用 pip：

   pip install -e .
   abraflexi-mcp
   

云端部署

可使用以下测试部署：

🌐 https://abraflexi.fastmcp.app/mcp

此云端实例让你无需本地安装即可测试和使用 AbraFlexi MCP 服务。配置 MCP 客户端，使用 HTTP 传输连接到此端点。

**注意：**这是一个测试部署。生产环境中，我们建议使用上述安装方式之一进行自托管。

配置

创建 .env 文件或设置环境变量：

cp .env.example .env
# Edit .env with your AbraFlexi server details

配置

必需的环境变量

• 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 - 使用 streamable-http 传输时，必须设置为 no-auth

使用方法

运行服务

使用启动脚本（推荐）：

uv run python scripts/start_server.py

直接执行：

uv run python -m abraflexi_mcp_server.server

CLI 帮助：

abraflexi-mcp --help

传输选项

此服务支持两种传输方式：

STDIO 传输（默认）

适用于 Claude Desktop 等 MCP 客户端的标准输入/输出传输：

# Set in .env or environment
ABRAFLEXI_MCP_TRANSPORT=stdio

HTTP 传输

基于 HTTP 的传输，适用于 Web 集成：

# Set in .env or environment
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

测试

运行测试套件：

uv run python scripts/test_server.py

只读模式

当 READ_ONLY=true（默认值）时，服务仅公开 GET 操作（检索数据），并阻止所有创建、更新和删除操作。此模式适用于：

• 📊 监控仪表板
• 🔍 只读集成
• 🔒 注重安全的环境
• 🛡️ 防止意外修改

若要启用写入操作，请在 .env 文件中设置 READ_ONLY=false。

工具调用示例

获取所有已开具的发票：

invoice_issued_get(limit=10)

按代码获取指定发票：

invoice_issued_get(kod="INV-2024-001")

统计 2026 年 8 月开具的发票数量（无需下载完整记录）：

invoice_issued_get(
    datum_vystaveni_od="2026-08-01",
    datum_vystaveni_do="2026-08-31",
    detail="id",
    add_row_count=True
)

创建新联系人：

contact_create(
    kod="CUSTOMER01",
    nazev="Example Company s.r.o.",
    email="[email protected]",
    tel="+420123456789"
)

获取产品：

product_get(nazev="Widget", limit=5)

通用 evidence 查询（支持分页/排序）：

evidence_get(
    evidence="faktura-vydana",
    filter_expr="datVyst >= '2024-01-01'",
    order="datVyst",
    order_direction="D",
    limit=20,
    start=0
)

将本地文件附加到任意记录：

evidence_attach_file(evidence="cenik", kod="PRODUCT01", filepath="/path/to/photo.jpg")

锁定发票，然后导出其 PDF：

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"
)

批量更新某个供应商的所有价格表项目：

evidence_mass_update(
    evidence="cenik",
    filter_expr="dodavatel = 'code:SUPPLIER01'",
    data={"stitky": "code:VIP"}
)

通过 Changes API 增量同步：

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。

OCI 容器

此服务可作为 OCI 容器（Docker/Podman）运行，无需在主机上安装 Python。

构建镜像

podman build -t abraflexi-mcp-server -f Containerfile .

运行容器

镜像默认使用 streamable-http 传输，端口为 8000。

使用单独的环境变量：

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

使用环境变量文件：

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 appimage/build-appimage.sh

该脚本会自动下载便携版 CPython 和 appimagetool。生成的文件会放在 build/appimage/ 中：

build/appimage/AbraFlexi-MCP-Server-<version>-x86_64.AppImage

运行 AppImage

如果当前工作目录中存在 .env 文件，AppImage 会自动加载该文件。

使用 .env 文件（推荐）：

cp .env.example .env
# edit .env with your credentials
./AbraFlexi-MCP-Server-*-x86_64.AppImage

使用内联环境变量：

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                  # Main server implementation
├── appimage/
│   ├── AppRun                     # AppImage entry point
│   ├── abraflexi-mcp-server.desktop
│   ├── abraflexi-mcp-server.svg
│   └── build-appimage.sh          # AppImage build script
├── debian/                        # Debian packaging
│   ├── abraflexi-mcp-server.svg   # AppStream stock icon
│   ├── abraflexi-mcp-server.install
│   └── cz.vitexsoftware.abraflexi-mcp-server.metainfo.xml
├── scripts/
│   ├── start_server.py            # Startup script with validation
│   └── test_server.py             # Test script
├── Containerfile                  # OCI container build
├── server.json                    # MCP Registry manifest
├── pyproject.toml                 # Python project configuration
├── setup.py                       # Legacy setuptools configuration
├── requirements.txt               # Dependencies
├── .env.example                   # Environment configuration template
├── .env                           # Your configuration (not in git)
├── .gitignore                     # Git ignore patterns
└── README.md                      # This file

运行测试

# Tool registration + basic connectivity
uv run python scripts/test_server.py

# Live capability scenario (all read tools + READ_ONLY write guards)
# Official public demo (login winstrom / winstrom):
python tests/live_capability_scenario.py \
  --url https://demo.flexibee.eu:5434 \
  --company demo \
  --login winstrom --password winstrom \
  --json-out /tmp/abra-demo-live.json

# Private/dev company example:
python tests/live_capability_scenario.py \
  --url https://flexibee-dev.spoje.net:5434 \
  --company testa_invest_s_r_o_ \
  --login "$ABRAFLEXI_LOGIN" --password "$ABRAFLEXI_PASSWORD" \
  --json-out /tmp/abra-live.json

任何未跳过的检查失败时，退出代码均为非零。

错误处理

该服务包含全面的错误处理：

• ✅ 清晰报告身份验证错误
• 🔒 使用明确的消息阻止违反只读模式的操作
• ✔️ 验证无效参数
• 🌐 正确格式化网络和 API 错误
• 📝 提供详细日志，便于排查问题

安全注意事项

• 🔑 在 .env 文件中安全存储凭据（切勿提交到 git）
• 🔒 对仅用于监控的场景启用只读模式
• 🛡️ 与 AbraFlexi 服务连接时使用 HTTPS
• 🔄 定期轮换密码
• 📁 确保 .env 文件具有适当的权限（600）

故障排除

常见问题

连接失败：

• 确认 ABRAFLEXI_URL 正确且可访问
• 检查身份验证凭据
• 确保已启用 AbraFlexi API
• 检查防火墙/网络设置

权限被拒绝：

• 确认用户拥有足够的 AbraFlexi 权限
• 尝试修改数据时，检查是否启用了只读模式

未找到工具：

• 确保已安装所有依赖项：uv sync
• 确认 Python 版本兼容（3.10+）

调试模式

设置环境变量以启用详细日志：

export DEBUG=1
uv run python scripts/start_server.py

依赖项

• FastMCP - MCP 服务框架
• python-abraflexi - AbraFlexi Python 库
• python-dotenv - 环境变量管理

许可证

本项目采用 MIT 许可证。

致谢

• 感谢 AbraFlexi 提供会计平台
• 感谢 Model Context Protocol 提供集成标准
• 感谢 FastMCP 提供服务框架

支持

• 📖 文档
• 🐛 问题跟踪
• 💬 AbraFlexi API 文档

作者

Vítězslav Dvořák

• 电子邮件：[email protected]
• GitHub：@VitexSoftware

---

为 AbraFlexi 和 MCP 社区倾情打造 ❤️