invoicepdfs

InvoicePDFs MCP サーバー

AI エージェントに InvoicePDFs API をツールとして提供します。ドキュメントのレンダリング、電子請求書のコンプライアンスチェック、顧客の管理に加え、必要に応じて API の残りの機能にもアクセスできます。

これは公開 API の通常の HTTPS クライアントです。データベースも、デプロイが必要な追加サービスもなく、render.yaml に追加するものもありません。お使いのマシン上で動作します。

使い方

MCP クライアントの設定に追加します。Claude Desktop、Cursor、または stdio 経由で MCP に対応するその他のクライアントで使用できます。

{
  "mcpServers": {
    "invoicepdfs": {
      "command": "npx",
      "args": ["-y", "@invoicepdfs/mcp"],
      "env": { "INVOICEPDFS_API_KEY": "inv_live_..." }
    }
  }
}

キーは https://invoicepdfs.com で作成してください。ローカルサーバーを指定する場合は、INVOICEPDFS_BASE_URL でホストを上書きできます。

API キーにはスコープ制限がありません。 このサーバーに渡すキーを使うと、データの削除を含め、アカウントで可能な操作をすべて実行できます。これはキーの性質であり、このサーバーの問題ではありません。このサーバーに渡せる、より制限された認証情報はありません。MCP クライアントでは、各ツール呼び出しの前に引き続き確認が求められます。

提供機能

ツールは 30 個あります。27 個は一般的な操作をそのまま名前にしています。たとえば document_render、document_create、compliance_check、customer_list などです。document_transition は to 引数 1 つで、7 つの状態からなるドキュメントのライフサイクルを扱い、残りのすべてにアクセスするツールが 2 つあります。

• find_operation — 161 個の操作を機能で検索し、一致した各操作の完全な入力スキーマを取得します。
• call_operation — そのうち 1 つを実行します。

API 全体にアクセスできますが、よく使う機能だけを最初に一覧表示しています。すべてのクライアントにはツール一覧の上限があります（Cursor は約 40、Junie は 100、Copilot は 128）。そのため、161 個のツールを公開するサーバーは、動作しなくなるか、接続済みの他のすべてのサーバーを押しのけてしまいます。

document_render は非同期でレンダリングし、結果が出るまで待機するため、キューに入った状態ではなく、レンダリングが完了した結果を返します。レンダリングは CPU 負荷が高く、単一のワーカーで処理されるため、複数を並列で開始するより、一度に 1 つずつレンダリングすることをおすすめします。

構成

ツールの構成は、起動時に openapi.json から構築されます。 src/operations.ts が仕様を読み込み、各操作の名前、入力スキーマ、説明を導き出します。src/client.ts はそれらをどれでも実行できる単一のエグゼキューターです。API にエンドポイントを追加すると、ここでコードを変更しなくても、動作するツールが追加されます。

意図的に、コミット済みファイルに生成するのではなく、実行時に構築しています。最初のバージョンでは TypeScript が 16,000 行生成され、API が変更されるたびに再生成してコミットする必要がありました。これは仕様のコピーをもう 1 つ持つことになり、独自に古くなる可能性もあります。仕様の解析にかかる時間は約 10 ミリ秒で、1 度だけです。このプロセスは 1 度だけ起動します。

手作業で記述するのは、次の 3 つだけです。

ファイル	仕様から生成できない理由
src/manifest.ts	どの操作を昇格するか、およびその名前
src/tools/documentRender.ts	非同期のデフォルト動作と、終端状態になるまでのポーリング
src/tools/findOperation.ts	検索と遅延読み込み

ツールの説明は、仕様を通じて API のハンドラーのドキュメント文字列から取得します。操作についての説明が 2 か所で管理され、ずれていくのを避けるため、ここには記述しません。

開発

npm install
npm test        # drift and tool-surface checks
npm run build   # compiles
npm pack        # vendors openapi.json into the tarball, then cleans up

このリポジトリは生成されたものです。 ソースは InvoicePDFs API モノレポの mcp/ にあり、ここへのコミットはすべて、そこからの同期です。そのため、このリポジトリで行った変更は次の同期で上書きされます。代わりにイシューを作成すれば、変更が残る場所で対応されます。

この分割には、それぞれに適した置き場所が異なるという理由があります。コードは、説明対象の API の隣に置くのが適切です。ツールの説明は API ハンドラー自身のドキュメント文字列であり、npm test は、マニフェストに記載された操作が仕様に存在しなくなった場合に失敗します。これは、ハンドラーの名前を変更するプルリクエスト内で実行してこそ機能するガードです。一方、パッケージ は公開リポジトリに置く必要があります。npm のビルド来歴にそれが必要であり、読めるソースのないレジストリ掲載には価値があまりないからです。

そのため、上流では API の変更ごとにずれを防ぐチェックが実行され、このリポジトリでは公開が行われます。