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