Spendesk MCP Server

Spendesk MCP服务器

服务器 主控程序 暴露我API公共部门 以“的形式工具 et de 资源 倾倒：

• 自动化ERP集成 （NetSuite、Xero、QuickBooks、DATEV等）
• 创建仪表板 来自Spendesk数据（结算、应付款项、供应商、用户等）

先决条件

• Node.js≥18
• 德 标识符OAuth2客户端 Spendesk（客户端ID+客户端机密），创建于 *设置>集成>API访问管理* （包括保费/企业、法定账户所有者）。

安装

npm install
npm run build

配置

环境变量：

乐模式 标准 (npm start)等等 回退HTTP 仅使用 OAuth2客户端凭据 : SPENDESK_ENV=production|demo|trunk +相应的标识符对。默认URL:prod https://public-api.spendesk.com，演示 https://public-api.demo.spendesk.com树干 https://beta-sandbox.api.trunk.spendesk.services （历史）。

文件示例 .env （不要提交）：

# Prod
SPENDESK_CLIENT_ID=your_client_id
SPENDESK_CLIENT_SECRET=your_client_secret

# Demo (optionnel)
# SPENDESK_ENV=demo
# SPENDESK_CLIENT_ID_DEMO=your_demo_client_id
# SPENDESK_CLIENT_SECRET_DEMO=your_demo_client_secret

# Trunk (optionnel)
# SPENDESK_ENV=trunk
# SPENDESK_CLIENT_ID_TRUNK=your_trunk_client_id
# SPENDESK_CLIENT_SECRET_TRUNK=your_trunk_client_secret

禁用某些（实验）工具

要避免暴露某些工具（例如实验工具），请创建配置文件。禁用的工具不是 未注册 并且不出现 步 在API参考中（工具 spendesk_get_api_reference 和资源 spendesk://api-reference).

文件 config/tools.config.json 项目的根源（或 tools.config.json) :

{
  "disabledTools": [
    "spendesk_get_accruals",
    "spendesk_get_purchase_orders"
  ]
}

服务器在启动时读取此文件。要重新激活工具，请从中删除其名称 disabledTools 并重新启动服务器。

明特利医生 ：要使文档（spendesk mcp docs）仅显示启用的工具，请在启动或部署文档之前运行：

npm run docs:sync-tools

然后在本地启动doc npm run docs:dev （同步+ mintlify dev）的。概述、簿记、应付账款、参考数据和支出分析页面将更新以隐藏禁用的工具。

使用

启动服务器（stdio）

# Client credentials (prod)
export SPENDESK_CLIENT_ID=...
export SPENDESK_CLIENT_SECRET=...
npm start

# Client credentials (demo)
export SPENDESK_ENV=demo
export SPENDESK_CLIENT_ID_DEMO=...
export SPENDESK_CLIENT_SECRET_DEMO=...
npm start

# Client credentials (trunk)
export SPENDESK_ENV=trunk
export SPENDESK_CLIENT_ID_TRUNK=...
export SPENDESK_CLIENT_SECRET_TRUNK=...
npm start

烟雾测试Stdio（之后 npm run build) : npm run test:mcp --视频 SPENDESK_API_TOKEN 并要求 SPENDESK_CLIENT_ID + SPENDESK_CLIENT_SECRET （或一对 _DEMO).

服务器通信 标准 ：MCP客户端（Cursor、Claude Desktop等）可以将其作为子进程运行，并发送JSON-RPC请求。

配置器光标

在游标的MCP设置中（或在MCP配置文件中）：

{
  "mcpServers": {
    "spendesk": {
      "command": "node",
      "args": ["/chemin/vers/spendesk-mcp-server/dist/index.js"],
      "env": {
        "SPENDESK_ENV": "demo",
        "SPENDESK_CLIENT_ID_DEMO": "",
        "SPENDESK_CLIENT_SECRET_DEMO": ""
      }
    }
  }
}

或与 npx 从项目目录（相同变量 SPENDESK_CLIENT_ID / SPENDESK_CLIENT_SECRET 或演示）：

{
  "mcpServers": {
    "spendesk": {
      "command": "npx",
      "args": ["-y", "tsx", "src/index.ts"],
      "cwd": "/chemin/vers/spendesk-mcp-server",
      "env": {
        "SPENDESK_ENV": "demo",
        "SPENDESK_CLIENT_ID_DEMO": "",
        "SPENDESK_CLIENT_SECRET_DEMO": ""
      }
    }
  }
}

（在生产中，优先考虑 node dist/index.js 之后 npm run build.)

配置者Claude桌面

1. 编译项目 （如果尚未完成）：

   cd /chemin/vers/spendesk-mcp-server
   npm run build

1. 打开Claude的MCP配置 :

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 或者在Claude桌面中： 设置 → 开发者 → 编辑配置

1. 添加Spendesk服务器 在 mcpServers （替换路径和令牌）：

   {
     "mcpServers": {
       "spendesk": {
         "command": "node",
         "args": ["/chemin/vers/spendesk-mcp-server/dist/index.js"],
         "env": {
           "SPENDESK_CLIENT_ID": "",
           "SPENDESK_CLIENT_SECRET": ""
         }
       }
     }
   }

使用真实的绝对路径，例如：

   "args": ["/Users/julien.chriqui/spendesk-mcp-server/dist/index.js"]

1. 完全重新启动Claude桌面 （退出应用程序，然后重新打开）。出现MCP工具（图标🔨 在输入区域旁边）。

多租户选项 ：在HTTP中，客户端可以发送 Bearer client_credentials:... 而不在服务器上存储标识符；在stdio中，凭证保留在 env 如上所述。

Serveur HTTP（流式传输）——ChatGPT等。

使用MCP代理 ChatGPT，HTTP客户端或在HTTP流中使用MCP的平台，启动HTTP服务器：

export SPENDESK_CLIENT_ID=...
export SPENDESK_CLIENT_SECRET=...
npm run start:http
# écoute par défaut sur http://0.0.0.0:3000

HTTP的有用变量：

终点：

• POST/mcp -JSON-RPC（初始化+消息）。服务器返回一个头 mcp-session-id 在第一初始化请求时。
• GET/mcp -SSE流（发送报头 mcp-session-id).
• 删除/mcp -关闭会话（标题 mcp-session-id).
• GET/doc -重定向到文档（Mintlify）。定义 DOCS_URL 对于目标URL；否则，将显示信息页面。
• GET/用法 -MCP使用仪表板（每日音量、顶级工具、上次通话）。可选：定义 USAGE_UI_SECRET 以保护访问。

HTTP身份验证和部署

L接口 /ui 多租户模式（基本SQLite+API密钥）已被删除。\ 现在只能通过以下方式进行身份验证：

• des 客户提供的凭证 （客户端凭据OAuth2，或对于给定请求 持有者令牌 由客户端在HTTP头中传输-而不是通过 SPENDESK_API_TOKEN 服务器端），或
• des 环境变量 在服务器上配置。

客户提供的凭证（DUST/CLAUDE）

了 客户端id 等等 客户端密码 Spendesk可由客户在连接时提供，无需在铁路上硬拷贝：

• 持票人 : Authorization: Bearer client_credentials:.\

生成： node scripts/generate-dust-bearer.mjs 并将结果粘贴到承载字段中（例如，在灰尘中）。

• 标头 : X-Spendesk-Client-Id: 和 X-Spendesk-Client-Secret: .

然后服务器调用 POST /v1/auth/token 使用这些会话ID，并在401上自动更新令牌。

模式回退（环境变量）

如果未提供身份验证头，则服务器使用 只有 环境变量 客户端凭证 ：根据 SPENDESK_USE_DEMO, SPENDESK_CLIENT_ID + SPENDESK_CLIENT_SECRET （prod）ou SPENDESK_CLIENT_ID_DEMO + SPENDESK_CLIENT_SECRET_DEMO （演示）。服务器调用POST /v1/auth/token 与流 client_credentials.

Spendesk API的URL选择如下： SPENDESK_USE_DEMO （沙盒与公共API）。这允许MCP在 模式单租户，用手指戳你。

部署（Docker、PaaS）

码头工人

docker build -t spendesk-mcp-server .
docker run -p 3000:3000 \
  -e SPENDESK_CLIENT_ID=your_client_id \
  -e SPENDESK_CLIENT_SECRET=your_client_secret \
  spendesk-mcp-server

部署在铁路上

1. 创建项目 : railway应用程序 → 新项目→ 从GitHub仓库部署。
2. 构建 ：铁路检测到 Dockerfile 并构建图像，或使用 railway.json （构建： npm ci && npm run build，开始： node dist/server-http.js）的。如果存在Dockerfile，则优先使用它。
3. 环境变量 （设置→ 变量）：

- 环境 : SPENDESK_USE_DEMO = true 对于演示沙盒， false 或者未为prod定义。 - Auth Spendesk （所选环境的至少一个选项）： - 客户端凭据prod : SPENDESK_CLIENT_ID + SPENDESK_CLIENT_SECRET （当 SPENDESK_USE_DEMO 最假的）。 - 客户凭据démo : SPENDESK_CLIENT_ID_DEMO + SPENDESK_CLIENT_SECRET_DEMO （当 SPENDESK_USE_DEMO=true). - 或者服务器上没有变量，如果 每个 客户端发送 Authorization: Bearer client_credentials:... （或Spendesk标题）。 - ALLOWED_HOSTS （推荐）-允许DNS重新绑定验证的主机，例如： votre-service.railway.app （无 https://）的。您可以在第一次部署后恢复域（设置→网络→生成域）。

1. 域名 ：设置→ 网络→ 生成域。L'URL MCP血清 https://.railway.app/mcp.
2. 检查 : MCP_BASE_URL=https://.railway.app node scripts/test-mcp-http.mjs

渲染/Fly.io

• 部署存储库（构建： npm ci && npm run build，开始： node dist/server-http.js).
• 定义 SPENDESK_CLIENT_ID + SPENDESK_CLIENT_SECRET （或仅按请求提供凭证），以及 ALLOWED_HOSTS 用于应用程序的公共域。
• MCP服务器的URL： https://votre-app.onrender.com/mcp （ou ton domaine）+ /mcp).

在铁路上部署文档（Mintlify）

DOC（Mintlify）在 spendesk-mcp-docs/.要将其作为第二项服务部署在铁路上：创建 新 来自同一仓库的铁路服务，定义 根目录 上 spendesk-mcp-docs然后部署。构建执行 npm ci，start启动中继Mintlify服务器的代理。在设置→网络中生成域。看 spendesk-mcp-docs/README.md 关于细节。

配置ChatGPT（或可流式HTTP MCP客户端）

在MCP客户端的接口或配置中（例如，使用MCP的ChatGPT或OpenAI响应API）：

1. 服务器URL : https://votre-domaine.com/mcp （部署的公共URL+ /mcp).
2. 授权 （可选）：

• 客户凭证（由客户提供，铁路上没有硬拷贝） ：要使DUST/CLAUDE将客户端ID和客户端秘密spendesk发送到连接：

- 选项A——不记名 ：持票人= client_credentials:.使用以下方法生成令牌： node scripts/generate-dust-bearer.mjs 然后将输出粘贴到灰尘承载器字段中。 - 选项B——标题 ：添加标题 X-Spendesk-Client-Id 和 X-Spendesk-Client-Secret （灰尘中的“网络和标题”部分）。在这种情况下不需要承载。

• 持有者令牌 ：客户端可以通过以下方式发送Spendesk API令牌： Authorization: Bearer 对于此会话（服务器上没有等效的环境变量）。
• 模式回退 ：如果未发送报头，服务器将使用 SPENDESK_CLIENT_ID + SPENDESK_CLIENT_SECRET （或演示对）在环境中。
• 要保护访问，请在前面放置反向代理（身份验证、API密钥） /mcp.

客户端首先使用JSON-RPC主体发送POST请求 initialize，收回 mcp-session-id 在响应头中，然后将此会话ID用于后续请求和SSE GET流。

dust（app.dust.tt）-连接列出了工具，但spendesk调用失败

频繁检查表：

1. 沙盒与触针（原因1） ：les client_id / client_secret 行李箱/沙箱 必须与 beta-sandbox.api.trunk.spendesk.services.关于 铁路，si SPENDESK_USE_DEMO 你缺席了吗 false，到目前为止，服务器使用 public-api.spendesk.com 即使Dust发送了无效的沙盒→令牌ID或API调用。 通过两个选项之一进行更正：

- A. 铁路变量： SPENDESK_USE_DEMO=true （可能 SPENDESK_BASE_URL 如果您使用其他演示URL）， 哦 - B 在灰尘中→ 网络和接头，添加第三个标题： X-Spendesk-Use-Demo = true （ou 1）的。因此，MCP会话使用沙盒主机进行OAuth流和工具， 无 更改部署的其余部分。 *（服务器也接受 Spendesk-Use-Demo 如果UI灰尘没有前缀 X-.)*

1. 熊视频 ：你可以离开这个领域 持有者令牌 使用视频 X-Spendesk-Client-Id + X-Spendesk-Client-Secret不要放空格或假令牌。

1. Spendesk示波器 ：倾倒 spendesk_get_suppliersOAuth应用程序必须至少具有 supplier:read （et experimental:supplier:manage 用于创建/存档）。在Spendesk中检查 *设置→集成→API访问管理*.

1. 轻测试 ：请助手打电话 spendesk_get_filter_options 哦 spendesk_get_wallet_summary 如果它通过了，但供应商没有，这几乎肯定是一个问题 范围 你会URL d‘API （第1点）。

1. 同步器 ：更改URL或铁路变量后，单击 同步 在灰尘中的MCP工具上，然后重试。

测试部署的MCP（或本地）

脚本检查HTTP服务器是否正确响应（get/、initialize、tools/list、tools/call）：

# Test en local (serveur : npm run start:http ; .env avec SPENDESK_CLIENT_ID + SPENDESK_CLIENT_SECRET)
node scripts/test-mcp-http.mjs

# Test vers une URL déployée (même paire dans l’environnement pour construire Bearer client_credentials)
MCP_BASE_URL=https://votre-app.up.railway.app node scripts/test-mcp-http.mjs

如果成功： ✓ MCP HTTP test passed.

测试员分析复合数据（分析支出、记账、应付账款账龄、现金流）

一个脚本调用5个复合工具以验证它们是否正确响应：

# 1. Démarrer le serveur (dans un premier terminal)
npm run start:http

# 2. Dans un second terminal (même .env / client id+secret que le serveur, ou headers client_credentials)
node scripts/test-composite-tools.mjs

脚本依次调用： spendesk_analyze_spend, spendesk_get_bookkeeping_pipeline, spendesk_get_payment_status, spendesk_get_ap_aging, spendesk_get_cash_flow_forecast 在一个示例期间（2026年1月）。如果出现错误（令牌、404、超时快照），将显示每个工具的消息。

要测试应付快照和分页：

FROM_DATE=2026-02-26 node scripts/test-payables-from-date.mjs

短时SQLite分析（模式类型Ramp）

您可以将Spendesk数据加载到 内存中的SQLite数据库 每个会话，然后让LLM执行只读SQL查询。适用于交叉分析、汇总和会计报告。

LLM的推荐工作流：

1. 呼叫 spendesk_load_sqlite_data 使用数据集（payables, settlements, suppliers, purchase_orders）对于应付款项，日期范围（from_date, to_date).
2. 呼叫 spendesk_list_loaded_tables 以确认模式和行数。
3. 呼叫 spendesk_execute_sql_query 使用分析SQL查询（仅选择/使用；结果上限为1000行）。
4. 呼叫 spendesk_clear_sqlite_tables 在分析结束时释放内存。

可用工具：

安全： 只有以开头的请求 SELECT 哦 WITH 被接受；关键词 INSERT, UPDATE, DELETE, DROP, CREATE, ALTER 被拒绝。

SQL查询示例（加载应付账款或其他表后）：

-- 1. Top 10 fournisseurs par montant (EUR)
SELECT supplier_name, SUM(amount_eur) AS total_eur, COUNT(*) AS nb
FROM payables GROUP BY supplier_name ORDER BY total_eur DESC LIMIT 10;

-- 2. Dépenses par centre de coût
SELECT cost_center, SUM(amount_eur) AS total_eur FROM payables
WHERE cost_center IS NOT NULL AND cost_center != '' GROUP BY cost_center ORDER BY total_eur DESC;

-- 3. Factures non payées (unpaid)
SELECT id, supplier_name, amount_eur, payable_date, due_date FROM payables
WHERE payment_status = 'unpaid' ORDER BY due_date;

-- 4. Répartition par type de payable (invoice, card, expense…)
SELECT payable_type, COUNT(*) AS nb, SUM(amount_eur) AS total_eur
FROM payables GROUP BY payable_type ORDER BY total_eur DESC;

-- 5. Tendance mensuelle (montant par mois)
SELECT strftime('%Y-%m', payable_date) AS month, SUM(amount_eur) AS total_eur, COUNT(*) AS nb
FROM payables GROUP BY month ORDER BY month;

-- 6. Payables non encore exportés en compta (bookkeeping_status = created)
SELECT supplier_name, SUM(amount_eur) AS total_eur FROM payables
WHERE bookkeeping_status = 'created' GROUP BY supplier_name ORDER BY total_eur DESC;

-- 7. Montant par devise d’origine
SELECT original_currency, SUM(amount_eur) AS total_eur, COUNT(*) AS nb
FROM payables GROUP BY original_currency ORDER BY total_eur DESC;

-- 8. Settlements : montant par état (processing, completed, failed, pending)
SELECT state, COUNT(*) AS nb, SUM(amount_eur) AS total FROM settlements GROUP BY state;

-- 9. Top fournisseurs sur les purchase orders
SELECT supplier_name, COUNT(*) AS nb_po, SUM(total_amount) AS total FROM purchase_orders
GROUP BY supplier_name ORDER BY total DESC LIMIT 10;

-- 10. Jointure payables + type pour analyse détaillée
SELECT payable_type, bookkeeping_status, COUNT(*) AS nb, SUM(amount_eur) AS total_eur
FROM payables GROUP BY payable_type, bookkeeping_status ORDER BY total_eur DESC;

工具（Tools）

Spendesk API的所有主要端点都公开为MCP工具：

支出数据

• spendesk_get_settlements –设置列表（通过过滤器 filters)
• spendesk_update_settlement_state –更新结算状态
• spendesk_get_bank_fees –银行费用（chargedFrom / chargedTo 浇注限制器日期 filters）的。看 出口银行手续费→ NetSuite 用于每日流量日志记录。
• spendesk_create_payables_snapshot / spendesk_get_payables_snapshot –应付账款快照（创建：公共API过滤器；检索：分页） page, perPage 最大100， filters 在喀麦隆）
• spendesk_get_payable / spendesk_get_payable_attachments –应付详情和附件
• spendesk_update_payable_bookkeeping –应付账款的会计状态（同步ERP）
• 报告（交钥匙答复） : spendesk_get_spend_dashboard –仪表板支出（按成本中心/类别/费用账户细分）； spendesk_get_top_suppliers_by_spend –按支出和应付/结算的前N名供应商； spendesk_get_purchase_orders_and_payables_export –出口POS+按期限支付，按供应商绑定
• spendesk_get_wallet_loads / spendesk_get_wallet_summary –充值和汇总钱包。看 导出钱包加载→ NetSuite 用于每日流量日志记录。

分析的

• spendesk_get_analytical_fields / spendesk_get_analytical_values –分析字段和值（先调用 spendesk_get_analytical_fields 为了得到 fieldId，然后 spendesk_get_analytical_values 与论点 fieldId)
• spendesk_get_cost_centers / spendesk_create_cost_center / spendesk_update_cost_center / spendesk_delete_cost_center –成本中心
• spendesk_get_expense_categories –支出类别

会计

• spendesk_get_journal_csv –会计导出的CSV内容
• spendesk_create_accounting_export –创建会计导出
• spendesk_get_journal_templates –报纸模板

供应商和用户

• spendesk_get_suppliers / spendesk_get_supplier –供应商（专用过滤器： ids, updatedBefore/After, createdBefore/After, bankCountry, iban, vatNumber, isArchived, + filters 通用）
• spendesk_create_suppliers –创建供应商（职位 /v1/suppliers，兵团=物体画面 supplierToCreate ；范围 experimental:supplier:manage)
• spendesk_update_supplier / spendesk_update_suppliers / spendesk_set_supplier_archive_status –供应商更新/存档（补丁）
• 生命周期演示 : node scripts/demo-supplier-lifecycle.mjs （创建→更新→存档；然后2个供应商相同增值税，过滤器 vatNumber，最近的存档）。需要客户凭证 experimental:supplier:manage 和 SPENDESK_USE_DEMO=true 这是树干沙箱。
• 烟雾沙盒（API直接、主干） : npm run test:sandbox-api 哦 node scripts/test-sandbox-direct-api.mjs -打电话 GET /v1/suppliers, GET /v1/purchase-orders, GET /v1/users, GET /v1/cost-centers 上 SPENDESK_BASE_URL 或者演示沙盒。使用 客户端凭证 (SPENDESK_API_TOKEN 在npm脚本中清空）：在沙盒上 SPENDESK_API_TOKEN “prod”或expired通常返回 401.可选： SUPPLIER_IDS=id1,id2 要重放过滤器： ids= 就像邮递员一样。
• 批量供应商（API直接供应商） : node scripts/test-supplier-bulk-operations.mjs -与邮递员收藏相同的流程 postman/Spendesk-Suppliers-Bulk.postman_collection.json （导入+步骤： postman/README.md).
• 列表+存档/取消存档 : npm run test:suppliers-archive-cycle -页面聚合 GET /v1/suppliers?isArchived=false，拿着 10 最近由 createdAt （客户端排序：API不提供 sort），然后 PATCH /v1/experimental/suppliers/:id/status （存档，然后取消存档），如 spendesk_set_supplier_archive_status.变量： SUPPLIER_ARCHIVE_TEST_COUNT, SUPPLIER_ARCHIVE_TEST_MAX_PAGES, SUPPLIER_ARCHIVE_TEST_PATCH_DELAY_MS （缺陷800）以限制 429, SUPPLIER_ARCHIVE_TEST_DRY_RUN=1 仅用于列表。范围 supplier:read + experimental:supplier:manage.
• 取消存档IDS列表 （例如，在中断测试后）： SUPPLIER_IDS=id1,id2,... node -r dotenv/config scripts/unarchive-suppliers-by-ids.mjs — PATCH .../status 与 isArchived: false，延迟+重试 429 (SUPPLIER_UNARCHIVE_DELAY_MS).
• 通过MCP（stdio）的相同存档/取消存档流 : npm run test:mcp-suppliers-archive-cycle — spendesk_get_suppliers → spendesk_set_supplier_archive_status → spendesk_get_supplier （变量 SUPPLIER_MCP_ARCHIVE_*, SUPPLIER_MCP_ARCHIVE_DRY_RUN=1）的。如果部分存档后出错，则回滚取消存档。
• 完整的供应商表（所有OpenAPI字段+读取/补丁分析） : node scripts/test-supplier-full-attributes.mjs --关系和图表属性： docs/supplier-full-attributes.md.
• spendesk_get_users / spendesk_get_user –用户（通过过滤器 filters)

网络钩子

• spendesk_create_webhook / spendesk_get_webhooks / spendesk_get_webhook / spendesk_update_webhook / spendesk_delete_webhook –Webhook的管理

采购订单

• spendesk_get_purchase_orders / spendesk_create_purchase_order –列表和创建。列表：对齐的过滤器 获取采购订单.创造： 创建采购订单.
• spendesk_get_purchase_order –按ID详细信息（获取采购订单），消毒响应。
• spendesk_cancel_purchase_order / spendesk_close_purchase_order – 取消 / 关闭 （范围 experimental:purchase-order:write). Spendesk业务规则 ：一个PO不能 取消 奎西 没有发票 与之无关；一个PO不能 闭合 奎西 全部 相关发票包括： 支付.
• 版本（补丁） ：此存储库中记录的公共API未公开-没有更新PO MCP工具。
• 测试 : npm run test:mcp-po （stdio MCP：创建→ get → 取消→ 创建B→ 关闭）avec .env ; npm run test:po-api 对于直接HTTP调用中的相同场景（scripts/test-purchase-orders-api.mjs).

短暂的SQLite（分析SQL）

• spendesk_load_sqlite_data –将游戏（应付账款、结算、供应商、采购订单）加载到内存中的SQLite表中。参数： dataset, from_date, to_date （必须支付）。
• spendesk_execute_sql_query –执行只读SQL查询（SELECT或WITH）。参数： sql结果限制为1000行。
• spendesk_list_loaded_tables –列出加载了模式（列、类型）和行数的表。
• spendesk_clear_sqlite_tables –删除表（table_names）或者全部为空。

流/集成

• 出口银行手续费→ NetSuite -在NetSuite会计分录中记录银行费用（OtherFee/FXFee）的每日日志，包括每日批量和幂等性。
• 导出钱包加载→ NetSuite -在NetSuite会计分录中记录钱包充值（银行转账→Spendesk），每个负载一个JE，具有幂和选项 WALLET_LOAD_AMOUNT_UNIT （美分对欧元）。

API发现/参考

• spendesk_get_api_reference –返回 API参考 ：端点列表（HTTP方法、路径）、参数（查询、路径、主体）、关联MCP工具的名称和字段 documentation （留置权 developer.spendesk.com）当可用时。当询问“端点是什么”时使用？“，”设置的参数是什么？“采购订单过滤器”，“API结构”。可选： mcpTool （例如。 spendesk_get_settlements)ou path （例如。 payables, purchase-orders）用于过滤。

列出项目（结算、供应商、采购订单、银行费用、钱包负载等）的工具接受显式分页 page （缺陷1）和 perPage.根据端点，服务器自动映射到预期的API参数（perPage 哦 pageSize例如供应商）。他们也接受 通用过滤器 通过参数 filters （具有任何Spendesk API查询参数的对象，例如： { from: '2024-01-01', to: '2024-12-31', state: 'completed' }). spendesk_get_payables_snapshot 还支持 page 和 perPage 对快照的应付账款进行分页（例如，以30/页的速度在约40页上支付1177笔）。

交钥匙答案（Claude/Dust）

客户可以问 只有一次 Claude或Dust中的三个自然语言问题之一，并获得 正确、准确和结构良好的答案 （Markdown表，章节），无需指定工具或重新格式化。

映射问题→ outil

公约终止日期 2026年第一季度= from: 2026-01-01, to: 2026-03-31 ；2026年1月= from: 2026-01-01, to: 2026-01-31.

建议的答复格式

• 仪表板支出 （之后 spendesk_get_spend_dashboard）：摘要（期间、总计、货币）；Markdown表“按成本中心”、“按支出类别”、“按费用账户”（列：名称/ID、金额、项目数量）。
• 顶级供应商 （之后 spendesk_get_top_suppliers_by_spend）：主表（等级、供应商、总金额、货币）；对于每个供应商（或根据要求）：应付款项/结算清单（ID、金额、日期）。
• 出口订单+应付款项 （之后 spendesk_get_purchase_orders_and_payables_export）：该期间的POS和应付金额；POS和应付账款的表格或清单；按供应商分组（如果有用）。

Claude/Dust说明（复制和粘贴）

您可以将以下块粘贴到 项目说明 （克劳德）或 运河系统 （灰尘）让助手选择正确的工具并格式化答案：

Pour les questions sur le spend (dashboard, répartition par cost center / catégorie / compte de charge), utilise l’outil spendesk_get_spend_dashboard avec from/to selon la période demandée (Q1 = 2026-01-01 à 2026-03-31, janvier = 2026-01-01 à 2026-01-31). Présente le résultat en tableaux Markdown avec les sections par cost center, par catégorie, par compte de charge.

Pour le top 10 fournisseurs par spend, utilise spendesk_get_top_suppliers_by_spend. Affiche un tableau classé et les payables/settlements associés pour chaque fournisseur.

Pour l’export des POs et payables d’une période, utilise spendesk_get_purchase_orders_and_payables_export. Présente les POs et payables sous forme de tableaux, avec regroupement par fournisseur si utile.

故障排除：“应付API 404”或“结算400”

如果Dust或Claude回答 付费API返回404 欧奎 定居点重新开放400 :

• 404应付款项\

应付账款API（快照/供应商发票）不适用于您的帐户。可能原因：

- Spendesk计划 ：应付账款通常保留给高级/企业优惠（发票/应付账款模块）。 - 范围 ：API密钥必须具有范围 payable:read （在中激活 *设置>集成>API访问管理*). - 在Spendesk界面（报告、供应商发票）中检查：如果您无法访问应用程序中的应付账款，API也不会公开它们。

• 400个定居点\

无效请求（参数或格式）。检查过滤器的过去值（ISO日期，无未知参数） paidFrom, clearedFrom, clearedTo, exportedAfter如果错误仍然存在，请联系Spendesk支持。

• 500内部服务器错误\

错误 服务器端Spendesk （不在MCP中）。API服务器由于内部原因崩溃或拒绝请求。要做的事情：

1. 验证身份验证 ：客户提供的客户凭证或代币承载者必须有效，并具有必要的范围（例如，如果您调用POS，则访问采购订单）。 1. 检查环境 ：在演示中（SPENDESK_USE_DEMO=true），演示API可能不支持所有端点（如采购订单）。 1. 请稍后再试 ：500可以是临时的（Spendesk事件）。几分钟后重试。 1. 看细节 ：自最新版本以来，错误消息包括API响应体的摘录（Body: ...）-这可能表明原因（例如，“未启用功能”、“过滤器无效”）。 1. 联系Spendesk ：如果错误在具有有效令牌的PROD帐户上重复，请打开带有端点、参数和消息/响应正文的Spendesk支持票证。

规避 ：只要不可用，MCP就无法计算“按支出分列的顶级供应商”或“仪表板支出”报告。您可以使用Spendesk报告（报告→按时间段筛选）或启用SpendeskPay模块/Scopes以解锁API。

了解API的结构

客户（Claude、Dust等）可以 询问MCP 要了解公开的Spendesk API的端点、参数和结构：

• 工具 spendesk_get_api_reference ：返回完整引用（baseURL、方法端点、路径、查询参数、路径参数、bodyparams、mcptool、responseNote）。可选参数： mcpTool 对于给定工具（例如。 spendesk_get_settlements), path 按路径过滤（例如。 settlements).
• 资源 spendesk://api-reference ：相同的只读内容（非常适合将其注入上下文或阅读资源的客户端）。

向导可以通过调用工具或读取资源来解决的问题示例：“设置API接受哪些参数？“，”列出应付款项的端点是什么？“端点采购订单的结构是什么？“。

资源（资源）

只读数据，用于为仪表板或上下文提供信息：

资源返回JSON（UTF-8）。

参考API

官方文件： Spendesk公用API.

许可证

MIT。