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 服务

将此内容放入文件中。如果文件中已有其他服务，只需将 "qcdatabase" 代码块添加到现有的 "mcpServers" 部分中。

Windows：

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

Mac（通常使用 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"]
    }
  }
}

（在 JSON 中使用 Windows 路径时，请使用双反斜杠 \\。）

4. 重启 Claude Desktop

完全退出并重新打开应用（在 Windows 上，还要从系统托盘中将其关闭；在 Mac 上，使用 Cmd-Q 退出——仅关闭窗口还不够）。新服务只有在全新启动时才会加载。

5. 确认服务已加载

开启新聊天，找到工具/连接器指示图标（消息框附近的滑块或工具图标）。点击后，你应该会看到 qcdatabase 及其工具列表。如果没有，请参阅故障排除。

然后让 Claude “connect to QC Database” 以登录——见下文。

---

首次使用

1. 登录。让助手 connect to QC Database（login 工具）。浏览器会打开；登录并选择要连接的公司工作区。此选择会将连接绑定到该组织。只需操作一次——系统会记住你的选择。

2. **选择项目。**让它按名称对某个项目 work on，或先列出你的项目。几乎所有操作都在某个项目“内部”进行，因此服务会要求你先选择一个项目，然后才能执行项目相关工作。你可以随时切换项目。

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（在同一张图纸/模式上批量处理最多 500 个项）。务必先调用 list_map_item_schemas——请参阅下方关于 CAD/PCF/.weldb 的说明
• Zipmaps（一次上传整张已映射的图纸）： inspect_zipmap、 upload_zipmap——请参阅 Zipmaps（一次上传整张已映射的图纸）
• 修复： 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）。锁是施工质量关卡，不是安全控制；只有在其所有者/创建者或授权检查员明确要求时，才能设置或清除锁。此处不会提供创建或编辑锁类型（具名停检定义，以及谁可以设置/清除每种停检点）的功能——这类权限敏感的设置需在 Web 应用的 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:read/trainings:write 权限。 发布、取消列出和重新分配所有者仍需在 QC Database Web 应用中完成。
• 培训合规： assign_training 和 invite_users（管理员；两者在 confirm=True 前都只会预览，最多 200 人）、list_assignments（培训矩阵：必修培训的已完成/即将到期/逾期/已过期，以及已阻止/宽限状态）、list_permission_requirements（哪些权限需要当前有效的培训；只能在 Web 应用中设置）和 get_my_trainings（任何成员均可调用，一次调用即可获取必修和已完成的培训、结果、链接及受限权限）。受培训限制的操作（接受地图项或 ITP 行项目、锁定操作、受限表单）可能会因 training_required 而失败；错误信息会列出培训名称、到期时间以及参加培训的链接。
• 培训竞赛： get_training_leaderboard（任何可以参与游戏的成员均可调用：按人员、用户类型、项目角色或项目列出最佳成绩排名，并显示你自己的名次）和 get_engagement_report（管理员可用：查看重玩次数、自愿参与次数、培训时长、多人游戏、分数提升情况，以及无人重玩的培训；范围可以是工作区、项目或某个培训）。
• 团队会话（实时多人游戏）： start_crew_session（已发布的多人培训；返回加入码、加入链接和团队扫描后即可一起游戏的二维码链接，也可以选择在应用内邀请项目）、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 培训构建者可以查看分配给自己的构建请求，并使用常规培训工具完成每个构建（包括审查，不收费）；客户管理员可以查看自己的请求和报价。申请报价、接受投标、接受培训及变更单都在培训页面中处理。
• 团队： list_crews（管理员可用）；使用 assign_training 和 {type: 'crew', crew_id} 将培训分配给团队。团队需在 Web 应用中编辑。
• 社区论坛（所有 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 权限。版主管理仍需在 Web 应用中完成。
• 实用工具： generate_qr_code

---

CAD、PCF 和 .weldb 系统的搭档

在 MCP 中，地图项类型定义是只读的：可以发现类型，但不提供创建、编辑或升级操作。记录编辑和导入会绑定到现有架构 ID；归档架构不会作为新类型安装。

允许创建和编辑列表及文档类型，但由于缺少 API 写入契约，这些操作会被阻止。移动文档文件夹以及将包标签放在 LFD 上也会被 API 阻止；将图纸移至包中不等同于添加 LFD 包标签。具体缺失项请参阅 API 交接文档。托管生产环境需要重新发布并刷新客户端工具发现，新工具才会显示；仅在开发环境中验证不会更新生产环境。

此服务天然适用于已描述几何图形的系统——CAD/CAE 导出文件、PCF 管道文件，以及 .weldb 锅炉制造商更换面板文件。这些来源包含构建优质地图项所需的大部分信息，因此助手可以据此生成准确的焊缝图——前提是遵循两个习惯：

1. 先获取架构。 在调用 create_map_item / bulk_create_map_items 之前，务必先调用 list_map_item_schemas。这样可以选对架构并查看其确切字段，让来源中的值填写到正确位置，而不是靠猜测或填写自由文本：
   • PCF（管道）文件包含管道焊缝所需的大部分信息——接头类型、材料、重量/Sch。
   • .weldb 文件包含材料、管壁厚度以及焊缝在图纸上的矩形位置——这些信息足以自动构建焊缝图。
2. 匹配来源的几何形状——点焊缝与矩形焊缝。 这是影响数据质量的关键。PCF 管道焊缝是单个点焊缝（一个 x/y 坐标）。.weldb 焊缝具有矩形位置——将第二个点（x_position_2/y_position_2）设为对角点，以保留范围。将矩形焊缝简化为单个点（或将点焊缝扩展成方框）会在不提示的情况下破坏地图数据。提前获取架构，就能在放置任何项目前清楚地看到这一区别。

---

Zipmaps：在一次上传中提交完整的映射图纸

zipmap 是一个普通的 zip 文件，其中打包了一张图纸（PNG，可选附带单页源 PDF）、已放置在图纸上的所有地图项，以及描述这些项类型的 JSON Schemas。这是“自带 AI”的交接方式：由你的模型、CAD 导出工具或工程量统计工具生成地图，再由 QC Database 导入。

upload_zipmap 将原先的三步操作（上传图纸 → 等待 → 针对图纸批量创建地图项）替换为一个事务性请求。图纸、所有 Schema 中的地图项及其提取的数据会一并创建，或者全部不创建。服务器不会在其上运行 AI；地图由你提供。

用自然语言提出请求即可：“将此 zipmap 上传到 Unit 2 hydro package。” 在此之前，助手会先完成三件事：

1. inspect_zipmap — 无需上传即可查看文件内容：图纸大小、每种类型的地图项数量、这些地图项使用的数据字段，以及哪些类型尚未绑定到 QC Database 地图项 Schema。
2. list_map_item_schemas / get_map_item_schema — zipmap 在本地命名其类型（weld、heat）；QC Database 则通过 id 标识 Schema。任何未绑定的类型都必须与其所属的 Schema 配对（schema_ids={"weld": "<id>"}），并通过比较类型字段与 Schema 字段来确认匹配。生成方可以预先将 id 写入归档中的 schemata/<type>.schema.json，省去此步骤。
3. list_packages — 新图纸必须归档到某处，而 API 要求提供 package id。请先选择（或 create_package）范围对应的 package。

坐标以 zipmap 的 PNG 像素为单位（原点在左上角，y 轴向下），与 QC Database 使用的坐标空间完全一致，因此不会缩放或翻转。如果项目使用按 Schema 自动编号，编号会优先于 zipmap 的地图项 id，结果中会将每个新地图项对应到其原始 id。

要重新发送修正后的地图？mode="replace" 会先软删除该 package 中编号相同的所有现存图纸（保留在审计记录中，从图纸列表中移除，其地图项也会随之移除），而不是留下重复项。默认模式 mode="append" 始终会创建新图纸。

所有可在本地检查的内容都会在上传之前检查——缺少 PNG、类型没有 Schema id、坐标超出图纸范围、会导致所有地图项错位的 PDF 坐标——因此地图有问题时，几秒内就会失败并列出需要修正的内容，而不是等到传输完数 MB 数据后才失败。

Zipmap 从你自己的计算机读取，因此可通过本地（stdio）服务使用此功能。托管服务不会接触你的磁盘（参见 文件系统安全）。

---

关于签核

将工作标记为已完成或已验收，即表示批准——系统会以你的姓名和当前时间记录此操作。助手可以代你执行这些操作，但每个相关工具都会明确告知你，该操作由你负责。服务器绝不会在未经告知的情况下签核。请将这些视为由你决定、并在你明确同意后执行的操作。

---

隐私与安全

• 服务在本地运行，只与 https://qcdatabase.ai 通信。
• 你的登录固定到一个组织（在登录时选择），会话也固定到一个项目——因此助手不会意外访问其他工作区或项目。
• 服务仅请求普通用户所需的权限；按设计不涉及管理员操作。
• 你可以随时在 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 模式——上传工具会读取你指定的文件，下载/导出工具会将文件写入你选择的路径。在 hosted 模式下，服务会拒绝所有本地文件系统访问，因为磁盘属于服务所在的机器，而非你的机器（在这种模式下上传/下载需要通过客户端文件通道进行）。

这些规则由 server.py 中的 _guard_local_path 在代码中强制执行。

---

故障排查

• 重启后，Claude Desktop 中没有显示 "qcdatabase"。
  1. 确保已完全退出应用（Windows 上通过系统托盘退出，Mac 上按 Cmd-Q），然后重新打开。
  2. 检查配置文件是否为有效的 JSON——缺少逗号或大括号会导致所有服务无法加载。如不确定，可将其粘贴到 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（位置见隐私与安全），然后重新登录——这会使用当前权限重新注册应用。
• 登录时浏览器没有打开。 助手会显示一个链接——手动打开链接完成操作，然后重新登录。
• 登录页面无法连接 / 端口已被占用。 登录会使用本地 Web 地址上的 8765 端口。如果该端口正被其他程序使用，请在启动应用前添加环境变量 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 通信——供一位本地用户使用，通过 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，绝不使用原始令牌）为键，因此许多人可以共用一个部署，而不会 看到彼此的工作。验证失败时会拒绝访问——无法解析出用户的令牌将被拒绝。 （重启后状态会重置——用户只需重新运行 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）。请保持开启：有状态会话在重启、重新部署和多副本设置时会中断（“找不到会话”）。只有需要在会话中由服务端发起消息时才设为 0。
• QCDB_MCP_JSON_RESPONSE — 使用纯 JSON 而非 SSE 流响应 POST 请求（默认值为 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 中实现包含两个方法的存储，并从 build_session_store 返回该存储（get_active_project / set_active_project）。

（令牌验证缓存有意按副本独立维护——每个副本都会从 /api/whoami/ 重建缓存，因此无需共享。）

根据 MIT 许可证授权（参见 LICENSE）。