xentral-mcp

<p align="center"> <img src="https://raw.githubusercontent.com/mjmirza/xentral-mcp/main/assets/xentral-icon.png" width="96" height="96" alt="xentral-mcp" /> </p> # xentral-mcp 通过Claude和其他MCP客户端以自然语言与您的Xentral ERP对话。询问客户、产品、未结发票或销售订单，并获得答案，无需打开Xentral用户界面或编写API调用。     > 适用于Xentral®。这是一个独立且非官方的连接器，不隶属于、不支持或不赞同Xentral。参见[商标声明](docs/TRADEMARKS.md)。 > > 许可证一句话。这不是MIT许可证，在商业环境下不免费使用。个人可以免费测试，并附上作者的署名。任何商业或商业化使用需要作者的事先书面批准。它按原样提供，不提供任何保证或责任，您自担风险。请在使用前阅读[许可证](LICENSE)。 > > 没有AI克隆。使用AI克隆、重新实现或重建该项目是衍生作品，需要作者的书面同意，参见[AGENTS.md](AGENTS.md)。如果您需要用于商业或定制，请通过next8n.com联系作者。 ## 您获得的内容 - 来自您实时ERP的答案，在您的AI客户端内。“显示我最近五笔销售订单”返回真实的行，不需要切换标签。 - 本地和平台无关。它在您的机器上通过stdio运行，支持macOS、Linux或Windows，无需云账户和供应商锁定。安装仅拉取MCP SDK、dotenv和zod，没有云特定内容。托管部署是可选的，从不必需。 - 默认读取，具有受保护的写入路径。写入在您启用它们之前关闭，因此代理可以查看但不更改任何内容，直到您允许。 - 正确的路径，而不是猜测的路径。每个工具都指向来自Xentral OpenAPI规范的已验证端点，包括朴素构建会出错的陷阱（交货单据，而不是发货级别的`deliveries`路径）。 - 访问548个操作。41种工具涵盖了订单到现金和采购到付款流程以及webhooks的常见情况，包括创建订单、发票、产品、客户、发货和收货的命名写入操作。当您需要更罕见的操作（会计、税务、POS）时，查找工具定位确切的路径，守护的通用请求调用它。 - 输出令牌精简。响应去除空字段，以便大型结果不会淹没您的上下文。询问`verbose`时，您将获得完整的有效载荷。 - 一条命令设置。`xentral-mcp setup`连接您的客户端，检查您的令牌是否与实时实例匹配，并在备份现有的配置之前。 ## 从头到尾的操作 1. 在Xentral的帐户设置、开发者设置、个人访问令牌下创建个人访问令牌。复制一次，它只在创建时显示。 2. 运行设置命令并粘贴您的实例URL和令牌。 ```bash npx xentral-mcp setup ``` 3. 重启您的客户端（Claude Desktop、Claude Code、Cursor、Windsurf或VS Code）。 4. 提出问题。“列出Xentral的前五个产品。”您获得了第一个答案。 在任何时候确认健康状况。 ```bash npx xentral-mcp doctor ``` ## 实际操作示例 您用自然语言提问。连接器调用已验证的端点，附加您的令牌，并返回真实的行。无需切换标签，无需API代码。 ```text 您：显示Xentral最近的三笔销售订单。 xentral-mcp -> GET /api/v1/salesOrders （验证路径，只读，令牌附加） Claude： # 订单 客户 日期 净额 状态 1 SO-10482 Muster GmbH 2026-07-06 1,240.00 released 2 SO-10481 Beispiel AG 2026-07-05 380.50 open 3 SO-10480 Test Handel KG 2026-07-05 2,905.00 shipped ``` 启用写入，相同的自然语言创建记录，在保护措施后面。 ```text 您：为客户4471创建销售订单，3个单位的SKU A-100。 xentral-mcp -> POST /api/v1/salesOrders/actions/import （写入路径，仅当您启用时） Claude：完成。订单SO-10483已创建，状态为open。您要释放它吗？ ``` ## 各个部分如何组合 ```mermaid flowchart LR A["您，使用自然语言"] --> B["MCP客户端<br/>Claude, Cursor, Windsurf, VS Code"] B --> C["xentral-mcp<br/>默认读取，保护写入"] C -->|"验证路径 + Bearer令牌通过TLS"| D[("您的Xentral ERP")] C -. "SSRF防护，路径防护，令牌删除，大小上限" .-> C ``` ## 这是针对谁的 适用于运行Xentral的机构和运营商，为DACH商务提供AI助手，可以安全地读取ERP。工具是源代码可用的。个人可以免费测试，并附上署名。任何商业或商业化使用需要作者的事先书面批准，参见[许可证](LICENSE)。其价值是一种有根据的、正确的、具有防护措施的集成，陌生人可以在五分钟内安装，付费服务将为您建立。 ## 我可以自行托管Xentral并指向它吗 不。现代Xentral仅支持云版本，唯一可自行托管的选项是旧社区分支OpenXE，它使用不同的API版本（HTTP摘要验证，而不是Bearer）。此MCP无法与其通信。如果您尝试这样做，请先阅读完整的说明并节省时间，参见[xentral-self-hosting-lessons](https://github.com/mjmirza/xentral-self-hosting-lessons)。使用现代Xentral云账户和个人访问令牌进行此MCP。 ## 此版本中的工具 26个命名读取工具，12个命名写入工具（默认关闭），2个规范库存帮助程序和1个守护的通用请求。总共41个。 ### 读取工具 | 工具 | 读取 | 路径 | |------|-------|------| | `xentral_list_products` | 产品 | `GET /api/v2/products` | | `xentral_get_product` | 一个产品 | `GET /api/v2/products/{id}` | | `xentral_get_product_stock` | 一个产品的库存 | `GET /api/v1/products/{id}/stocks` | | `xentral_get_product_sales_prices` | 一个产品的销售价格 | `GET /api/v1/products/{id}/salesPrices` | | `xentral_list_customers` | 客户 | `GET /api/v2/customers` | | `xentral_get_customer` | 一个客户 | `GET /api/v2/customers/{id}` | | `xentral_list_sales_orders` | 销售订单 | `GET /api/v1/salesOrders` | | `xentral_get_sales_order` | 一个销售订单 | `GET /api/v1/salesOrders/{id}` | | `xentral_list_invoices` | 发票 | `GET /api/v1/invoices` | | `xentral_get_invoice` | 一个发票 | `GET /api/v1/invoices/{id}` | | `xentral_get_invoice_balance` | 一个发票的余额 | `GET /api/v1/invoices/{id}/balance` | | `xentral_get_invoice_documents` | 一个发票的文档和PDF引用 | `GET /api/v1/invoices/{id}/documents` | | `xentral_list_purchase_orders` | 采购订单 | `GET /api/v1/purchaseOrders` | | `xentral_get_purchase_order` | 一个采购订单 | `GET /api/v1/purchaseOrders/{id}` | | `xentral_list_delivery_notes` | 交货单据 | `GET /api/v1/deliveryNotes` | | `xentral_get_delivery_note` | 一个交货单据 | `GET /api/v1/deliveryNotes/{id}` | | `xentral_get_delivery_note_shipments` | 一个交货单据的发货 | `GET /api/v1/deliveryNotes/{id}/shipments` | | `xentral_list_suppliers` | 供应商 | `GET /api/v1/suppliers` | | `xentral_get_supplier` | 一个供应商 | `GET /api/v1/suppliers/{id}` | | `xentral_list_webhooks` | webhooks | `GET /api/v1/webhooks` | | `xentral_get_webhook` | 一个webhook | `GET /api/v1/webhooks/{id}` | | `xentral_list_webhook_event_types` | webhook事件类型 | `GET /api/v1/webhookEventTypes` | | `xentral_list_domains` | API区域及其计数 | 捆绑库存 | | `xentral_find_endpoint` | 任意548个操作按关键词 | 捆绑库存 | | `xentral_request` | 对任意规范路径的守护请求 | 守护通用 | ### 写入工具 这些是集成用户最常用的写入操作。我们通过侦察实际的Xentral连接器（Make.com应用、n8n社区节点、较旧的n8n节点）来选择它们，其中相同的核心不断出现，然后针对捆绑的规范交叉检查每个路径，以确保每个工具都指向实际操作。每个写入工具默认关闭。如果服务器启动时`XENTRAL_MCP_READONLY=false`，它返回一个明确的错误，并且在启用写入之前永远不会调用API。它们都不使用DELETE。 | 工具 | 执行 | 路径 | |------|------|------| | `xentral_create_sales_order` | 导入新的销售订单（每个商店和市场推送使用的操作） | `POST /api/v1/salesOrders/actions/import` | | `xentral_release_sales_order` | 释放订单以履行 | `PATCH /api/v3/salesOrders/{id}/actions/release` | | `xentral_send_sales_order` | 将订单文档发送给客户 | `PATCH /api/v3/salesOrders/{id}/actions/send` | | `xentral_cancel_sales_order` | 取消订单 | `POST /api/v1/salesOrders/{id}/actions/cancel` | | `xentral_set_product_stock` | 在存储位置设置绝对库存 | `PATCH /api/v1/storageLocations/setTotalStock` | | `xentral_create_shipment` | 记录带有跟踪信息的发货 | `POST /api/v1/shipments` | | `xentral_create_invoice` | 创建发票 | `POST /api/v1/invoices` | | `xentral_create_credit_note` | 创建退款或更正的信用额度 | `POST /api/v1/creditNotes` | | `xentral_create_product` | 创建产品 | `POST /api/v2/products` | | `xentral_create_customer` | 创建客户（具有客户角色的地址） | `POST /api/v2/customers` | | `xentral_create_purchase_order` | 创建采购订单给供应商 | `POST /api/v1/purchaseOrders` | | `xentral_receive_goods` | 记录采购订单的收货 | `POST /api/v1/purchaseOrders/{id}/goodsReceipts` | 两个陷阱值得明确说明。首先，`xentral_set_product_stock`设置绝对数量，它不是增量也不是移动记账，因为API没有单独的库存移动交易端点。其次，`xentral_create_shipment`记录跟踪信息，它不打印承运商标签，因为API没有公共标签生成调用。使用`xentral_get_delivery_note_shipments`读取记录的内容。 命名写入工具在本地stdio服务器上运行，您在自己的机器上控制写入标志。托管的工作程序保持写入关闭，因此多租户路径保持只读。 ### 守护的通用请求 `xentral_request`在严格的守护下访问命名工具未涵盖的操作。 - GET始终允许。POST、PATCH和PUT仅当服务器启动时`XENTRAL_MCP_READONLY=false`才允许。DELETE还需要`XENTRAL_MCP_ALLOW_DELETE=true`。 - 不允许的方法返回结构化错误，从不调用API。 - 路径必须是相对的，以`/api/`开头，并且必须在该方法中存在于规范中。完整URL、协议相对表单和路径遍历被拒绝（SSRF防护）。Bearer令牌自动附加，从不记录。 - 在429速率限制时，请求在短暂的延迟后重试一次。 写入默认关闭。出于实际原因，PATCH销售订单会替换其完整的行项目列表，因此任何未包含的行项目将被删除。调用者必须发送现有的行项目ID以保留它们。读取保持安全的默认值，而写入是您有意选择开启的。 ## 配置 在您的客户端配置或本地`.env`中设置这些。 | 变量 | 含义 | |----------|---------| | `XENTRAL_API_URL` | 完整的实例主机，例如`https://acme.xentral.biz`。没有版本段。裸主机没有方案会添加`https`。 | | `XENTRAL_ID` | 实例ID，仅扩展为`https://<id>.xentral.biz`。使用其中一个。 | | `XENTRAL_TOKEN` | 个人访问令牌。永远不要提交它。永远不要粘贴到聊天中。 | | `XENTRAL_MCP_READONLY` | 读取防护。默认值1，读取仅需。设置为`false`以允许POST、PATCH和PUT通过通用工具。 | | `XENTRAL_MCP_ALLOW_DELETE` | 默认`false`。设置为`true`，与readonly `false`一起允许DELETE。 | | `XENTRAL_MCP_TIMEOUT_MS` | 每个请求的超时毫秒数。默认30000。 | | `XENTRAL_MAX_RESPONSE_CHARS` | 格式化输出的字符上限。默认20000。 | 您的令牌存储位置。设置命令将其写入您选择的客户端配置文件中，而其他地方不存储。令牌仅通过TLS到达您的Xentral实例。 ## 手动布线 如果您的客户端不在已知列表中，请打印配置块并粘贴您自己。 ```bash npx xentral-mcp setup --print ``` 对于CI或脚本安装，请使用标志驱动。 ```bash npx xentral-mcp setup --yes --url https://acme.xentral.biz --token "$XENTRAL_TOKEN" --client cursor` ``` ## 本地开发 ```bash npm install npm run typecheck npm run build npm run smoke` ``` 烟雾测试启动构建的服务器，通过stdio断言每个工具注册。它不会进行实时实例。 ## 安全 - 默认读取。写入在`XENTRAL_MCP_READONLY=false`时关闭，DELETE还需要`XENTRAL_MCP_ALLOW_DELETE=true`。 - 方法防护。禁止的方法返回结构化错误，不会调用API。 - 路径防护。通用工具接受相对`/api/`路径，仅拒绝完整URL、协议相对表单和路径遍历，并拒绝任何不在规范中指定路径的方法（SSRF防护）。 - 机密卫生。令牌从不记录，错误主体中的任何出现都将被删除。 - 令牌静止存储。在托管路径上，令牌用AES-256-GCM加密后存储，不会以纯文本形式持久保存。 完整的姿态、威胁模型、静止加密、SSRF和路径防御以及您承担的责任在[.github/SECURITY.md](.github/SECURITY.md)中有详细说明。 ## 托管选项 运行此程序的默认和推荐方式是本地stdio服务器，绑定到任何平台。 如果您不想在本地运行，可以使用托管的Cloudflare Worker作为替代方案（作者使用的）。 它使用MCP Streamable HTTP传输，提供个人访问令牌头方法和OAuth同意流程，签署人员一次登录。 两种方法都以AES-256-GCM加密令牌存储在静止状态。 整个托管路径在本地Cloudflare运行时测试端到端，连接方法、完整OAuth流程、静止加密和端点保护。 请参阅`docs/PROJECT_STRUCTURE.md`了解详情。 ## 测试 测试范围明确说明，不夸大。 - 163个单元测试用例，涵盖纯模块和写入门控，Node内置测试运行。功能覆盖率100%，行覆盖率99.78%。工具未计算的一行是类型声明，不携带运行时。 - 33个离线对抗性套件，证明SSRF、路径、只读、删除防护，打开和关闭写入和删除路径，并显示敌对输入不会使服务器崩溃或令牌泄漏。 - 7个MCP协议一致性套件，涵盖所有41种工具。 - 15个工作程序套件，涵盖加密、同意页面和配置助手。 - 一个实时端点扫描，调用Xentral实例上的所有194个GET操作并报告每个操作。发现了零个客户端错误。少数会计端点在演示实例上返回服务器端500，因为未在那里配置该模块，扫描将其记录为上游故障，而不是客户端故障。 - 32个实时压力测试套件，涵盖分页边界、每分钟100次速率限制和429处理、响应截断和请求超时。 使用`npm test`运行离线捆绑包。它涵盖了烟雾、单元、协议、工人、攻击、扫视和压力测试，并且不进行实时调用。 使用`npm run test:live`运行实时捆绑包，它涵盖了实时、实时写入、扫视和压力测试，并且需要环境中的真实令牌和实例URL。 单个脚本`test:unit`, `test:aggression`, `test:protocol`, `test:worker`, `test:sweep`, `test:stress`, `test:live`, `test:live:write`, 也存在。 ## 需要为您的业务设置吗？ 如果您运行Xentral并希望将其连接到您自己的实例，或扩展到您确切的工作流，Nexus AI可以为您完成设置。这是付费安装和集成服务，位于开放工具之上。那涵盖了什么，一一列出。 1.托管安装和布线。Nexus AI将服务器连接到您的Xentral实例，实时验证令牌，并将其连接到您选择的客户端，Claude、Cursor或任何MCP客户端，以便您的团队从第一天开始提出问题，而不是阅读设置文档。 2. 为您的流程定制工具。这里的41种工具涵盖了常见的情况。Nexus AI添加了您每天运行的精确端点的命名工具，从规范中的548个中，正确的分页、内容类型和陷阱为您处理。 3. 安全地启用写入。创建订单、发票、发货和收货单据默认关闭。Nexus AI启用您实际需要的写入操作，在相同的读取保护和删除保护下，并简要审查行项目替换行为，以免PATCH意外删除您想要保留的内容。 4. 托管部署。如果您不想运行本地服务器，Nexus AI部署托管的Cloudflare Worker，带有OAuth登录和静止加密的令牌，因此您的整个团队通过一个URL连接。 5. 防护措施和监控。SSRF和路径防护、令牌删除、速率限制处理和健康检查，以及深入的测试套件，因此您触摸ERP的东西是值得信赖的。 6. 交接和培训。关于如何用自然语言询问订单、库存、发票等内容的简要会议，以及您保留的书面运行手册。 想安装或在上面构建自定义版本吗？通过next8n.com联系Nexus AI，描述您的实例和您关心的流程，Nexus AI将为您量身定制。 ## 项目结构 参见`docs/PROJECT_STRUCTURE.md`了解文件夹布局、托管部署、写入阶段和成本模型。 ## 许可证和致谢 源代码可用于[Xentral-MCP源代码可用许可证](LICENSE)。这不是MIT许可证，也不是开源许可证。简而言之。 - 个人可以免费下载、运行和测试它，并附上作者的署名。 - 商业使用、生产使用和任何商业部署需要作者的事先书面批准。通过next8n.com提出请求。 - 保留字数在任何使用中必须保留。保留版权声明和通知。 - 按原样提供，不提供任何保证或责任。您自担风险，所有代理对您的数据采取的行动都是您的责任。 Xentral&reg;是Xentral ERP Software GmbH的商标。该项目是独立且非官方的，不隶属于、不支持或赞同Xentral ERP Software GmbH，并且仅使用名称来声明API兼容性。如果Xentral ERP Software GmbH或任何权利持有人希望删除或更改任何引用，请发送电子邮件至support@next8n.com，它将及时、善意地完成。参见[商标和署名](docs/TRADEMARKS.md)。