InvoiceXML

InvoiceXML MCP 服务

一个 Model Context Protocol 服务，可向 AI Agent 提供 InvoiceXML API。支持 Factur-X、ZUGFeRD、 XRechnung、UBL / CII 和 Peppol BIS Billing 3.0。

同一代码库支持两种部署模式，启动时通过一个环境变量选择：

模式	运行方	身份验证
可自托管	你，在自己的机器或服务上	通过环境变量或 appsettings.json 设置单个 API 密钥
托管	InvoiceXML，在自己的基础设施上	针对 invoicexml.com 的 OAuth 2.1 + 动态客户端注册

两种模式运行的是同一个二进制文件，只有配置不同。此代码库与平台无关，不涉及托管位置或方式。

架构

+----------------------+   ProjectReference   +----------------------+
|  InvoiceXml.Mcp.Core | -------------------> |  InvoiceXml.Mcp.Host |
|  (SDK: client+tools) |                      |  (the deployable)    |
+----------------------+                      +----------------------+

InvoiceXml.Mcp.Core 是一个轻量、与传输方式无关的 SDK：

• IInvoiceXmlClient — 面向公共 REST API 的类型化客户端
• HttpInvoiceXmlClient — 唯一的实现；使用来自 IHttpClientFactory 的 HttpClient
• InvoiceXmlClientOptions — 基础 URL、超时时间（不含身份验证）
• AddInvoiceXmlMcpCore(IServiceCollection, IConfiguration) — DI 入口；返回 IHttpClientBuilder，以便宿主将身份验证作为 DelegatingHandler 附加

SDK 不会接触凭据。宿主通过 HTTP 管道应用凭据。 正是这个分界点，让同一代码库能够支持两种部署模式。

InvoiceXml.Mcp.Host 是一个 ASP.NET Core 10 应用：

• 在启动时读取 Mcp:AuthMode（ApiKey 或 OAuth）
• 通过 AddHostAuth(...) 将相应的 DelegatingHandler 接入 Core HTTP 客户端
• 在 POST / 提供 MCP 端点，在 GET / 提供便于浏览的欢迎页面，并提供 /health

添加一种新的身份验证模式 = 在 AuthExtensions.cs 中添加一个分支，并在 Auth/<Mode>/ 下添加一个小型文件夹。添加一个新工具 = 新增一个 [McpServerTool] 类。其他内容无需更改。

仓库结构

invoicexml-mcp/
├── src/
│   ├── InvoiceXml.Mcp.Core/              # the SDK: client, models, tools
│   │   ├── Enums/  Interfaces/  Models/  Options/  Services/  Tools/  Extensions/
│   └── InvoiceXml.Mcp.Host/              # the deployable host
│       ├── Auth/{ApiKey,OAuth}/          # the two auth modes
│       ├── Configuration/
│       ├── Program.cs
│       └── appsettings.json              # safe defaults, no secrets
├── tests/
│   ├── InvoiceXml.Mcp.Core.Tests/
│   └── InvoiceXml.Mcp.Host.Tests/
├── Directory.Build.props                 # repo-wide MSBuild defaults
├── Directory.Packages.props              # Central Package Management
├── global.json                           # pins the .NET SDK
└── InvoiceXml.Mcp.slnx

本地运行

你需要 .NET 10 SDK 和一个 InvoiceXML API 密钥。

# 1. Provide your API key (pick one):

# A. dotnet user-secrets (recommended — kept outside the repo)
dotnet user-secrets --project src/InvoiceXml.Mcp.Host set "Mcp:ApiKey:Value" "your-key"

# B. environment variable
$env:INVOICEXML_API_KEY = "your-key"

# 2. Run
dotnet run --project src/InvoiceXml.Mcp.Host

在浏览器中访问 GET http://localhost:5004/ 会显示欢迎页面；MCP 端点是 POST http://localhost:5004/；GET /health 返回 { "status": "ok" }。

配置

{
  // Required in OAuth mode. The public origin where this MCP server is reachable.
  // Used in the protected-resource metadata response.
  "McpUri": "https://mcp.example.com",

  "InvoiceXml": {
    "BaseUrl": "https://api.invoicexml.com",   // override for staging / local
    "Timeout": "00:01:40"
  },

  "Mcp": {
    "AuthMode": "ApiKey",                       // "ApiKey" | "OAuth"
    "ApiKey": {
      "Value": ""                               // ApiKey mode: NEVER commit a real key
    },
    "OAuth": {
      "AuthorizationServer": "https://invoicexml.com",
      "ScopesSupported": [ "api_token.read" ]
    },
    "FileInput": {                              // limits for the URL-fetch input mode
      "MaxFileSizeBytes": 5242880,
      "FetchTimeout": "00:00:30"
    }
  }
}

对应的环境变量（双下划线表示嵌套）：

变量	对应配置
INVOICEXML_API_KEY	Mcp:ApiKey:Value（便捷别名）
Mcp__ApiKey__Value	Mcp:ApiKey:Value
Mcp__AuthMode	Mcp:AuthMode（ApiKey 或 OAuth）
Mcp__OAuth__AuthorizationServer	Mcp:OAuth:AuthorizationServer
McpUri	McpUri（根级配置）
InvoiceXml__BaseUrl	InvoiceXml:BaseUrl

OAuth 模式

当 Mcp:AuthMode=OAuth 时，宿主不再接受静态 API 密钥，而是：

1. 对任何不含 Bearer 令牌的 POST / 请求返回 401，并附带 WWW-Authenticate: Bearer resource_metadata="…"。
2. 提供 GET /.well-known/oauth-protected-resource，将 MCP 客户端指向作为授权服务器的 invoicexml.com。
3. 在每次出站调用 InvoiceXML API 时，原样转发传入的 Bearer 令牌 （API 是令牌有效性的事实来源；MCP 服务不会在本地验证令牌）。

MCP 客户端执行的流程：

client → MCP  POST /                           → 401 + resource_metadata
client → /.well-known/oauth-protected-resource → { authorization_servers: [invoicexml.com] }
client → invoicexml.com/.well-known/oauth-authorization-server
                                               → { authorize, token, register endpoints }
client → invoicexml.com/oauth/register         → client_id + client_secret  (DCR)
client → invoicexml.com/oauth/authorize        → user consents, gets code
client → invoicexml.com/oauth/token            → access_token  (= user's API key)
client → MCP  POST /  + Authorization: Bearer  → 200, tool call flows through

部署

宿主是一个标准的 ASP.NET Core 应用——可按运行 .NET 服务的常用方式部署 （systemd、容器、PaaS 等；本仓库不指定具体方式）：

dotnet publish src/InvoiceXml.Mcp.Host -c Release -o ./publish
# then run ./publish/InvoiceXml.Mcp.Host on your host

在宿主上通过环境变量设置配置（切勿提交机密信息）：

• ASPNETCORE_ENVIRONMENT=Production
• Mcp__AuthMode=ApiKey（或 OAuth）
• Mcp__ApiKey__Value=… / INVOICEXML_API_KEY=…（ApiKey 模式）
• McpUri=https://your-public-url 和 Mcp__OAuth__AuthorizationServer=https://invoicexml.com（OAuth 模式）

在反向代理 / 负载均衡器处终止 TLS，并将请求转发到宿主的 HTTP 端口。 此服务无状态，因此可以在负载均衡器后运行多个实例。

许可证

MIT — 参见 LICENSE。