AbraFlexi MCP服务器
使用FastMCP和python AbraFlexi集成AbraFlexi的综合模型上下文协议（MCP）服务器。该服务器通过兼容MCP的工具提供对AbraFlexi REST API功能的完全访问。
特性
📄 发票管理
invoice_issued_get-检索已开具的发票（faktura vydana）invoice_issued_create-创建新的已开具发票invoice_issued_update-更新现有已开具发票invoice_issued_delete-删除已开具的发票invoice_received_get-检索收到的发票（faktura prijata）invoice_received_create-创建新收到的发票
👥 联系人管理
contact_get-检索联系人和公司（地址）contact_create-创建新联系人contact_update-更新现有联系人contact_delete-删除联系人
📦 产品管理
product_get-从价目表中检索产品（cenik）product_create-创造新产品product_update-更新现有产品product_delete-删除产品
🏦 银行交易管理
bank_transaction_get-检索银行交易记录（banka）bank_transaction_create-创建新的银行交易记录
🔧 通用证据操作
evidence_get-从任何证据中获取记录evidence_create-在任何证据中创建记录evidence_update-更新任何证据中的记录evidence_delete-从任何证据中删除记录evidence_list-列出所有可用证据
安装
先决条件
- 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：从源代码安装
- 克隆存储库：
git clone https://github.com/VitexSoftware/abraflexi-mcp-server.git
cd abraflexi-mcp-server- 使用紫外线进行安装（推荐）：
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-必须设置为no-auth用于流式http传输
用法
运行服务器
使用启动脚本（推荐）：
uv run python scripts/start_server.py直接执行：
uv run python -m abraflexi_mcp_server.server运输选项
服务器支持两种传输方式：
STDIO传输（默认）
Claude Desktop等MCP客户端的标准输入/输出传输：
# Set in .env or environment
ABRAFLEXI_MCP_TRANSPORT=stdioHTTP传输
基于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操作（检索数据）并阻止所有创建、更新和删除操作。这有助于：
- 📊 监控仪表板
- 🔍 只读集成
- 🔒 具有安全意识的环境
- 🛡️ 防止意外修改
要启用写入操作，请设置 READ_ONLY=false 在你的 .env 文件。
工具调用示例
获取所有已开具的发票：
invoice_issued_get(limit=10)按代码获取特定发票：
invoice_issued_get(kod="INV-2024-001")创建新联系人：
contact_create(
kod="CUSTOMER01",
nazev="Example Company s.r.o.",
email="info@example.com",
tel="+420123456789"
)获取产品：
product_get(nazev="Widget", limit=5)通用证据查询：
evidence_get(
evidence="faktura-vydana",
filter_expr="datVyst >= '2024-01-01'",
limit=20
)MCP集成
此服务器旨在与兼容MCP的客户端（如Claude Desktop）配合使用。看 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使用env文件：
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--x86_64.AppImage运行AppImage
AppImage会自动加载 .env 如果存在，请从当前工作目录中删除文件。
使用.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
├── 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运行测试
# Test server functionality
uv run python scripts/test_server.py
# Test with specific environment
ABRAFLEXI_URL=https://your-server.com uv run python scripts/test_server.py错误处理
服务器包括全面的错误处理：
- ✅ 明确报告身份验证错误
- 🔒 用描述性消息阻止只读模式违规
- ✔️ 验证无效参数
- 🌐 网络和API错误的格式正确
- 📝 用于故障排除的详细日志记录
安全考虑
- 🔑 将凭据安全地存储在
.envfile（永远不要提交到git） - 🔒 启用只读模式，仅监视用例
- 🛡️ 将HTTPS用于AbraFlexi服务器连接
- 🔄 定期轮换密码
- 📁 确保
.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 API文件
作者
维特斯拉夫 Dvorak
- 电子邮件：info@vitexsoftware.cz
- github： @Vitex软件
______________________________________________________________________
由以下材料制成❤️ AbraFlexi和MCP社区