Quickfile MCP

🚀 QuickFile MCP 服务器

QuickFile MCP 服务器是专为 QuickFile UK 会计软件打造的模型上下文协议（MCP）服务器。借助该服务器，AI 助手能够全面访问发票开具、客户管理、采购记录、银行事务以及财务报告等功能，为会计工作提供更智能、高效的支持。

🚀 快速开始

1. 克隆并安装项目

cd ~/git
git clone https://github.com/marcusquinn/quickfile-mcp.git
cd quickfile-mcp
npm install
npm run build

2. 配置凭证

创建 QuickFile API 凭证：

mkdir -p ~/.config/.quickfile-mcp
cat > ~/.config/.quickfile-mcp/credentials.json << 'EOF'
{
  "accountNumber": "YOUR_ACCOUNT_NUMBER",
  "apiKey": "YOUR_API_KEY",
  "applicationId": "YOUR_APPLICATION_ID"
}
EOF
chmod 600 ~/.config/.quickfile-mcp/credentials.json

获取凭证的位置：

1. 账户编号：在 QuickFile 仪表盘的右上角可见。
2. API 密钥：进入账户设置 → 第三方集成 → API 密钥。
3. 应用程序 ID：进入账户设置 → 创建 QuickFile 应用 → 复制应用程序 ID。

3. 安装 OpenCode（若尚未安装）

OpenCode 是一款开源的 AI 编码助手，可在终端中运行，它支持像本项目这样的 MCP（模型上下文协议）服务器。

# 全局安装 OpenCode
npm install -g opencode

# 或者使用 npx 直接运行
npx opencode

更多安装选项和配置信息，请参阅 OpenCode 文档。

4. 配置 OpenCode

在 ~/.config/opencode/opencode.json 中添加以下内容：

{
  "mcp": {
    "quickfile": {
      "type": "local",
      "command": ["node", "/path/to/quickfile-mcp/dist/index.js"],
      "enabled": true
    }
  }
}

或者使用设置脚本：

./setup.sh opencode

5. 开始使用

重启 OpenCode 并尝试以下指令：

"Show me my QuickFile account details"
"List my recent invoices"
"Search for clients named 'Smith'"
"Get the profit and loss report for this year"

✨ 主要特性

• 40 多种 MCP 工具：全面覆盖 QuickFile API 的各项功能。
• 客户管理：支持创建、搜索、更新和删除客户及联系人。
• 发票开具：可创建发票、估算单、信用票据，通过电子邮件发送，并获取 PDF 格式文件。
• 采购管理：记录和管理来自供应商的采购发票。
• 供应商管理：提供完整的供应商创建、读取、更新和删除（CRUD）操作。
• 银行事务：管理银行账户、交易记录和账户余额。
• 财务报告：生成利润与损失报表、资产负债表、增值税义务报表和账龄分析报告等。
• 系统操作：查看账户详情、事件日志和备注信息。

📦 安装指南

克隆项目

cd ~/git
git clone https://github.com/marcusquinn/quickfile-mcp.git
cd quickfile-mcp

安装依赖

npm install

构建项目

npm run build

💻 使用示例

基础用法

在配置好凭证和 OpenCode 后，重启 OpenCode 并输入以下指令：

"Show me my QuickFile account details"

此指令将调用 quickfile_system_get_account 工具，获取 QuickFile 账户的详细信息。

高级用法

若要获取特定时间段内的利润与损失报表，可在 OpenCode 中输入：

"Get the profit and loss report from 2024-01-01 to 2024-12-31"

该指令将调用 quickfile_report_profit_loss 工具，并传入相应的日期参数，以生成指定时间段的利润与损失报表。

📚 详细文档

可用工具

系统工具（3 个）

客户工具（7 个）

发票工具（8 个）

采购工具（4 个）

供应商工具（4 个）

银行工具（5 个）

报告工具（6 个）

API 速率限制

QuickFile 每个账户默认的 API 调用限制为 每天 1000 次。如需提高此限制，请联系 QuickFile 支持团队。

开发相关

# 安装依赖
npm install

# 构建 TypeScript 代码
npm run build

# 在开发模式下运行（自动重新加载）
npm run dev

# 运行单元测试（快速，无 API 调用）
npm test

# 运行集成测试（需要凭证）
npm run test:integration

# 运行所有测试
npm run test:all

# 类型检查
npm run typecheck

# 代码检查
npm run lint

# 调试 API 调用（显示带有脱敏凭证的请求/响应）
QUICKFILE_DEBUG=1 node dist/index.js

使用 MCP Inspector 进行测试

在开发和调试过程中，建议使用官方的 MCP Inspector 工具，而非通过 AI 助手运行。该工具提供以下功能：

• 直接调用工具：使用自定义参数直接调用 MCP 工具。
• 实时查看响应：无需 AI 解释，直接查看完整的 JSON 响应。
• 快速迭代：无需等待 AI 处理请求。
• 调试可见性：查看原始服务器输出和错误信息。

快速开始

# 全局安装 MCP Inspector
npm install -g @modelcontextprotocol/inspector

# 使用此服务器运行检查器
npx @modelcontextprotocol/inspector node dist/index.js

然后在浏览器中打开 http://localhost:5173，进行以下操作：

1. 查看所有 37 个可用工具的列表。
2. 点击工具查看其输入模式。
3. 填写参数并执行。
4. 查看原始 JSON 响应。

示例测试工作流程

1. 测试账户访问：使用 {} 调用 quickfile_system_get_account。
2. 测试客户搜索：使用 {"companyName": "test"} 调用 quickfile_client_search。
3. 测试报告生成：使用 {"startDate": "2024-01-01", "endDate": "2024-12-31"} 调用 quickfile_report_profit_loss。
4. 测试发票列表：使用 {"invoiceType": "INVOICE"} 调用 quickfile_invoice_search。

此方法适用于以下场景：

• 调试 API 响应问题。
• 验证新工具是否正常工作。
• 测试参数验证。
• 调查错误响应。

贡献指南

QuickFile API 文档

QuickFile API 对元素顺序和必填字段有严格要求。在贡献代码时，请遵循以下步骤：

1. 始终查看官方 API 模式：访问 https://api.quickfile.co.uk/。
2. 使用 Context7 进行 AI 辅助开发：访问 https://context7.com/websites/api_quickfile_co_uk。
   • Context7 已对完整的 QuickFile API 文档进行索引。
   • 使用它查询确切的字段名称、必填参数和元素顺序。
   • 示例：“What are the required fields for Purchase_Search?”

关键 API 特性

• 元素顺序很重要：XML 模式验证要求特定的字段顺序。
• 必填字段因端点而异：大多数搜索端点需要 OrderResultsBy 和 OrderDirection。
• 字段命名不一致：例如，FromDate/ToDate 与 DateFrom/DateTo。
• SearchParameters 包装器：大多数端点需要在查询参数周围使用此包装器。
• 名义代码类型：有时为字符串，有时为整数（请查看模式）。

架构

quickfile-mcp/
├── src/
│   ├── index.ts           # MCP 服务器入口点
│   ├── api/
│   │   ├── auth.ts        # MD5 身份验证
│   │   └── client.ts      # HTTP 客户端
│   ├── tools/
│   │   ├── index.ts       # 工具注册表和导出
│   │   ├── utils.ts       # 共享实用程序（错误处理、日志记录）
│   │   ├── schemas.ts     # Zod 验证模式
│   │   ├── system.ts      # 系统工具
│   │   ├── client.ts      # 客户工具
│   │   ├── invoice.ts     # 发票工具
│   │   ├── purchase.ts    # 采购工具
│   │   ├── supplier.ts    # 供应商工具
│   │   ├── bank.ts        # 银行工具
│   │   └── report.ts      # 报告工具
│   └── types/
│       └── quickfile.ts   # TypeScript 类型
├── tests/
│   ├── unit/              # 单元测试（201 个测试）
│   └── integration/       # API 集成测试（16 个测试）
├── .agent/                # AI 助手文档
└── .opencode/agent/       # OpenCode 代理文件

凭证安全

• 凭证存储在 ~/.config/.quickfile-mcp/credentials.json 中。
• 文件权限应为 600（仅所有者可读写）。
• 切勿将凭证提交到版本控制系统。
• API 密钥可提供完全访问权限，请像对待密码一样妥善保管。
• Secretlint 会在提交前自动运行，以防止意外泄露机密信息。
• 可手动运行 npm run secretlint 扫描机密信息。

相关项目

• OpenCode：支持 MCP 的开源 AI 编码助手。
• QuickFile：英国会计软件。
• QuickFile API 文档。
• 模型上下文协议：AI 工具集成的协议规范。
• AI DevOps 框架：全面的 AI 基础设施管理框架。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

作者：Marcus Quinn - 版权所有 © 2025