Quickfile MCP

🚀 QuickFile MCP Server

QuickFile UK会計ソフトウェア用のモデルコンテキストプロトコルサーバーです。AIアシスタントに請求書、クライアント、購入、銀行取引、および財務報告への完全なアクセスを提供します。

✨ 主な機能

• QuickFile APIを網羅するための40以上のMCPツール
• クライアント管理：クライアントと連絡先の作成、検索、更新、削除
• 請求書管理：請求書、見積書、クレジットノートの作成；メールでの送信；PDFの取得
• 購入管理：仕入先からの購入請求書の記録と管理
• 仕入先管理：仕入先の完全なCRUD操作
• 銀行取引管理：銀行口座、取引、残高
• 財務報告：損益計算書、貸借対照表、VAT義務、債権債務残高表
• システム操作：アカウント詳細、イベントログ、メモ

🚀 クイックスタート

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"

💻 使用例

基本的な使用法

# クイックスタートの手順を実行することで、基本的な使用が可能になります。

高度な使用法

# 高度な使用法については、各種ツールの操作や、MCP Inspectorを使用した開発・デバッグなどがあります。

📦 インストール

上記のクイックスタートの手順を参照してください。

📚 ドキュメント

利用可能なツール

システム（3つのツール）

クライアント（7つのツール）

請求書（8つのツール）

購入（4つのツール）

仕入先（4つのツール）

銀行取引（5つのツール）

報告書（6つのツール）

APIのレート制限

QuickFileは、アカウントごとに1日あたり1000回のAPI呼び出しがデフォルトの制限です。この制限を引き上げる必要がある場合は、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. クライアント検索のテスト：quickfile_client_searchを{"companyName": "test"}で呼び出す
3. 報告書のテスト：quickfile_report_profit_lossを{"startDate": "2024-01-01", "endDate": "2024-12-31"}で呼び出す
4. 請求書一覧のテスト：quickfile_invoice_searchを{"invoiceType": "INVOICE"}で呼び出す

これは、以下の目的に推奨されるアプローチです。

• APIレスポンスの問題のデバッグ
• 新しいツールが正しく動作することの検証
• パラメータ検証のテスト
• エラーレスポンスの調査

貢献について

QuickFile APIドキュメント

QuickFile APIは、要素の順序と必須フィールドに厳格な要件があります。貢献する際は、以下のことを行ってください。

1. 常に公式のAPIスキーマを確認：https://api.quickfile.co.uk/
2. AI支援開発にContext7を使用：https://context7.com/websites/api_quickfile_co_uk
   • Context7はQuickFile APIドキュメント全体をインデックス化しています。
   • 正確なフィールド名、必須パラメータ、要素の順序を照会するために使用します。
   • 例：「Purchase_Searchの必須フィールドは何ですか？」

主要なAPIの癖

• 要素の順序が重要 - XMLスキーマの検証には特定のフィールド順序が必要です。
• 必須フィールドはエンドポイントによって異なる - ほとんどの検索エンドポイントでは、OrderResultsByとOrderDirectionが必須です。
• フィールド名が一貫性がない - 例：FromDate/ToDateとDateFrom/DateTo
• SearchParametersラッパー - ほとんどのエンドポイントでは、クエリパラメータをこのラッパーで囲む必要があります。
• NominalCodeの型 - 時には文字列、時には整数（スキーマを確認）

アーキテクチャ

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ドキュメント
• Model Context Protocol - AIツール統合のためのプロトコル仕様
• AI DevOps Framework - 包括的なAIインフラストラクチャ管理

📄 ライセンス

MITライセンス - 詳細については、LICENSEファイルを参照してください。

作成者: Marcus Quinn - Copyright © 2025