QCDatabase.AI

QC Database MCP サーバー

AI アシスタント（Claude など）が、日々の QC Database での作業を代わりに行うための小さなプログラムです。作業中のプロジェクトを設定し、記録をアップロードし、AI がドキュメントから読み取った内容を確認し、完全で追跡可能な ターンオーバーパッケージ の作成に必要な未完了項目を見つけて処理できます。

お使いのコンピューター上で実行されます。AI アシスタントがこのプログラムと通信し、このプログラムがお客様のログイン情報を使って、お客様に代わって QCDatabase.AI と通信します。

公式の Model Context Protocol Python ライブラリと QC Database MCP 仕様に基づいています。仕様は qcdatabase.ai/mcp_server_spec.md で公開されており、このリポジトリにも mcp_server_spec.md として保存されています。

---

アシスタントに頼めること

接続すると、自然な言葉で話しかけることができます。たとえば、次のように頼めます。

• 「QC Database に接続して。」 → サインインします（ブラウザーが一度開きます）。
• 「Riverside Unit 2 プロジェクトで作業して。」 → セッション中、そのプロジェクトを設定します。
• 「この MTR を Mill Test Reports フォルダーにアップロードして。」
• 「このプロジェクトでターンオーバーに必要なもののうち、まだ不足しているものは？」
• 「自分に割り当てられている未完了の参照リクエストを表示して。」
• 「12 番ライン付近で X 線検査に不合格だった溶接箇所を見つけて。」 → プロジェクトデータを意味ベース（セマンティック）で検索し、関連度順に表示します。
• 「QC Database でテストパッケージを作成するには？」 → 組み込みの QC Database ユーザーマニュアルをもとに回答するため、アシスタントを離れずにアプリの使い方を学べます。
• 「この写真をその溶接箇所に添付して。」
• 「この検査を完了としてマークして。」（署名記録はお客様の名前で登録されることをお知らせします。これは AI ではなく、お客様が判断することです。）

---

始める前に

お使いのコンピューターに Python 3.10 以降 が必要です。

• Windows： Microsoft Store（「Python」で検索）からインストールするか、 python.org/downloads からインストールします。 python.org からインストールする場合は、「Add Python to PATH」 にチェックを入れてください。
• Mac： brew install python を実行するか、 python.org/downloads からインストールします。

インストールされているか確認するには、ターミナル（Windows では PowerShell、Mac では Terminal）を開いて、次のコマンドを実行します。

python --version

Python 3.10 以上と表示されます。（Mac によってはコマンドが python3 です。）

---

インストール

このフォルダーでターミナルを開き、次のコマンドを実行します。

pip install ".[runtime]"

これで完了です。サーバーと qcdatabase-mcp というコマンドがインストールされます。

pip が見つからない場合は、python -m pip install ".[runtime]"（または python3 -m pip install ".[runtime]"）を試してください。

---

Claude Desktop へのインストール

Claude Desktop がこのサーバーを起動し、チャット内にツールを表示します。一度設定すれば、以降はそのまま使えます。

1. Claude Desktop アプリをインストールする

まだインストールしていない場合は、 claude.ai/download からダウンロードしてサインインします。

2. 設定ファイルを開く

Claude Desktop で次の操作を行います。

1. 設定を開きます （Windows：メニュー ☰ → File → Settings、Mac：Claude → Settings）。
2. Developer タブに移動します。
3. Edit Config をクリックします。

claude_desktop_config.json という名前のファイルが開きます（必要な場合は作成されます）。 次の場所から直接開くこともできます。

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Mac： ~/Library/Application Support/Claude/claude_desktop_config.json

3. QC Database サーバーを追加する

この内容をファイルに貼り付けます。ファイルにほかのサーバーがすでにある場合は、既存の"mcpServers"セクション内に"qcdatabase"ブロックを追加してください。

Windows：

{
  "mcpServers": {
    "qcdatabase": {
      "command": "python",
      "args": ["-m", "qcdatabase_mcp"]
    }
  }
}

Mac（通常、Python はpython3です）：

{
  "mcpServers": {
    "qcdatabase": {
      "command": "python3",
      "args": ["-m", "qcdatabase_mcp"]
    }
  }
}

ファイルを保存します。

Claude が起動できない場合（「python not found」と表示される場合や、サーバーが失敗する場合）は、"python"だけでなく、Python のフルパスを指定してください。ターミナルでwhere python（Windows）またはwhich python3（Mac）を実行してパスを調べ、そのパスを"command"として貼り付けます。Windows の場合、たとえば次のようになります。

{
  "mcpServers": {
    "qcdatabase": {
      "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": ["-m", "qcdatabase_mcp"]
    }
  }
}

（Windows のパスを JSON 内に記述する場合は、バックスラッシュを二重にした\\を使用してください。）

4. Claude Desktop を再起動する

アプリを完全に終了してから再度開きます（Windows では、システムトレイからも終了します。Mac では、ウィンドウを閉じるだけでは不十分なので、Cmd-Q で終了します）。新しいサーバーは、完全に起動し直したときにのみ読み込まれます。

5. 読み込まれたことを確認する

新しいチャットを開始し、ツール／コネクターのインジケーター（メッセージボックスの近くにあるスライダーまたはツールアイコン）を探します。それをクリックすると、ツール一覧とともにqcdatabaseが表示されるはずです。表示されない場合は、トラブルシューティングを参照してください。

次に、Claude に**「QC Database に接続して」**と頼んでサインインします。詳しくは以下をご覧ください。

---

初めて使うとき

1. サインインします。 アシスタントにQC Database に接続してと頼みます（loginツール）。ウェブブラウザーが開くので、ログインして、接続する会社のワークスペースを選択します。この選択によって、接続先の組織が固定されます。この操作は一度だけ行えばよく、選択内容は記憶されます。

2. プロジェクトを選択します。 プロジェクト名を指定して、そのプロジェクトの作業を依頼するか、まずプロジェクト一覧を表示します。ほとんどの操作はプロジェクト「内」で行うため、サーバーはプロジェクトの作業を始める前に、プロジェクトを選ぶよう求めます。プロジェクトはいつでも切り替えられます。

3. 作業を開始します。 ドキュメントや図面のアップロード、引き渡しに必要な不足項目の確認、参照依頼の作成と完了、メモや写真の追加などを行えます。

---

できること（ツールグループ）

• セッション： login、logout、auth_status、whoami
• 目的の情報を探す： list_tenants、list_projects、set_project、 get_active_project、list_project_members、list_lists、list_list_items、 list_map_item_schemas、get_map_item_schema、list_document_folders、 list_form_schemas
• 管理対象の語彙リスト： create_list_item、update_list_item、 delete_list_item（論理削除です。リストの読み取り結果には表示されなくなりますが、 記録には残ります）
• プロジェクト、ジョブ、パッケージ： update_project、list_jobs、create_job、 update_job、list_packages、create_package、update_package、 list_line_specs、create_line_spec、update_line_spec（更新されるのは渡した フィールドのみです。フィールドを空にするには、clear にそのフィールド名を指定します）
• アップロード記録： upload_document、upload_document_version、 download_document、upload_drawing、upload_large_format_drawing、 upload_drawing_to_package、upload_drawing_version、 upload_large_format_drawing_version、attach_photo
• 図面： list_drawings、get_drawing（マップアイテムに使うHTML5 canvasの座標空間における ピクセル幅／高さを含む）、export_drawing、 export_large_format_drawing、update_drawing（識別用メタデータ）、 move_drawing_to_package（アクティブなプロジェクト内にある既存の図面と移動先を指定します。 パッケージの割り当てのみを変更し、アップロードや複製は行いません）
• 入力可能なPDFフォーム： list_fillable_templates、get_fillable_template、 download_fillable_template、submit_fillable_template
• 構造化データ： get_document、set_document_extracted_data、 list_documents、list_map_items、get_map_item、create_map_item （ピクセル座標で溶接部／フランジを配置します）、update_map_item（名前変更、移動、 メモ、担当者、作業ステータス）、bulk_create_map_items、 bulk_update_map_items（1つの図面／スキーマにつき最大500件を一括処理）。必ず 最初に list_map_item_schemas を呼び出してください。下記のCAD／PCF／.weldbに関する注意事項をご覧ください
• Zipmap（マッピング済み図面全体を1回のアップロードで送信）： inspect_zipmap、 upload_zipmap — Zipmapをご覧ください
• 修理： list_repair_codes、add_map_item_repair
• 検査フォームとメモ： list_form_submissions、create_form_submission、 get_form_submission、update_form_submission、complete_form_submission、 create_note、list_notes、resolve_note
• 写真： list_photos、attach_photo
• ITPと承認（必要に応じて）： list_itp_line_items、get_itp_line_item、 create_itp_line_item、update_itp_line_item、mark_map_item_complete、 mark_map_item_accepted、mark_itp_complete、mark_itp_accepted
• 品質保留ロック（立会い点／保留点 — ユーザーが判断）： list_lock_types （読み取り専用）、list_locks、get_lock、add_lock（マップアイテムまたはITP明細に 保留点を設定します。フィットアップ、仮付け、溶接部の清浄度、FME、最終閉止、 ボイラーチューブのFMEスポンジ挿入／取り出しなどを対象にでき、検査が完了するまで 提出できないようにします）、unlock_lock、assign_lock、 delete_lock（誤って設定した保留を取り消します。論理削除のため、監査証跡には残り、 アイテムの保留は解除されます。実際に要件を満たした保留には unlock_lock を使用してください）。 ロックは施工品質ゲートであり、セキュリティ制御ではありません。ロックの設定または解除は、 所有者／作成者または権限を持つ検査員から明示的に依頼された場合にのみ行ってください。 ロックのタイプ（名前付きの保留定義と、それぞれを設定／解除できるユーザー）の作成や編集は ここでは利用できません。権限に関わるこの設定はウェブアプリのProject Adminで行います。 アシスタントがその場所をご案内します
• 引き渡し（重要な部分）： list_reference_requests、 create_reference_request、list_references、create_reference、 turnover_report
• 受け入れ： list_shippers、list_shipper_line_items
• セマンティック検索（意味に基づくランキング付き検索）： semantic_search — プロジェクトの ドキュメント、図面、大判図面、ジョブ、パッケージ、リストアイテム、マップアイテム、フォーム送信、 メモ、出荷元を自然言語で検索します
• QC Databaseの使い方： search_user_manual（「〜するにはどうすればよいですか？」のような質問をして、 製品のヘルプ記事を読む）、list_user_manual（ヘルプの目次を閲覧）
• トレーニング（redline.schoolでプレイできるトレーニング）： create_training、 list_trainings、get_training、list_training_ideas、get_training_idea、 get_training_policy（管理者）、upload_training_policy、 get_training_authoring_guide、get_training_template、 validate_training_bundle（無料）、upload_training_version（無料。自分だけがプレイできる 非公開バージョンを保存します）、submit_training_review（25ドルのセキュリティレビュー。 confirm_charge が必要）、get_training_reviewと download_training_version（レビュー済みバージョンのみ。共同開発者向け）。ローカルサーバーは バンドルフォルダーを自動的にZIP化し、redline.schoolへ直接送信します。ホストサーバーでは、 先に begin_upload を使ってZIPを送信してください。ファイルの内容がAIを経由することはありません。 これらのツールでは、アクティブなプロジェクトではなく、明示的な scope を指定します。 Trainingsの提供開始前に承認された接続は、trainings:read／trainings:write を取得するために 再承認が必要です。公開、掲載解除、所有者の再割り当てはQC Databaseウェブアプリで行います。
• トレーニングのコンプライアンス： assign_trainingとinvite_users（管理者向け。どちらも confirm=True まではプレビューで、最大200人まで）、list_assignments（Training Matrix： 完了／期限間近／期限超過／期限切れ、および必須トレーニングのブロック中／猶予期間）、 list_permission_requirements（どの権限に最新のトレーニングが必要か。設定はウェブアプリでのみ可能）、 get_my_trainings（すべてのメンバーが利用でき、1回の呼び出しで必須トレーニングと完了済みトレーニング、 結果、リンク、制限対象の権限を取得します）。マップアイテムやITP行の承認、ロック操作、制限対象の フォームなど、制限付きの操作は training_required で失敗することがあります。エラーには必要なトレーニング、 有効期限、そのトレーニングを受講するためのリンクが記載されます。
• トレーニングの競争： get_training_leaderboard（ゲームをプレイできるすべてのメンバーが利用できます。 個人、ユーザータイプ、プロジェクトの役割、またはプロジェクトごとのベストスコアをランキング表示し、 自分の順位も表示します）、get_engagement_report（管理者向け。ワークスペース、プロジェクト、 または1つのトレーニングについて、再プレイ、任意のプレイ、トレーニング時間、マルチプレイヤー、 スコアの向上、誰も再プレイしていないトレーニングを表示します）
• クルーセッション（ライブマルチプレイヤー）： start_crew_session（公開済みのマルチプレイヤー トレーニングを開始します。参加コード、参加リンク、クルーが一緒にプレイする際にスキャンするQRリンクが 返されます。プロジェクトへのアプリ内招待も任意で利用できます）、 list_crew_sessions、get_crew_session（参加者、チーム、ゲーム終了時の結果）、 end_crew_session、invite_project_to_crew_session。開始、終了、招待の前にはプレビューが表示され、 confirm=True が必要です。
• ビルドサービス： list_build_requests、get_build_request、およびPQSスタッフ向けの quote_build_request（価格。0ドルも指定可能。説明付き。事前にプレビューが表示され、双方にメールが送信されます）。 PQS Training Builderは自分に割り当てられたビルドを確認し、通常のトレーニングツールを使ってそれぞれを 作成します（レビューも含まれ、料金はかかりません）。顧客側の管理者は、自分たちのリクエストと見積もりを 確認できます。見積もりの依頼、入札の承認、トレーニングの承認、変更注文はトレーニングページで行います。
• クルー： list_crews（管理者向け）。assign_training と {type: 'crew', crew_id} を使って トレーニングをクルーに割り当てます。クルーの編集はウェブアプリで行います。
• コミュニティフォーラム（すべてのQC Databaseユーザーが共有）： list_forum_boards、 list_forum_posts（ボード、検索、質問で絞り込み）、get_forum_post、 list_forum_replies、create_forum_post、reply_to_forum_post（画像は任意。 ホストサーバーでは、先に begin_upload を使って送信してください）。投稿はすべての会社に公開され、 QC Databaseによって「via MCP」のバッジが付くため、投稿前にアシスタントが本文を表示します。 Forum APIの提供開始前に承認された接続は、forum:read／forum:write を取得するために再承認が必要です。 モデレーションはウェブアプリで行います。
• ユーティリティ： generate_qr_code

---

CAD、PCF、および .weldb システムと連携

マップアイテムのタイプ定義は MCP では読み取り専用です。検出はできますが、作成、編集、昇格の操作は公開されていません。レコードの編集とインポートは既存のスキーマ ID に紐づきます。アーカイブされたスキーマが新しいタイプとしてインストールされることはありません。

リストとドキュメントのタイプ作成・編集は許可されていますが、API の書き込みコントラクトが不足しているためブロックされています。ドキュメントフォルダーの移動と、LFD に付けるパッケージタグも API によってブロックされています。図面をパッケージに移動することは、LFD のパッケージタグではありません。正確な不足点についてはAPI 引き継ぎドキュメントをご覧ください。ホスト型の本番環境で新しいツールを表示するには、再公開とクライアント側のツール検出の再実行が必要です。開発環境での検証だけでは、本番環境は更新されません。

このサーバーは、CAD/CAE エクスポート、PCF 配管ファイル、.weldb 製缶工向け交換パネルファイルなど、すでにジオメトリを記述しているシステムと自然に連携します。これらのソースには、適切なマップアイテムに必要な情報のほとんどが含まれているため、アシスタントは正確な溶接マップを作成できます。ただし、次の 2 つの習慣を守る必要があります。

1. まずスキーマを取得します。 create_map_item／bulk_create_map_items の前に、必ず list_map_item_schemas を呼び出してください。適切なスキーマを選択し、正確なフィールドを把握できるため、値を推測したりフリーテキストで入力したりせず、ソースの値を適切な場所に割り当てられます。
   • PCF（配管）ファイルには、配管溶接に必要な情報のほとんど（継手の種類、材質、重量／sch）が含まれています。
   • .weldb ファイルには、材質、チューブ壁厚、および図面上の溶接部の矩形位置が含まれており、溶接マップを自動的に作成するのに十分な情報が得られます。
2. ソースのジオメトリに合わせます。点溶接か矩形溶接かを判別します。 これはデータ品質を大きく左右します。PCF の配管溶接は、単一の点溶接（x／y 座標 1 つずつ）です。.weldb の溶接には矩形の位置が指定されています。範囲を維持するため、2 つ目の点（x_position_2／y_position_2）には対角の頂点を指定してください。矩形溶接を単なる点に縮約したり、点溶接を矩形に広げたりすると、気付かないうちにマップが破損します。事前にスキーマを取得することで、アイテムを配置する前にこの違いを明確にできます。

---

Zipmaps：マップ全体を1回のアップロードで登録

zipmap は、1枚の図面（PNG、必要に応じて元の1ページPDFも含む）に、配置済みのすべてのマップアイテムと、それらのアイテムの種類を記述するJSON Schemaをまとめた通常のzipファイルです。これは「AIはお好きなものを」という引き継ぎ方法です。お使いのモデル、CADエクスポート、または数量拾いツールがマップを作成し、QC Databaseが取り込みます。

upload_zipmap を使うと、これまでの3段階の手順（図面をアップロード → 待機 → 図面に対してアイテムを一括作成）が、1回のトランザクションリクエストに置き換わります。図面、すべてのスキーマに属するマップアイテム、および抽出データが一緒に作成されるか、何も作成されないかのどちらかです。サーバー側ではAIを実行しません。マップはお客様が用意します。

自然な言葉で依頼できます。「このzipmapをUnit 2の配管パッケージにアップロードして。」 その前に、アシスタントは次の3つを行います。

1. inspect_zipmap — アップロードせずに内容を確認します。図面のサイズ、種類ごとのアイテム数、アイテムが使用するデータフィールド、QC Databaseのマップアイテムスキーマにまだ紐付けられていない種類を確認できます。
2. list_map_item_schemas / get_map_item_schema — zipmapでは種類をローカル名（weld、heat）で指定しますが、QC DatabaseではスキーマをIDで識別します。紐付けられていない種類は、該当するスキーマと対応付ける必要があります（schema_ids={"weld": "<id>"}）。種類のフィールドとスキーマのフィールドを比較して、その対応を確認します。作成ツール側でIDをあらかじめアーカイブ内の schemata/<type>.schema.json に書き込んでおけば、この手順を省略できます。
3. list_packages — 新しい図面をどこかに登録する必要があり、APIではパッケージIDが必須です。まず、対象のスコープパッケージを選択するか、create_package で作成します。

座標はzipmapのPNG上のピクセル座標（原点は左上、y軸は下向き）で渡されます。QC Databaseがマップする空間と同じなので、拡大縮小や反転は行われません。プロジェクトでスキーマごとの自動採番を使用している場合、zipmapのアイテムIDよりも自動採番されたラベルが優先されます。また、結果には、新しく作成された各アイテムと元のIDとの対応が報告されます。

修正したマップを再送しますか？ mode="replace" を指定すると、重複を残す代わりに、そのパッケージ内で同じ図面番号を持つ有効な図面があれば、まず論理削除します（監査証跡には保持されますが、図面一覧からは消え、関連するマップアイテムも削除されます）。デフォルトの mode="append" では、常に新しい図面が作成されます。

ローカルで確認できる項目はすべて、アップロード前にチェックされます。PNGの欠落、スキーマIDが割り当てられていない種類、図面の範囲外にある座標、すべてのアイテムの位置がずれてしまうPDF空間の座標などを確認します。そのため、数メガバイトのデータを送信した後ではなく、修正項目の一覧とともに数秒でエラーになります。

Zipmapはお使いのコンピューターから読み取られるため、ローカルの（stdio）サーバーで動作します。ホスト型サーバーがディスクにアクセスすることはありません（ファイルシステムの安全性を参照）。

---

承認について

作業を完了または承認済みにすることは、承認を行うことを意味します。システムには、お客様の名前と現在の時刻で記録されます。アシスタントが代わりに実行することはできますが、該当するツールはいずれも、その操作の責任はお客様にあることを明示します。サーバーが何も知らせずに承認することはありません。これらの操作は、お客様の承認を得て行う判断として扱ってください。

---

プライバシーと安全性

• サーバーはローカルで実行され、https://qcdatabase.ai とのみ通信します。
• ログインは1つの組織に固定され（サインイン時に選択）、セッションは1つのプロジェクトに固定されます。そのため、アシスタントが誤って別のワークスペースやプロジェクトにアクセスすることはありません。
• サーバーが要求する権限は一般ユーザーに必要なものだけです。設計上、管理者操作は対象外です。
• 接続済みのアプリは、QC Database アカウントからいつでも切断できます。

ログイン情報は、ユーザーごとのフォルダーにあるお使いのコンピューターに保存されます。

• Windows： %LOCALAPPDATA%\qcdatabase-mcp\store.json
• Mac： ~/Library/Application Support/qcdatabase-mcp/store.json
• Linux： ~/.config/qcdatabase-mcp/store.json

ログイン情報を削除するには、logout ツールを実行するか、そのファイルを削除してください。

ファイルシステムの安全性（設計上の不変条件）

これは、サーバー自身の安全性と、このオープンソースリポジトリへの貢献者全員を守るために、サーバーが常に遵守しなければならない厳格なルールです。

• サーバーは自身のファイルを変更しません。 どのツールも、サーバーのインストール先全体（自身のソース、依存関係（site-packages）、仮想環境、チェックアウト時のリポジトリルート）から読み取ったり、そこへ書き込んだりできません。指定されたパスに関係なく、アシスタントがサーバーや依存関係のコードを編集することはできません（自己改変はできません）。ダウンロードでは既存ファイルの上書きも拒否されます。新しいパスを選んでください。
• サーバーはトークンフロー以外で認証情報ストアにアクセスしません。 どのツールもユーザーごとの設定ディレクトリを読み書きできないため、トークンがツール経由で外部に流出したり上書きされたりすることはなく、リポジトリにコミットされることもありません（チェックアウトの外に保存され、store.json も .gitignore の対象です）。
• ツールがローカルで扱うファイルはユーザー自身のドキュメントのみで、stdio モードの場合に限られます。 アップロードツールは指定されたファイルを読み取り、ダウンロード／エクスポートツールは選択したパスに書き込みます。ホスト型モードでは、サーバーはすべてのローカルファイルシステムへのアクセスを拒否します。ディスクはお客様のものではなくサーバーのものだからです（その環境でのアップロード／ダウンロードには、代わりにクライアント側のファイル転送経路が必要です）。

これらのルールは、server.py の _guard_local_path によってコード内で強制されています。

---

トラブルシューティング

• 再起動後も Claude Desktop に「qcdatabase」が表示されない場合
  1. アプリを完全に終了（Windows ではシステムトレイ、Mac では Cmd-Q）してから、もう一度開いてください。
  2. 設定ファイルが有効な JSON であることを確認してください。カンマや波括弧が1つ欠けているだけでも、すべてのサーバーが読み込まれなくなります。確信が持てない場合は、JSON チェッカーに貼り付けて確認してください。
  3. それでも読み込まれない場合は、"command" に Python のフルパスを設定してください（上記のインストールに関する注意を参照）。
  4. Claude Desktop のログでエラーを確認してください。Windows：%APPDATA%\Claude\logs\、Mac：~/Library/Logs/Claude/。
• 「Not logged in.」と表示される場合 アシスタントに QC Database に接続するよう依頼し、ブラウザーでサインインを完了してください。
• 「No project is set.」と表示される場合 アシスタントにプロジェクトで作業するか、プロジェクトを一覧表示するよう依頼してください。
• 新しい機能で「Access denied (403)」と表示される場合（ユーザーマニュアルや品質保留ロックなど） 以前のバージョンで最初にサインインした場合、保存されているアプリ登録は、その機能の権限が追加される前のものです。store.json を削除し（保存場所はプライバシーと安全性を参照）、もう一度サインインしてください。現在の権限でアプリが再登録されます。
• ログイン時にブラウザーが開かなかった場合 アシスタントにリンクが表示されます。手動で開いて手続きを完了し、その後もう一度サインインしてください。
• サインインページに接続できない／ポートがすでに使用中の場合 ログインではポート 8765 のローカル Web アドレスを使用します。別のプログラムがそのポートを使用している場合は、アプリを起動する前に環境変数 QCDB_CALLBACK_PORT を追加して別の空きポートを設定してください（例：8766）。その後、もう一度サインインしてください。
• python が見つからない場合 Python を再インストールし、「Add to PATH」にチェックを入れてください（Windows）。または、設定で python3 を使用してください。

開発者向け

pip install -e '.[runtime]' # editable install
python -m qcdatabase_mcp    # run the stdio server directly

pip install -e '.[dev]'     # editable install + test deps
pytest                      # run the test suite

レイアウト：

src/qcdatabase_mcp/
  __main__.py   # entry point + CLI (chooses stdio vs. hosted HTTP)
  server.py     # FastMCP server + all tools + local filesystem guard
  hosted.py     # multi-user hosting: OAuth resource server, token verify, sessions
  client.py     # HTTP client: bearer auth, auto-refresh, errors, pagination, path safety
  auth.py       # OAuth2 (PKCE + dynamic client registration) login & refresh (stdio)
  config.py     # local token / project storage (stdio)
tests/
  test_security.py  # guard, token verifier, path safety, pagination, refresh, ...
mcp_server_spec.md  # the API + behaviour spec this server implements
CLAUDE.md           # contributor invariants (filesystem safety, credential handling)

環境変数（stdio モード）：

• QCDB_CALLBACK_PORT — ローカルの OAuth コールバックポート（デフォルトは 8765）。
• QCDB_CONFIG_DIR — トークン／設定の保存場所を上書きします。

多数のユーザー向けのホスティング（mcp.qcdatabase.ai）

デフォルトでは、サーバーは stdio 経由で MCP を通信します。つまり、ローカルユーザー 1 人が login ツールでサインインします。代わりに --http を渡すと、複数ユーザー向けのホスト型サーバーが起動し、/mcp で Streamable HTTP トランスポートを提供します。また、公開 ホームページ（人間向けの接続手順）を / で、ヘルスチェック（ロードバランサーや稼働時間モニター向け）を /health で提供します。

自分のマシンで試す（.venv を作成してインストールし、http://127.0.0.1:8000 で実行します）：

./scripts/run-local.sh        # Mac/Linux
.\scripts\run-local.ps1       # Windows (PowerShell)
scripts\run-local.bat         # Windows (double-clickable / cmd)

その後、ブラウザーで http://127.0.0.1:8000/ を開きます。

サーバーにデプロイして、git pull と再起動だけでデプロイが完了するようにします。詳細な手順（systemd ユニット、nginx/Caddy の設定、確認チェックリスト、トラブルシューティング）は deploy/README.md にあります。

cp deploy/example.env .env    # set QCDB_MCP_RESOURCE_URL=https://mcp.example.com
./scripts/run-server.sh       # binds 127.0.0.1:8000; put a TLS proxy in front

nginx の背後では、元の Host ヘッダーを必ず転送してください （proxy_set_header Host $host;）。提供されている deploy/nginx.conf では設定済みです。 これを設定しないと、DNS リバインディング保護によって認証済みのリクエストがすべて 421 で拒否され、「OAuth は動作するのにツール呼び出しはまったくできない」という状態になります。Caddy（deploy/Caddyfile）ではデフォルトで正しく処理されます。

ホスト型モードでは、サーバーは OAuth 2.0 リソースサーバー（MCP の認可仕様に準拠）として動作します。共有シークレットはなく、ディスクにも何も保存されません。

• 各 MCP クライアントは QCDatabase.AI で独自のユーザーとしてサインインします（このサーバーが公開する /.well-known/oauth-protected-resource ドキュメントから認可サーバーを検出し）、すべてのリクエストでそのユーザーのアクセストークンを Authorization: Bearer … として送信します。
• サーバーは /api/whoami/ に対してトークンを検証し、ユーザーを特定して、そのユーザーとして処理を行います。認証されていないリクエストには、クライアントを認可サーバーへ案内する WWW-Authenticate ヘッダーを付けて 401 を返すため、サインインは自動的に行われます。
• ユーザーごとのセッション状態（アクティブなプロジェクト）は、グローバルに一意な ID（テナント＋ユーザー ID。生のトークンは使用しません）をキーとしてメモリに保持されるため、多くのユーザーが 1 つのデプロイを共有しても、互いの作業が見えることはありません。検証に失敗した場合は安全側に倒し、ユーザーを特定できないトークンは拒否します。（状態は再起動時にリセットされます。ユーザーは set_project を再実行するだけです。）
• DNS リバインディング保護により、各リクエストの Host／Origin が検証されます（偽装された Host → 421、偽装された Origin → 403）。

ホスト型モードでは、login／logout ツールは何もしません（サインインはクライアント側で行います）。それ以外は stdio と同じように動作します。

ホスト型モードの設定（フラグは環境変数より優先されます）：

• QCDB_MCP_HTTP=1 — --http と同じです。
• --host / QCDB_MCP_HOST、--port / QCDB_MCP_PORT — バインド先です（デフォルトは 127.0.0.1:8000）。
• --resource-url / QCDB_MCP_RESOURCE_URL — このサーバーの公開 URL と OAuth リソース ID です。ループバック以外のホストにバインドする場合は必須です。
• --issuer-url / QCDB_MCP_ISSUER_URL — OAuth 認可サーバーです（デフォルトは https://qcdatabase.ai）。
• QCDB_MCP_ALLOWED_HOSTS / QCDB_MCP_ALLOWED_ORIGINS — 許可リストに追加するエントリーです （カンマ区切り）。追加のホスト名を経由する場合などに指定します。許可されたオリジンにのみ /mcp の CORS ヘッダーが付与されます。ブラウザーを利用するクライアントが接続できるよう、 そのクライアントのオリジンをここに追加してください。
• QCDB_MCP_SCOPES — 保護リソースのドキュメントでは scopes_supported として、401 チャレンジでは scope="..." として通知されるスコープです（スペース区切りまたはカンマ区切り）。デフォルトは stdio ログインで使用される、一般的な読み取りと書き込みのスコープと同じです。Claude などの MCP クライアントは通知されたスコープのみを要求するため、空のままにすると読み取り専用アクセスになります。 通知されるだけで、必須ではありません。より少ないスコープで承認されたトークンでも接続できます。 すべての値は、QCDatabase.AI が許可するスコープでなければなりません。
• QCDB_MCP_TOKEN_CACHE_TTL — 検証済みのトークンを信頼して /api/whoami/ に再確認するまでの秒数です （デフォルトは 60）。上流で失効したトークンがここで引き続き使用できる時間もこれに相当します。 この時間を短くするには、値を小さくしてください。
• QCDB_MCP_TOKEN_NEG_CACHE_TTL — 検証に失敗した結果を記憶する秒数です （デフォルトは 5）。これにより、無効なトークンによる API への負荷増大を抑えます。
• QCDB_MCP_STATELESS — サーバー側で MCP セッションを保持せずに各リクエストを処理します （デフォルトは 1）。有効のままにしてください。ステートフルなセッションは、再起動、再デプロイ、 複数レプリカ構成で機能しなくなります（「session not found」）。セッション内でサーバー起点の メッセージが必要な場合に限り、0 に設定してください。
• QCDB_MCP_JSON_RESPONSE — POST への応答として SSE ストリームではなく、プレーンな JSON を返します （デフォルトは 1）。有効のままにしてください。バッファリングプロキシ（nginx のデフォルト設定など） では SSE が停滞し、クライアントがタイムアウトします。このサーバーのツールはいずれも部分的な結果を ストリーミングしません。

TLS。 サーバーの手前にあるリバースプロキシで TLS を終端してください（プレーン HTTP を インターネットに公開しないでください）。実際の Host ヘッダーを転送してください。

リソースインジケーター（制約なし）。 このサーバーは QCDatabase が発行した有効なトークンを 受け付け、QCDB_MCP_RESOURCE_URL からリソース ID を取得するため、特別な AS の設定がなくても フォークして独自ドメインでホストできます。RFC 8707 の厳格なオーディエンスバインディングを行う場合、 運用者は認可サーバーを設定して MCP URL にバインドされたトークンを発行できますが、必須ではありません。

レプリカ間のスケーリング。 共有状態は、各ユーザーが固定したプロジェクトのみです。 サイズが小さく、秘密情報ではなく、破棄しても問題ありません（固定情報が失われた場合は set_project を再実行するだけです）。デプロイに適した方法を選んでください。

• 単一インスタンス（デフォルト）。 インメモリストアを使用するため、追加の実行作業はありません。 ほとんどのセルフホスト環境に最適です。
• スティッキーセッション。 ロードバランサーの背後に複数のレプリカを配置し、各ユーザーを同じ レプリカにルーティングします。引き続きインメモリですが、レプリカを再起動すると、そのユーザーの 固定情報は失われます。
• 共有ストア（Redis）。 QCDB_MCP_REDIS_URL を設定し、追加パッケージを インストールします（pip install 'qcdatabase-mcp[redis]'）。すべてのレプリカで状態が共有され、 再起動後も維持されます。固定情報は QCDB_MCP_SESSION_TTL 秒間アイドル状態が続くと期限切れに なります（デフォルトは 8h）。別のバックエンドを接続するには、hosted.py にある 2 つのメソッド get_active_project / set_active_project を持つストアを実装し、build_session_store から返してください。

（トークン検証キャッシュは意図的にレプリカごとに保持されます。各レプリカが /api/whoami/ からキャッシュを再構築するため、共有は不要です。）

MIT ライセンスの下でライセンスされています（LICENSE を参照）。