Multi-Tenant Invoice Autofill MCP Server

一个 Python 后端服务，使支持函数调用或 MCP 的 LLM（Claude、Gemini、GPT 等）能够代表租户在 Digital Invoicing Software 上自动填写并保存发票。

功能特性

• 双传输支持：通过标准 MCP 协议（stdio / Streamable HTTP）和 REST API（FastAPI，带 OpenAPI Schema）对外提供。

• 多租户与认证：按租户的凭据加密、自定义 MCP API 密钥以及隔离的会话管理。

• 弹性适配器：封装式 HTTP 适配器，模拟浏览器请求头，支持自动会话刷新和动态 Cookie 过期时间解析。

• 幂等性与并发控制：通过文档哈希进行去重，并使用按租户的 Redis 分布式锁（lock:tenant:{id}）。

• 隐私优先：强制性的结构化日志脱敏层，用于清除密码、Cookie、密钥和令牌。

• 零硬编码值：代码、注释或测试中不包含任何凭据或业务身份；测试数据全部通过合成方式生成。

Related MCP server: Invoice MCP Server

本地先决条件

• Python 3.12+

• Docker 和 Docker Compose（用于本地 Postgres 和 Redis）

快速开始

1. 环境设置

将 .env.example 复制为 .env 并设置本地变量：

cp .env.example .env

2. 启动本地数据库与 Redis

docker-compose up -d

3. 安装依赖

python -m venv .venv
# Windows:
.\.venv\Scripts\pip install -r requirements.txt
# Linux/macOS:
source .venv/bin/activate
pip install -r requirements.txt

4. 运行迁移

.\.venv\Scripts\alembic upgrade head

5. 启动服务器

# Start FastAPI REST server:
.\.venv\Scripts\uvicorn mcp_digitalinvoice.main:app --reload --port 8000

# Run MCP stdio server:
.\.venv\Scripts\python -m mcp_digitalinvoice.mcp_server.server

安全

[!CAUTION] 加密密钥管理：ENCRYPTION_KEY 环境变量必须设置为安全且经 base64 编码的 32 字节 Fernet 密钥。如果未提供 ENCRYPTION_KEY，应用程序将在启动时立即失败。如果某个加密密钥曾用于加密真实租户数据，且怀疑其已泄露，则必须使用新生成的密钥重新加密这些数据，因为旧密钥必须被视为已泄露。

工作流程

租户接入（connect_account）

1. 使用租户在 Digital Invoicing Software 上的登录邮箱、密码和企业名称调用 connect_account。

2. 服务器对凭据进行加密，通过初始登录对其验证，并返回唯一的 mcp_api_key。

3. 将此 mcp_api_key 提供给 LLM（以 Bearer 令牌或请求头的形式），用于后续的工具调用。

发票自动填写（fill_invoice）

LLM 使用提取出的发票 JSON 负载（buyer、items、meta）调用 fill_invoice。该服务会验证必填字段、强制执行单文档顺序处理、检查幂等性、解析租户会话、将负载映射为下游结构，并创建发票草稿。

运行测试

.\.venv\Scripts\pytest -v tests/