SignWell

SignWell MCP サーバー

SignWell の電子署名ワークフローをオーケストレーションする Model Context Protocol サーバーです。

前提条件

• Node.js v18 以降。
• ドキュメントへのアクセス権がある SignWell API キー（環境変数 SIGNWELL_API_KEY）。
• オプションの上書き設定：
  • 本番環境以外のエンドポイントには SIGNWELL_API_BASE_URL を使用します。
  • HTTP クライアントのタイムアウトを調整するには SIGNWELL_API_TIMEOUT_MS を使用します（デフォルトは 90000 ms。setup の CLI フラグ --timeout を指定すると、環境変数のプロンプトをスキップし、この設定を保存します）。

セットアップ

対話型ウィザード（推奨）

1. まだインストールしていない場合は、依存関係をインストールします。

   npm install
   

2. CLI をバンドルし、MCP クライアントがビルド出力を参照するようにします。

   npm run build
   

3. ウィザードを実行し、プロンプトに従います。

   node build/index.js setup
   

   • SignWell のシークレットは、Linux では ~/.config/signwell-mcp/env、macOS では ~/Library/Application Support/SignWell/MCP/env、Windows では %APPDATA%/SignWell/MCP/env に、0700/0600 のアクセス許可で保存されます。
   • Claude Desktop、Claude Code、Cursor、OpenCode の設定ファイルを自動的に更新します（書き込みの前にバックアップが作成されるため、プラットフォームごとのパスを探す必要はありません）。
   • クライアントの設定先：
     • Claude Code：~/.claude.json の mcpServers.signwell
     • Claude Desktop：claude_desktop_config.json の mcpServers.signwell
     • Cursor：~/.cursor/mcp.json の mcpServers.signwell
     • OpenCode：~/.config/opencode/opencode.json の mcp.signwell（Windows：%USERPROFILE%\.config\opencode\opencode.json）
   • 各クライアントで文書化されている JSON ラッパーと STDIO／ローカルサーバーの形式を使用するため、クライアントの再起動後にサーバーが表示されます。
   • 以前の Claude Code のインストールで古い ~/.claude/mcp.json の servers.signwell エントリーが書き込まれている場合、セットアップを再実行すると、そのレガシーファイルのバックアップを作成し、正しい ~/.claude.json 設定を書き込んだ後、古い SignWell エントリーだけを削除します。
   • --print（または -p）を指定すると、ディスクに書き込まずに出力をプレビューできます。また、--yes --api-key=... を指定すると、非対話型の実行（CI、開発用コンテナーなど）ができます。
   • ウィザードで設定する MCP クライアントを制限するには、--clients=claude-desktop,cursor を渡します。すべてのクライアントを対象にする場合は省略します。デフォルト以外の HTTP タイムアウトが必要な場合にのみ、--timeout=<ms> を渡してください。
   • バンドル（npm run build）してパッケージを公開すると、エンドユーザーは npx @signwell/mcp setup で同じウィザードを実行できます。グローバルにインストールすると、signwell-mcp setup を直接実行することもできます。

手動での環境変数設定

環境変数を自分で管理したい場合は、サーバーを実行する前に必要な値をエクスポートします。

export SIGNWELL_API_KEY="your_api_key"
# export SIGNWELL_API_BASE_URL="https://www.signwell.com/api/v1"   # optional

インストール（npm）

パッケージが npm（GitHub：Bidsketch/signwell-mcp）に公開された後は、次の方法でインストールできます。

• グローバルにインストールせずにセットアップウィザードを実行します。

  npx @signwell/mcp setup
  

• バイナリを継続して使用する場合は、グローバルにインストールします。

  npm install -g @signwell/mcp
  signwell-mcp setup
  

設定後、signwell-mcp を使って MCP サーバーを起動します（Node.js v18 以降が必要です）。

signwell-mcp.mcpb ファイルは、Claude Desktop 用の独立した拡張機能アーティファクトです。ルートの manifest.json を使用するため、リリース用には npm run build の実行後に再ビルドしてください。

ローカル開発ワークフロー

1. 依存関係をインストールします：npm install

2. CLI エントリーポイントをバンドルします（MCP クライアントの設定に必要です）：npm run build

3. 認証情報を設定します：node build/index.js setup（公開後は npx @signwell/mcp setup も使用できます）

4. MCP サーバーをローカルで起動します：npm start（node build/index.js を実行します）

5. コミットする前に、別のターミナルを開いてテストとリンターを実行します。

   npm test
   npm run typecheck
   npm run lint
   

6. MCP Inspector やその他のクライアントを使用する場合は、npm start（stdio）を指定してください。

サーバーの実行

• 開発用エントリーポイント（stdio トランスポート）：

  SIGNWELL_API_KEY="$SIGNWELL_API_KEY" npm start
  # or run directly:
  SIGNWELL_API_KEY="$SIGNWELL_API_KEY" node build/index.js
  

• CLI ヘルパー：

  • node build/index.js --help は使い方と環境変数の要件を表示します。
  • node build/index.js --version は現在のビルドを表示します。
  • node build/index.js setup は、ソースから作業している場合に、前述のセットアップウィザードを起動します。
  • パッケージがバンドル／公開された後は、npx @signwell/mcp setup でウィザードを実行でき、SIGNWELL_API_KEY=... npx @signwell/mcp でパッケージ化されたバイナリを介してサーバーを起動できます（グローバルインストールの場合は、signwell-mcp ... を直接実行できます）。

MCP Inspector

MCP Inspector を使って、ローカルでツールを試してください。

npx @modelcontextprotocol/inspector node build/index.js

テスト

品質チェックを順番に実行します。

npm test
npm run typecheck
npm run lint
npm run format

デモ

MCP Inspector のセッション例（ID はサニタイズ済み）：

1. 下書きを作成

   Tool: document_create
   Input: {
     "name": "Sales Agreement",
     "recipients": [{ "id": "1", "name": "Alice Example", "email": "[email protected]" }],
     "files": [{ "name": "agreement.pdf", "file_url": "https://files.example.com/agreement.pdf" }]
   }
   Output:
   {
     "ok": true,
     "type": "document_create",
     "message": "Document draft created.",
     "data": {
       "id": "doc_123",
       "status": "draft"
     }
   }
   

2. 下書きを送信

   Tool: document_send_draft
   Input: { "document_id": "doc_123", "confirm_send": true }
   Output:
   {
     "ok": true,
     "type": "document_send_draft",
     "message": "Send request accepted.",
     "data": { "id": "doc_123", "status": "Sent" },
     "warnings": ["Status may update asynchronously. If this response still shows Draft, call document_get after a few seconds; do not send again. Recipient send_email is an embedded-signing setting, not an email-delivery receipt."]
   }
   

3. ステータスを確認

   Tool: document_get
   Input: { "document_id": "doc_123" }
   Output:
   {
     "ok": true,
     "type": "document_get",
     "message": "Fetched document status.",
     "data": {
       "id": "doc_123",
       "status": "completed",
       "recipients": [{ "email": "[email protected]", "status": "signed" }]
     }
   }
   

4. 完成した PDF

   Tool: document_completed_pdf
   Input: { "document_id": "doc_123" }
   Output:
   {
     "ok": true,
     "type": "document_completed_pdf",
     "data": {
       "pdf_url": "https://signwell-downloads.example.com/doc_123.pdf"
     }
   }
   

プライバシーポリシー

このセクションでは、SignWell MCP サーバーのデータ取り扱いについて説明します。

データの収集

• MCP サーバー自体は、個人データや使用状況の分析データを収集、送信、保存しません。
• SignWell API キーは、アクセス許可を制限したファイル権限（0600）で、プラットフォームごとの安全な場所にローカル保存されます。
  • macOS： ~/Library/Application Support/SignWell/MCP/env
  • Linux： ~/.config/signwell-mcp/env
  • Windows： %APPDATA%/SignWell/MCP/env

使用と保存

• file_store で提供されたファイルは、60 分の TTL で一時的にメモリ内に保持され、自動的に消去されます。
• メモリ内のファイルデータはすべて、サーバーの再起動時にも消去されます。
• セットアップ時に作成される認証情報ファイル以外に、永続的なデータ保存はありません。

第三者との共有

• MCP サーバーは、第三者とデータを共有しません。
• すべての API 通信は、お使いのマシンと SignWell のサーバー（https://www.signwell.com/api/v1）の間で直接行われます。

テレメトリーと分析

• サーバーは、いかなる種類の使用状況分析データやテレメトリーも収集、送信、保存しません。

データの保持

• メモリ内のファイルストレージは、サーバーの再起動時、または 60 分の TTL の期限切れ後に消去されます。
• ローカルの認証情報設定ファイル以外に、永続的に保持されるデータはありません。

お問い合わせ

プライバシーに関するお問い合わせは、[email protected] までご連絡いただくか、github.com/Bidsketch/signwell-mcp/issues で issue を作成してください。

ホストされているプライバシーポリシーは、https://www.signwell.com/privacy/ もご覧ください。

リソース

• MCP リソース：document://{id} と template://{id} は、ツールと同じ正規化ロジックを再利用する読み取り専用の JSON スナップショットを提供します。これにより、インスペクターや他の MCP クライアントから、以前に作成したアセットをすばやく参照できます。

ファイルの添付と下書きの安全性

• document_create と template_create_document は常に draft: true を設定するため、document_send_draft を明示的に呼び出さない限り、メールが送信されることはありません。
• files 配列を使って、file_url（公開 URL、または Claude Desktop などの UI でファイルを @ 添付した際に MCP クライアントが提供するリンク）、file_base64、または resource_uri のいずれかでファイルを指定します。resource_uri を指定すると、MCP サーバーは自動的に resources/read を呼び出して添付ファイルのバイトデータを取得し、SignWell の /api/v1/documents/ エンドポイントに転送します。

ドキュメントの修正と署名日

• 受信者名： 各 document_create 受信者に name を指定します。name を省略した場合は、従来の first_name と last_name が結合されます。API の課金なしで拘束力のないテスト用ドキュメントを作成するには、test_mode: true を設定します。
• 下書きの設定： document_send_draft では、confirm_send: true とともに、name、subject、message、expires_in、reminders などの更新を任意で指定できます。省略した設定は保持されます。受信者、ファイル、フィールドの編集や、送信せずに変更を保存することはできません。
• 送信済みドキュメントの受信者： document_get を呼び出して受信者 ID を取得し、document_id、confirm_update: true、recipients: [{ "id": "<returned recipient ID>", "name": "Correct Name", "email": "[email protected]" }] を指定して document_update_recipients を呼び出します。変更しない値も含め、名前とメールアドレスの両方を指定してください。送信済み／閲覧済み／保留中／バウンス済みのドキュメントで、署名を開始していない受信者のみ変更できます。埋め込み形式ではない受信者には新しい通知メールが送信されます。埋め込み形式の受信者には、既存の send_email 設定が適用されます。
• ドキュメントの取り下げ： document_id と confirm_delete: true を指定して document_delete を呼び出すと、ドキュメントが削除され、進行中の署名がキャンセルされます。誤ったリクエストがある場合は、置き換えを作成する前に削除して、リクエストが二重に有効になるのを防いでください。
• 送信ステータス： 送信が成功すると「Send request accepted」が返され、ステータスの更新が 1 回試みられます。更新に失敗しても、受け付けられた送信は成功のままです。ステータスの反映には遅れが生じる場合があります。再送信するのではなく、数秒後に document_get を使用してください。send_email は埋め込み署名のオプションであり、配信確認ではありません。

自動入力され、編集できない署名日を設定するには、text_tags: true と次の既存の SignWell テキストタグを使用します。

{{signature:1:y}} {{autofill_date_signed:1:y}}
{{signature:2:y}} {{date:2:y::::::y}}

どちらの日付形式も署名日を固定します。署名者が選択する日付には、編集可能な {{date:1:y}} を引き続き使用してください。テキストタグの解析は非同期です。処理後に document_get でフィールドを確認してください。SignWell のテキストタグオプション、受信者の更新、更新と送信の制限を参照してください。

利用可能なスクリプト

スクリプト	用途
npm start	npm run build の実行後、stdio 経由で MCP サーバーのエントリーポイントを実行します。
npm test	テストスイートを実行します。
npm run typecheck	tsc --noEmit でプロジェクトの型をチェックします。
npm run lint	Biome を使ってソースとテストの lint を実行します。
npm run format	Biome を使ってリポジトリのフォーマット規約を適用します。
npm run build	esbuild を使って build/index.js に ESM バンドルを生成します。

ディレクトリ構成

.
├── src/                # MCP server source (entrypoint + domain modules)
│   └── setup/          # Interactive setup wizard for MCP client configuration
├── test/               # Test suites
├── build/              # Bundled output (ignored in releases)
├── biome.json          # Biome lint/format configuration
└── tsconfig.json       # TypeScript compiler configuration