@mindops/zapsign-mcp

ZapSign の REST API を MCP ツールとして公開する Model Context Protocol サーバーです。MCP対応ホスト (Claude Desktop、VS Code、Cursor、自作の SDK アプリ) に組み込むと、LLM がドキュメント作成、署名者の管理、DOCX テンプレートへの入力、バックグラウンドチェックの実行、ウェブフックの管理といったドキュメントワークフローを実行できます。

カバー範囲

ツールは ZapSign のリソースごとにグループ化されています。このセットは公開 REST API と一対一に対応しており、各ツールはちょうど 1 つのエンドポイントをラップします。

• Documents — PDF URL / base64 / テンプレートからの作成、一覧、詳細、更新、削除、表示順の並べ替え、署名位置の配置、oneclick、追加ドキュメント、署名者アクティビティログ

• Signers — 追加、更新、詳細、削除、一括署名、拒否、ユーザーによる拒否、認証試行のリセット、通知の再送、検証情報、署名者グループ

• Templates — DOCX からの作成、フォームフィールドの更新、一覧、詳細、更新、削除

• Users — 作成、一覧、削除、プラン情報

• Webhooks — 作成、削除 (イベントペイロードは API エンドポイントではなく、参照用ドキュメントです)

• Auth (JWT) — トークンの取得、トークンのリフレッシュ (静的 API トークンの代替)

• Background checks — 個人/法人チェックの作成、一覧、詳細

• Timestamp — 署名済み PDF、または署名を変更せずに任意の PDF へのタイムスタンプ適用

• Validation — 署名済み PDF の検証

• Partner — パートナー企業の管理、支払い状況の更新、プラン利用状況の CSV レポート

インストール

レジストリへの公開後:

npm install -g @mindops/zapsign-mcp
# or run on demand with npx (no global install):
npx -y @mindops/zapsign-mcp

公開前のローカルインストール

cd /path/to/zapsign-mcp
npm install
npm run build
npm link            # exposes `zapsign-mcp` on $PATH globally

初回公開

このパッケージは npmjs.org の @mindops スコープを対象としており、restricted アクセスで公開されます。公開するには:

npm login                      # authenticate against registry.npmjs.org
npm publish --access restricted   # or just `npm publish` — restricted is the publishConfig default

@mindops の組織が npm にまだ存在しない場合は、先に https://www.npmjs.com/org/create から作成してください。

設定

.env ファイルを作成するか (MCP ホストの設定に環境変数を設定します):

ZAPSIGN_API_TOKEN=your-permanent-system-user-token
ZAPSIGN_ENV=production       # or 'sandbox' for the test environment

推奨: システムユーザーの永続トークン (ZapSign パネルの Configurações → API → Tokens)。ユーザーに紐付いたトークンは失効するため、自動化が停止します。

MCP ホストからの利用

Claude Desktop / Claude Code

MCP の設定に追加します (通常は ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zapsign": {
      "command": "npx",
      "args": ["-y", "@mindops/zapsign-mcp"],
      "env": {
        "ZAPSIGN_API_TOKEN": "...",
        "ZAPSIGN_ENV": "production"
      }
    }
  }
}

VS Code / Cursor

同じ形式です。設定の MCP servers セクションに追加してください。

開発中のローカルでの利用

npm install
npm run build
ZAPSIGN_API_TOKEN=... ZAPSIGN_ENV=sandbox node dist/index.js

サーバーは stdio で通信します。任意の MCP クライアントから接続してツールを確認できます。

ツール命名規則

• snake_case の名前は ZapSign のリソース用語に対応します (create_document、add_signer、delete_template など)

• ツール入力のフィールド名は ZapSign の API のスペルをそのまま維持します (phone_country、phone_number、auth_mode、url_pdf...)。そのため、実際に送信されるリクエストボディは API が期待するものと完全に一致します

• パスパラメータは同じ名前のトップレベルフィールドとして現れます (doc_token、signer_token、template_token)

開発

npm install
npm run typecheck
npm run build

新しいエンドポイントを追加するには、src/tools/<resource>.ts に定義を作成し、npm run build を再実行します。各ツールは薄いラッパーです:

registerTool(server, client, {
  name: 'create_document',
  description: 'Create a new document from a public PDF URL.',
  inputSchema: z.object({ /* fields */ }),
  handler: async (input, { client }) => client.post('/docs/', input),
});

このヘルパーは、MCP トランスポート向けにエラーエンベロープを整形し、JSON 文字列化する処理を担当します。

バージョニング

このパッケージは ZapSign の v1 API に対応します。ZapSign はエンドポイントを /api/v1/ の配下でバージョニングしており、v2 が将来リリースされた場合、このサーバーは v1 をその場で置き換えるのではなく、並行モジュールとして追加される予定です。

ライセンス

プロプライエタリ (MindOps 社内)。再配布する前に MindOps へ連絡してください。