questlaw-library

QuestLaw Library MCP

• QuestLaw Library MCP
  • 概览
  • 快速开始
  • 设置与安装
  • 使用服务
  • 开发与发布
  • 许可证

概览

一个只读 MCP 服务，可让 AI 客户端搜索和阅读你的 QuestLaw 研究资料库。

项目状态

QuestLaw MCP 是一个实验性开源项目，用于将你的 QuestLaw 资料库连接到 AI 工具。

该服务会在你自己的设备上解密资料库，解密对象是通过扩展程序生成的 .qlvault 导出文件。它是只读的，不会建立网络连接。

免责声明

本项目不属于 QuestLaw 官方支持的产品套件。

使用本项目会在你的计算机上解密资料库，并将可读内容提供给你连接的 AI 客户端。该客户端会将读取的内容发送给其服务提供商。服务本身不会向任何地方发送数据，但无法控制客户端或服务提供商如何处理收到的数据。请充分了解这一点后再使用，并在连接包含敏感信息的资料库之前阅读 SECURITY.md。

工作原理

1. 在 QuestLaw 中，使用 Export 工具创建资料库的加密文件（questlaw-backup-<date>.qlvault）。
2. 服务会在你选择的文件夹中查找最新的导出文件。
3. 它使用你的账户密钥在_内存中_解密文件。你的资料库绝不会以未加密的形式写入磁盘。
4. 它会建立搜索索引并响应工具调用。

QuestLaw extension          your machine                         AI client
+--------------+            +---------------------------+        +----------+
| encrypted    |  export    | questlaw-library-mcp      | stdio  | Claude,  |
| library      |----------->|                           |<------>| ChatGPT, |
| (IndexedDB)  | .qlvault   | 1. reads the export       |  MCP   | ...      |
+--------------+   file     | 2. unwrap with your key   |        +----------+
                            | 3. decrypt in memory      |
      account key --------->| 4. build a search index   |
   (OS secret store)        | 5. answer tool calls      |
                            +---------------------------+
                            no network connections, no writes

快速开始

npx -y [email protected] setup

setup 会显示信息披露内容并请你确认接受，将你的账户密钥存储在操作系统的密钥存储中，查找最新的导出文件，对其进行解密测试，然后输出客户端的配置。之后若要检查安装状态：

npx -y [email protected] doctor

从克隆的仓库开始，运行与 node bin/questlaw-library-mcp.js setup 和 node bin/questlaw-library-mcp.js doctor 相同的命令。doctor 检查通过后，选择下方的一种安装方式。

设置与安装

要求

• Node.js 20 或更高版本。 推荐使用 24 或更高版本。
• QuestLaw 资料库导出文件。 请参阅 从 QuestLaw 导出资料库。
• 43 个字符的账户密钥。 请参阅 账户密钥。
• MCP 客户端。 例如 Claude Desktop、Claude Code、Codex，或任何支持通过 stdio 使用 MCP 的客户端。ChatGPT 需要使用 Secure MCP Tunnel。

从 QuestLaw 导出资料库

在扩展程序中，选择 export a backup。加密资料库会生成一个名为 questlaw-backup-<date>.qlvault 的文件。如果在扩展程序设置中启用每日备份，扩展程序每天都会写入一个新文件，让 AI 客户端无需你采取任何操作即可获取最新研究内容。

默认情况下，服务会读取 ~/Downloads 中最新的 .qlvault 文件。若要更改此设置，请将 QUESTLAW_VAULT_FILE 设为特定文件或其他文件夹。

服务读取的是导出时的资料库副本，而不是实时资料库。如果你在导出后添加了研究内容，模型必须等到你再次导出后才能看到这些内容。

**Word 加载项用户：**此服务只读取 .qlvault 导出文件。它无法访问你的 Word 文档，使用 Microsoft Copilot 也不会改变这一点。

你的账户密钥

导出文件的保险库密钥使用你的 43 个字符的账户密钥进行封装，因此服务器需要该密钥才能打开导出文件。请在扩展程序中依次打开 Settings, Encrypted library, Show account key 获取密钥，然后将其存储：

npx -y [email protected] setup

密钥的存储位置

平台	存储位置
macOS	登录钥匙串
Windows	%APPDATA% 下的 DPAPI blob
Linux	通过 secret-tool 使用 libsecret

在 macOS 和 Linux 上，密钥通过 stdin 传递给存储区。在 Windows 上，密钥通过子进程环境传递。密钥绝不会出现在命令行中。

账户密钥可以打开你知识库的所有导出文件，因此请像对待密码一样妥善保管。 你也可以通过 QUESTLAW_RECOVERY_CODE 提供密钥，但除非同时设置 QUESTLAW_ALLOW_ENV_KEY=1，否则服务器会忽略该变量。

安装

Claude Code 插件

该插件包含服务器以及一个用于向模型说明搜索工作原理的技能。请从 Releases 下载 questlaw-mcp-claude-plugin-<version>.zip，或使用 npm run plugin 构建。

通过 Claude 的 Plugins, Upload plugin 控件上传 ZIP（根据客户端不同，该控件位于 Customize 或 Settings 下）。同一个 ZIP 适用于 Claude Desktop 插件上传、Cowork 和 Claude Code。Cowork 和 Claude Code 会运行本地 MCP 服务，插件技能也可在聊天中使用。请参阅 Anthropic 的插件指南。

该插件无需配置。它会读取 ~/Downloads 中最新的 .qlvault、密钥存储区中 default 账户的密钥，以及 setup 记录的授权。上传插件前，请先运行 setup。

要替换已安装的副本，请先卸载，再上传新的归档文件：

claude plugin uninstall questlaw-library

Claude Desktop

• 插件上传： 使用上文所述的 questlaw-mcp-claude-plugin-<version>.zip。
• 桌面扩展： 使用 Releases 中的 questlaw-mcp-claude-desktop-<version>.mcpb，或使用 npm run bundle 构建。通过 Desktop 的扩展安装程序安装，并在必填的披露字段中输入 i-understand。

无论哪种方式，都请先通过 setup 存储密钥。

不使用插件的 Claude Code

claude mcp add questlaw-library -- npx -y [email protected]

Codex

codex mcp add questlaw-library -- npx -y [email protected]

或者直接将其添加到 ~/.codex/config.toml：

[mcp_servers.questlaw-library]
command = "npx"
args = ["-y", "[email protected]"]

[mcp_servers.questlaw-library.env]
QUESTLAW_VAULT_FILE = "/absolute/path/to/export_folder"

Codex 会将 config.toml 中的 env 值以纯文本形式保存。你可以将导出文件路径放在那里，但请将账户密钥保存在操作系统的密钥存储区中。设置 QUESTLAW_ALLOW_ENV_KEY 的目的，就是防止密钥落入此类文件。

ChatGPT 桌面应用包含 Codex 引擎，并读取同一个 ~/.codex/config.toml。如果你通过 Codex 添加该服务器，它可在桌面应用的 Codex 部分使用，但不能用于普通的 ChatGPT 聊天。如需在普通聊天中使用，请参阅下一节。

ChatGPT

ChatGPT 无法自行启动本地服务。它会通过 OpenAI 的 安全 MCP 隧道进行连接， 该连接只会从你的计算机向外发起。你需要在 ChatGPT 中启用开发者模式， 并拥有 OpenAI 开发者平台的访问权限。

一次性设置：

1. 在 platform.openai.com 上创建隧道（其 ID 以 tunnel_ 开头）和运行时 API 密钥。
2. 安装 tunnel-client， 可以从该页面安装，也可以使用 brew install tunnel-client 安装。
3. 创建配置文件。将隧道 ID 和两个路径替换为你自己的值：

export CONTROL_PLANE_API_KEY="sk-..."

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile questlaw \
  --tunnel-id tunnel_YOUR_TUNNEL_ID \
  --mcp-command "/path/to/node /absolute/path/to/questlaw-mcp/bin/questlaw-library-mcp.js"

tunnel-client doctor --profile questlaw --explain

4. 在 ChatGPT 中开启设置、安全与登录、开发者模式。
5. 在网页版 ChatGPT 中创建开发者模式应用，选择 Tunnel 作为连接方式，并选择你创建的隧道。截至撰写本文时，此选项可在网页版使用，但桌面应用中不可用。

每次需要使用时，启动隧道并保持运行：

tunnel-client run --profile questlaw

隧道客户端会为你启动 MCP 服务。检查两者是否都在运行：

pgrep -fl "tunnel-client|questlaw-library-mcp"

其他任何 stdio MCP 客户端

{
  "mcpServers": {
    "questlaw-library": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

只有在需要更改默认值时，才添加 env 块：

{
  "mcpServers": {
    "questlaw-library": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "QUESTLAW_VAULT_FILE": "/absolute/path/to/export_folder"
      }
    }
  }
}

此版本已固定，因此安装时会准确安装你检查过的版本。要升级，请更改客户端配置中的版本。

默认文件位置：

客户端	路径
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Code	~/.claude.json
Codex	~/.codex/config.toml
ChatGPT	无配置文件。请参阅 ChatGPT

setup 命令会输出适用于你计算机的确切配置。

检查安装

npx -y [email protected] doctor

  ok   vendored modules: 4 verified, from questlaw-extension @ 58d523c9 (synced 2026-10-07)
  ok   disclosure: accepted 2026-09-14T22:09:34.603Z
  ok   account key: found in login keychain as "default"
  ok   library export: questlaw-backup-2026-09-09.qlvault, 2.01 MiB, exported 11 days ago
  ok   decrypt: 341 records in 354ms -- 32 cases, 4 projects, 6 relationships, ...

5 passed, 0 warnings, 0 failing

使用服务

可用工具

工具	参数	用途
library_overview	无	介绍知识库包含的内容、项目、法院和标签，以及导出日期
list_cases	project、court、tag、sort、limit、offset	分页列出所有权威资料，或经筛选后的子集
search_library	query、types、limit、offset	对所有内容进行一次排序搜索
search_cases	query、project、court、tag、limit、offset	搜索符合条件的已保存权威资料
get_case	guid*	获取一份完整的权威资料，包括笔记、引文和相关案例
search_quotes	query、limit、offset	搜索符合条件的已保存引文
list_project_cases	projectId*、sort、limit、offset	列出某个项目下的所有内容
get_source_text	documentId*、outline、query、maxChars、offset、limit	获取法规、条例、规则或意见中捕获的文本
find_citation_mentions	text*、limit、offset	找出草稿中引用知识库已有权威资料的所有位置
reload_snapshot	无	重新读取磁盘上的最新导出内容

星号表示必填参数。types 参数接受 case、quote 和 source 中的任意值。tag 筛选器不区分大小写，并匹配完整标签；court 筛选器匹配法院名称中的任意部分。

典型的会话从 library_overview 开始，它会介绍知识库。随后，模型调用 search_library 查找内容，再调用 get_case 或 get_source_text 阅读全文。若要列出知识库内容而非进行搜索，模型可以不带参数调用 list_cases，并分页浏览所有权威资料，包括未归入任何项目的资料。

搜索有几项限制，会影响查询词的写法：

• 搜索匹配的是词语，而非含义，因此查询中需要包含用户可能会输入的词语。
• 法院名称是筛选参数，而非搜索文本。几乎所有法院名称都包含 “United States”、“Court” 或 “District”，因此搜索这些词会匹配几乎所有内容。
• 不支持通配符。查询中没有实际词语时，系统会列出知识库并说明这一点，而不是报告没有匹配项。

工具结果中包含你未撰写的文本，例如捕获的意见，同时也包含你自己的笔记。应将这些文本视为阅读材料，而非需要遵循的指令。 SECURITY.md 解释了原因。

配置

所有配置均通过环境变量完成，默认安装无需配置任何环境变量。

变量	默认值	作用
QUESTLAW_VAULT_FILE	~/Downloads	一个 .qlvault 导出文件，或一个从中选取最新文件的文件夹
QUESTLAW_KEY_ACCOUNT	default	保存密钥的 Secret Store 帐户：字母、数字、.、_、-
QUESTLAW_MAX_RESPONSE_BYTES	65536	每个结果的字节数上限，范围为 8 KiB 至 1 MiB
QUESTLAW_DISCLOSURE_ACK	unset	设置为 i-understand 即表示通过环境变量同意
QUESTLAW_ALLOW_ENV_KEY	unset	设置为 1 后，可由 QUESTLAW_RECOVERY_CODE 提供密钥
QUESTLAW_RECOVERY_CODE	unset	密钥本身。除非上面的设置为 1，否则会忽略
QUESTLAW_CONFIG_DIR	~/.questlaw-library-mcp	记录同意状态的位置

命令行

questlaw-library-mcp              serve over stdio
questlaw-library-mcp setup        disclosure, key custody, and client config
questlaw-library-mcp doctor       diagnose an install
questlaw-library-mcp consent      read the disclosure; --accept, --revoke, --status
questlaw-library-mcp verify       check the vendored modules against their digests
questlaw-library-mcp --version

setup 命令接受 --yes，可在不询问的情况下接受默认值；还接受 --key，可替换已存储的密钥。verify 命令接受 --json。

故障排查

首先运行 doctor。下表列出了服务返回的错误代码。

代码	含义	修复方法
disclosure_not_accepted	尚未表示同意	questlaw-library-mcp consent
account_key_unavailable	密钥存储中没有密钥	questlaw-library-mcp setup
invalid_key_account	QUESTLAW_KEY_ACCOUNT 包含不可用字符	使用 1-64 个字母、数字、.、_ 或 -
recovery_unwrap_failed	密钥无法打开此导出文件	检查密钥。轮换密钥后，请使用当前密钥
recovery_code_malformed	不是由 43 个 base64url 字符组成	重新复制，不要包含空格或换行符
vault_file_missing	服务查找的位置没有 .qlvault 文件	导出备份，或设置 QUESTLAW_VAULT_FILE
vault_file_unreadable	文件系统拒绝打开该文件	检查路径及其权限
invalid_export_file	不是可读取的导出文件	使用未经编辑的 questlaw-backup-*.qlvault
vault_integrity_failed	导出文件未通过完整性检查	重新导出备份
vendor_integrity_failed	供应商模块与其摘要不匹配	从可信来源重新安装。不要运行此安装命令
case_not_found、document_not_found	找不到具有该 ID 的记录	先搜索，再准确传入搜索结果中的 ID
invalid_argument、input_too_large	工具参数无效	消息中会指出相关参数

在桌面客户端中，如果从克隆仓库运行服务，请为 node 提供绝对路径。Claude Desktop 和 ChatGPT 桌面应用启动服务时不会加载你的 shell 配置文件，因此无法找到版本管理器中的裸 node 命令。密钥存储命令在 macOS 上通过绝对路径调用（/usr/bin/security），在 Windows 上则通过 %SystemRoot% 下的 powershell.exe 调用。在 Linux 上，secret-tool 必须位于默认 PATH 中。

开发与发布

git clone https://github.com/questlaw/questlaw-mcp.git
cd questlaw-mcp
npm test

该服务没有运行时依赖，也无需构建步骤。npm install 会添加 eslint，只有 npm run lint 会用到它。

命令	功能
npm test	使用已提交的测试样例运行测试套件
npm run lint	运行 eslint（需先执行 npm install）
npm run check	运行 verify、供应商代码漂移检查和测试。发布前必须运行
npm run eval	根据已记录的基线衡量搜索相关性
npm run bench	仅供维护者使用：构建包含 2,000 个用例的库并进行测量
npm run bundle	为 Claude Desktop 构建 dist/questlaw-mcp-claude-desktop-<version>.mcpb
npm run plugin	构建用于上传到 Claude 插件、Cowork 和 Claude Code 的 dist/questlaw-mcp-claude-plugin-<version>.zip
npm run vendor:sync	仅供维护者使用：再次从代码检出目录复制四个核心模块
npm run vendor:check	如果供应商代码副本与代码检出目录不再一致，则报错
npm run fixture:regen	仅供维护者使用：重新构建已提交的测试样例

CONTRIBUTING.md 介绍了修改的工作流。 REFERENCE.md 说明了导出格式、解密步骤、记录架构、供应商代码模块、项目布局以及测试强制执行的规则。修改 src/ 或 vendor/ 下的任何内容之前，请先阅读。

要让客户端使用你的克隆版本，而不是 npm 上的版本：

{
  "mcpServers": {
    "questlaw-library": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/questlaw-mcp/bin/questlaw-library-mcp.js"]
    }
  }
}

npm run bundle 只打包 package.json 中 files 下列出的文件，会检查清单版本是否匹配、入口文件和每个供应商代码模块是否存在，并生成 .mcpb。它需要系统中的 zip 命令。在 Windows 上，请改用 npx @anthropic-ai/mcpb pack。

npm run plugin 会将 .claude-plugin/plugin.json、.mcp.json 和 skills/ 放在 ZIP 根目录下，并将 npm 会发布的文件放入 runtime/，因为 Claude 拒绝上传包含顶层 bin/ 目录的插件。 插件的 .mcp.json 中绝不能放入 ${user_config.*}。原因请参阅 REFERENCE.md 中的“陷阱”部分。

许可证

GPL-3.0-or-later。请参阅 LICENSE。

该许可证涵盖 vendor/questlaw/ 中的四个文件。这些文件复制自 QuestLaw 浏览器扩展的源代码，并有意随本软件包一同发布。