@archiesun/yonsuit-fin-mcp

v1.1.5

Published

4 days ago

用友做账MCP服务器 - 基于Model Context Protocol的用友财务系统对接服务

0High
0Medium
0Low

archiesun

yonyou mcp model-context-protocol accounting finance erp

用友做账MCP服务器

基于 Model Context Protocol (MCP) 的用友财务系统对接服务，为AI助手提供用友做账能力。

项目简介

本项目是一个MCP（Model Context Protocol）服务器实现，旨在为AI助手（如Claude、ChatGPT等）提供与用友财务系统交互的能力。通过标准化的MCP协议，AI助手可以调用各种财务操作工具，实现凭证管理、科目查询、账簿查询等功能。

核心特性

完整的MCP协议支持 - 完全兼容MCP SDK，支持工具、资源、提示词管理
精简高效的工具集 - 10个核心工具，覆盖凭证和档案管理
自动签名和认证 - 内置用友API签名机制，自动处理Token管理
智能初始化流程 - 自动验证URL和Token，确保API调用成功
类型安全 - 使用TypeScript开发，提供完整的类型定义
完善的错误处理 - 详细的错误信息和日志记录

系统要求

Node.js >= 20.0.0
npm >= 9.0.0

快速开始

1. 安装依赖

npm install

2. 配置环境变量

复制环境变量示例文件：

cp .env.example .env

编辑 .env 文件，填入实际的用友API配置：

# 用友API配置（必填）
YONYOU_APP_KEY=your_app_key_here
YONYOU_APP_SECRET=your_app_secret_here
YONYOU_TENANT_ID=your_tenant_id_here

# 数据中心域名（可选，不填则自动获取）
YONYOU_DATA_CENTER_DOMAIN=

# 用户ID（可选，仅用户认证模式需要）
YONYOU_USER_ID=your_user_id_here

3. 构建项目

npm run build

4. 运行服务

开发模式：

npm run dev

生产模式：

npm start

在AI助手中配置

Claude Desktop配置

在Claude Desktop的配置文件中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yonsuit-fin-mcp": {
      "command": "npx",
      "args": ["-y", "@archiesun/yonsuit-fin-mcp"],
      "env": {
        "YONYOU_APP_KEY": "your_app_key",
        "YONYOU_APP_SECRET": "your_app_secret",
        "YONYOU_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

使用npx直接运行

npx -y @archiesun/yonsuit-fin-mcp

全局安装

npm install -g @archiesun/yonsuit-fin-mcp
yonsuit-fin-mcp

MCP工具列表

本服务器提供10个核心工具，分为三大类：

凭证管理（4个工具）

| 工具名称 | 描述 | 必填参数 | |---------|------|---------| | query_voucher_list | 查询凭证列表，支持多条件筛选和分页 | accbookCode | | query_voucher_detail | 查询凭证详情，包含所有分录明细 | voucherId | | save_voucher | 创建凭证 | accbookCode, voucherTypeCode, bodies | | delete_voucher | 删除凭证（支持批量） | ids |

档案管理（5个工具）

| 工具名称 | 描述 | 必填参数 | |---------|------|---------| | account_query | 查询科目列表 | - | | accountbook_query | 查询账簿列表 | - | | vouchertype_query | 查询凭证类型列表 | - | | currency_query | 查询币种列表 | - | | customdoc_query | 查询自定义档案（部门、供应商、客户等） | custdocdefid 或 custdocdefid___code |

结账管理（1个工具）

| 工具名称 | 描述 | 必填参数 | |---------|------|---------| | check_period_status | 查询结账状态 | org, accPeriod |

初始化流程

系统在调用任何业务接口前，会自动执行以下验证流程：

1. 验证必填配置（appKey, appSecret, tenantId）
2. 自动获取数据中心域名（gatewayUrl 和 tokenUrl）
3. 获取并验证 Token 有效性
4. 验证成功后执行业务接口调用

注意：YONYOU_DATA_CENTER_DOMAIN 现在是可选配置。如果不填写，系统会自动通过用友API获取租户所在数据中心的域名。这确保了npx启动时API调用的成功率。

环境变量说明

必填配置

| 变量名 | 描述 | 示例 | |-------|------|------| | YONYOU_APP_KEY | 用友应用Key | your_app_key | | YONYOU_APP_SECRET | 用友应用Secret | your_app_secret | | YONYOU_TENANT_ID | 租户ID | your_tenant_id |

可选配置

| 变量名 | 描述 | 默认值 | |-------|------|--------| | YONYOU_DATA_CENTER_DOMAIN | 数据中心域名（不填则自动获取） | - | | YONYOU_USER_ID | 用户ID（仅用户认证模式需要） | - | | YONYOU_AUTH_TYPE | 认证类型 | app_auth | | YONYOU_TOKEN_CACHE_TTL | Token缓存时间(秒) | 7200 | | LOG_LEVEL | 日志级别 | info | | LOG_FORMAT | 日志格式 | json | | HTTP_TIMEOUT | HTTP超时时间(ms) | 30000 | | HTTP_MAX_RETRIES | 最大重试次数 | 3 |

开发指南

代码规范

npm run lint      # 代码检查
npm run format    # 代码格式化
npm run typecheck # 类型检查

测试

npm test              # 运行测试
npm run test:watch    # 监听模式
npm run test:coverage # 测试覆盖率

构建

npm run build    # 构建项目
npm run clean    # 清理构建产物

项目结构

yonyou-mcp/
├── src/
│   ├── config/          # 配置管理
│   ├── auth/            # 认证模块
│   ├── signature/       # 签名模块
│   ├── client/          # API客户端
│   ├── tools/           # MCP工具定义
│   ├── services/        # 业务服务
│   ├── utils/           # 工具函数
│   ├── types/           # 类型定义
│   ├── server/          # MCP服务器
│   └── index.ts         # 入口文件
├── dist/                # 编译输出
├── package.json
└── tsconfig.json

安全说明

所有API请求均需签名验证
敏感信息通过环境变量管理，不会记录到日志
Token自动缓存和刷新，避免频繁认证

许可证

MIT

更新日志

查看 CHANGELOG.md 了解版本更新历史。

贡献指南

欢迎提交Issue和Pull Request。在提交代码前，请确保：

代码通过所有测试
代码符合项目的代码规范
添加必要的文档和注释

技术支持

如有问题，请提交Issue或联系项目维护者。