yuki MCP

小雪

A. 模型上下文协议 将AI代理连接到的（MCP）服务器 由纪 通过Yuki的SOAP API进行会计。

使用Node.js、TypeScript和 @modelcontextprotocol/sdk.

______________________________________________________________________

安装

npm install @codemill-solutions/yuki-mcp

然后将其添加到MCP主机配置中（例如。 claude_desktop_config.json):

{
  "mcpServers": {
    "yuki": {
      "command": "node",
      "args": ["node_modules/@codemill-solutions/yuki-mcp/dist/index.js"],
      "env": {
        "YUKI_API_KEY": "your-api-key-here",
        "YUKI_DOMAIN_ID": "your-administration-guid-here"
      }
    }
  }
}

______________________________________________________________________

先决条件

• Node.js 20+
• 启用API访问的Yuki帐户
• 您的Yuki API密钥（Yuki→ 设置→ API)

______________________________________________________________________

设置

1.安装依赖项

npm install

2.配置环境变量

cp .env.example .env

编辑 .env:

YUKI_API_KEY=your-api-key-here
YUKI_DOMAIN_ID=your-administration-guid-here  # optional at startup

YUKI_DOMAIN_ID 可以留空——服务器在没有它的情况下启动。调用 get_administrations 要发现正确的GUID，请通过 administrationId 单个工具上的参数。

3.建造

npm run build

4.连接到MCP主机

添加到MCP主机配置中（例如。 claude_desktop_config.json):

{
  "mcpServers": {
    "yuki": {
      "command": "node",
      "args": ["/absolute/path/to/yuki-mcp/dist/index.js"],
      "env": {
        "YUKI_API_KEY": "your-api-key-here",
        "YUKI_DOMAIN_ID": "your-administration-guid-here"
      }
    }
  }
}

______________________________________________________________________

多管理支持

如果你能做到 多届Yuki政府 （每个都有自己的API密钥），您可以提供一个JSON文件，该文件映射 administrationId 到其对应的API密钥。然后，服务器会自动对每次管理进行身份验证，不需要单个共享密钥。

密钥文件格式

{
  "a1b2c3d4-0000-0000-0000-000000000001": "api-key-for-admin-1",
  "a1b2c3d4-0000-0000-0000-000000000002": "api-key-for-admin-2"
}

路径解析（第一场比赛获胜）

环境变量

YUKI_API_KEYS_FILE=/path/to/your/api-keys.json

当存在密钥文件时， YUKI_API_KEY 变为可选--文件密钥用于所有特定于管理的工具调用，以及 YUKI_API_KEY （如果设置）作为不针对特定管理的工具的后备方案（例如。 get_administrations).

如果两者都没有 YUKI_API_KEY 启动时找不到密钥文件，服务器会记录一个警告，但会继续运行——工具在调用时会返回一个错误。

______________________________________________________________________

可用工具（30）

行政部门

关系

销货

购货发票

交易和银行

会计

会计信息

从中获得更丰富的只读视图 AccountingInfo.asmx 服务——标准不提供 Accounting.asmx.

文件

后台办公室

______________________________________________________________________

测试

选项1-MCP检查员（工具级，无LLM）

npm run inspect

在以下位置打开浏览器UI http://localhost:5173 在那里，您可以调用单个工具并检查原始响应。

选项2——代理测试工具（带Claude）

运行一个完整的代理循环：Claude对任务进行推理，调用工具，并返回最终答案——就像AI代理使用此MCP一样。

将您的Anthropic API密钥添加到 .env:

ANTHROPIC_API_KEY=sk-ant-...

然后运行一个场景：

npm run agent                                              # default: get_administrations
npm run agent -- --scenario outstanding-invoices
npm run agent -- --scenario search-relations --arg "Bedrijf BV"
npm run agent -- --scenario gl-accounts
npm run agent -- --scenario bank-transactions --arg "1200"
npm run agent -- --scenario full-workflow

可用场景： get-administrations, search-relations, outstanding-invoices, outstanding-payables, gl-accounts, bank-transactions, full-workflow.

______________________________________________________________________

建筑

src/
├── index.ts                  # Entry point — loads env + keys file, registers tools, starts stdio transport
├── yuki-client.ts            # SOAP client: per-key session cache, envelope builder, axios HTTP, fast-xml-parser
└── tools/
    ├── administrations.ts    # get_administrations, get_administration_id
    ├── relations.ts          # search_relations, upsert_contact
    ├── invoices.ts           # get_sales_invoices, get_purchase_invoices,
    │                         # process_sales_invoice, process_purchase_invoice
    ├── transactions.ts       # get_transactions, get_transaction_details, process_journal
    ├── accounting.ts         # get_gl_accounts, get_gl_accounts_fiscal, get_net_revenue
    ├── accounting-info.ts    # get_gl_account_scheme, get_period_table,
    │                         # get_gl_transactions_detailed, get_transaction_document,
    │                         # get_start_balances, get_missing_invoices
    ├── documents.ts          # upload_document, upload_document_from_path,
    │                         # get_document_folders, list_documents, search_documents,
    │                         # get_document, download_document, get_cost_categories
    └── backoffice.ts         # get_workflow, get_outstanding_questions

scripts/
└── test-agent.ts             # Agent test harness (Claude + MCP client loop)

认证流程

Yuki使用两步身份验证模式：

1. Authenticate(accessKey) → 返回临时 sessionID
2. 所有后续通话都包括 sessionID

YukiClient.getSessionID(adminId?) 透明地处理这个问题。当与A通话时 administrationId，它从加载的密钥映射中解析匹配的API密钥。在进程的生命周期内，每个API键缓存会话ID- Authenticate 每个键只调用一次，而不是每个工具调用一次。

注： Yuki服务中的参数大小写不同-- sessionId （小写d）on Sales.asmx 和 Purchase.asmx; sessionID （大写D）on Accounting.asmx, AccountingInfo.asmx, Contact.asmx，以及 Archive.asmx。这是按工具处理的。

XML文档

编写工具(process_sales_invoice, process_purchase_invoice, process_journal, upsert_contact)将结构化数据作为XML字符串传递给Yuki xmlDoc SOAP参数。这 XmlValue 包装器确保此XML原始嵌入（不是实体编码）在SOAP信封中。所有用户提供的值都是通过XML转义的 escapeXml().

______________________________________________________________________

费率限制

Yuki执行 每天1000个API请求 （可升级至5000至10000）。每次工具调用都是一个请求。会话ID已缓存，因此 Authenticate 每个服务器进程每个API键只调用一次，而不是每个工具调用一次。

设计代理工作流，一次性获取广泛列表并从代理的上下文窗口引用它们，而不是在每一步都重新获取。

______________________________________________________________________

故障排除

______________________________________________________________________

关于CodeMill解决方案

CodeMill解决方案 是一家总部位于荷兰的荷兰软件公司。我们构建智能、可扩展和定制的解决方案，帮助组织发展、优化流程并实现其数字化目标。

我们的服务包括：

• 定制应用 --门户、仪表板、业务软件和真正增值的完全定制的平台。
• API集成 -通过智能API连接将您的应用程序与其他系统和外部平台连接。
• 移动应用 --iOS和Android应用程序作为web应用程序的逻辑扩展。

yuki-mcp 是我们的开源集成之一，使Yuki的会计平台可以通过模型上下文协议供人工智能代理访问。

📧 info@codemill.dev 🌐 codemill.dev 💼 领英 🐙

______________________________________________________________________

许可证

麻省理工学院——见 许可证.