Vaquill

vaquill-mcp

Vaquill 法律研究 API 的 MCP 服务，适用于 Vaquill。涵盖美国联邦和 50 个州的主要法律：美国法典（USC）、联邦法规（CFR）、州法令和法规、州宪法和美国宪法、法院规则、《联邦公报》、行政命令以及机构指南。使用 AI 工具即可搜索主要法律、解析法条引文、浏览层级结构，并依据官方来源生成答案。

快速开始

前提条件

在 vaquill.ai 注册以获取 API 密钥。

Claude.ai（Web）

无需安装。从 Customize > Connectors > Add custom connector 添加为远程 MCP 服务：

选项 A：Bearer 令牌（推荐）

打开同一对话框中的 Request headers 部分，并在那里添加凭据：

URL:            https://mcp.vaquill.ai/mcp
Header name:    Authorization
Header value:   Bearer vq_key_your_key_here

Claude 会原样发送你输入的值，不会自行添加任何方案，因此值 字段中应填写 Bearer vq_key_...，而不是 Authorization: Bearer vq_key_...。

选项 B：URL 中的 API 密钥（兼容方式）

https://mcp.vaquill.ai/s/vq_key_your_key_here

此方式仍然有效，而且在客户端完全无法发送 标头时，这是唯一可用的方式。其他情况下请优先使用选项 A：URL 中的凭据会记录在服务器日志、代理和浏览历史中，因此 Anthropic 的 连接器指南建议不要这样做，MCP 规范也禁止这样做。

Claude Pro、Max、Team 和 Enterprise 方案均可使用。Request headers 部分处于 Beta 阶段，按账户启用，只接受简短的标头名称许可列表，且最多可添加四个。在 Team 和 Enterprise 方案中，所有者需先在 Organization settings 中添加连接器。

Claude Desktop

通过 Settings > Developer > Edit Config 打开配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}

如需使用印度法律，请添加 --jurisdiction IN。每个进程只能服务一个 语料库，因此如果两者都要使用，请运行两个条目：

{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": { "VAQUILL_API_KEY": "vq_key_your_key_here" }
    },
    "vaquill-india": {
      "command": "uvx",
      "args": ["vaquill-mcp", "--jurisdiction", "IN"],
      "env": { "VAQUILL_API_KEY": "vq_key_your_key_here" }
    }
  }
}

完全退出 Claude 后重新打开。它不会重新加载文件。

Claude Code

远程（无需安装）：

claude mcp add --transport http --scope user vaquill \
  https://mcp.vaquill.ai/mcp \
  --header "Authorization: Bearer vq_key_your_key_here"

本地（通过 uvx）：

claude mcp add --scope user vaquill -e VAQUILL_API_KEY=vq_key_your_key_here \
  -- uvx vaquill-mcp

--scope user 会为每个项目注册服务；默认情况下只对当前目录生效。-e 会将密钥与注册信息一同保存，因此即使从 IDE 启动 Claude Code，密钥也不会丢失，而在 shell 配置文件中使用 export 则无法做到这一点。--header 和 -e 都支持可变参数，因此必须放在服务名称之后。

Cursor

如需对每个项目生效，请编辑 ~/.cursor/mcp.json；如只需对一个项目生效，请编辑 .cursor/mcp.json。

远程：

{
  "mcpServers": {
    "vaquill": {
      "url": "https://mcp.vaquill.ai/mcp",
      "headers": {
        "Authorization": "Bearer vq_key_your_key_here"
      }
    }
  }
}

本地（通过 uvx）：

{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}

VS Code（Copilot）

添加到 .vscode/mcp.json。如需对每个项目生效，而非仅对一个项目生效，请运行 MCP: Open User Configuration 命令，并在那里使用相同的配置格式。

远程：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "vaquill-authorization",
      "description": "Authorization header value",
      "password": true
    }
  ],
  "servers": {
    "vaquill": {
      "type": "http",
      "url": "https://mcp.vaquill.ai/mcp",
      "headers": {
        "Authorization": "${input:vaquill-authorization}"
      }
    }
  }
}

凭据通过提示词输入，而不是保存在文件中，因此可以安全地提交该文件。VS Code 会在首次启动时询问凭据，并记住它。保存后请重启服务，否则工具不会显示。

本地（通过 uvx）：

{
  "servers": {
    "vaquill": {
      "type": "stdio",
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json。

远程：

{
  "mcpServers": {
    "vaquill": {
      "serverUrl": "https://mcp.vaquill.ai/mcp",
      "headers": {
        "Authorization": "Bearer vq_key_your_key_here"
      }
    }
  }
}

Windsurf 使用 serverUrl 而非 url 来指定远程服务；如果你想从环境中读取凭据，它也会解析 ${env:VAR}。

本地（通过 uvx）：

{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}

可用工具

工具会在启动时根据 Vaquill API 的实时 OpenAPI 规范生成，因此工具集始终与当前 API 保持一致。如需获取权威且最新的工具列表和每次调用的积分费用，请运行免费的 get_pricing 工具，或查看 MCP 客户端的工具列表。

美国服务器提供 26 个工具，印度服务器提供 22 个，均包含 search 和 fetch。所有工具都为只读。法律变更提醒（看板和监控）有意不作为 MCP 工具提供：API 仍支持这些功能，因此请在 Vaquill 控制台中创建和管理提醒，或直接通过 REST API 操作。

主要工具组（以下为代表性工具）：

美国法规与规章

美国法典（USC）、《联邦法规汇编》（CFR）、全部 50 个州的法典、宪法、州法院规则、《联邦公报》以及机构指导文件。

工具	说明
search_us_statutes	混合语义与关键词搜索；可按 corpusType、state、titleNumber、chapter、年份等筛选。
get_us_statute_section	根据 actId 获取条款元数据（引文、层级、官方来源链接）。
get_us_statute_section_text	获取条款的完整 HTML 和纯文本。
get_sections_batch	单次调用最多获取 50 个条款的元数据。
resolve_statute_citation	将 Bluebook 引文（例如 42 U.S.C. § 1983）直接解析到对应条款。可选的 state（2 个字母的代码或 federal）和 corpusType 会作为筛选条件；若真实引文不符合这些条件，响应会包含 citationOutsideFilters。
list_statute_divisions	一次浏览一个层级的法规结构。
list_statutes_coverage	自描述式覆盖范围矩阵：显示各司法辖区包含哪些法规语料。

在上下文中阅读条款

工具	说明
get_section_neighbors	按法规顺序紧邻该条款的前后条款。
get_section_definitions	管辖该条款的定义术语，来自其所在章节的定义条款。
get_section_cited_by	哪些 USC/CFR 条款交叉引用了该条款（即 crossReferences 的反向关系）。
get_section_cross_state	其他州涉及同一主题的条款，按相似度排序。
get_section_changes	刷新过程中观察到该条款随时间发生的变化。

实用工具

工具	说明
get_pricing	API 实时积分价格（免费，无需身份验证）。
search	通用单字符串语料搜索，返回 {id, title, url}。
fetch	通用单字符串检索，返回 {id, title, text, url, metadata}。

提供 search 和 fetch 是因为 ChatGPT 的深度研究和公司知识连接器会通过这些确切名称及其单字符串签名来匹配语料服务器，没有它们就无法工作。它们是上述类型化工具的轻量封装；任何能够调用类型化工具的客户端都应优先使用这些工具：类型化工具可按司法辖区、语料、日期和状态筛选，而这两个通用工具不支持这些筛选。fetch 对其 id 的格式有意保持宽容，接受 act_id、引文 URL、纯路径，或诸如 42 U.S.C. 1983 的 Bluebook 引文。

资源和提示词

此服务不只有工具。根据 OpenAPI 文档生成的 MCP 服务会为每个端点发布一个工具，不提供其他内容；这两类基本元素承载着 API 中没有的知识，而且不会占用每轮工具预算。

资源（读取，不要调用）：

资源	内容
vaquill://guide	如何正确使用语料库：标识符规则、“仍然有效的法律”在此处的实际含义、变更列表为空能说明什么、不能说明什么，以及费用所在。没有任何端点为其提供支持。
vaquill://us/coverage	覆盖情况矩阵：每种 corpusType 及其按司法管辖区统计的数量。免费。
vaquill://in/filters	印度语料库实际包含的筛选词汇。免费。
vaquill://pricing	实时积分定价。免费。

提示词（内置陷阱的工作流）：

提示词	所包含的内容
good_law_check(citation)	actStatus 与 goodLawStatus、amendmentHistory 的区别，以及为什么 unknown 表示尚未核查，而非当前有效。
fifty_state_survey(topic, states)	先检查覆盖情况，避免将“没有此类法律”与“我们的语料库中没有”混为一谈。
whats_changed(since, corpus, state)	变更捕获记录的是观察结果，而非法律效力；结果为空不代表“没有任何修订”。
cite_check(text)	批量解析，而不是循环处理；然后根据各条款核实段落中的主张。
old_code_citation(citation)	印度：回答前，先将 IPC/CrPC 映射到自 2024 年 7 月 1 日起生效的 BNS/BNSS 条款。
indian_provision_check(question)	印度：先阅读筛选词汇，并准确说明修订相关的注意事项。

印度立法

同一主机上的独立端点。中央和州法律，以及主要监管机构（SEBI、RBI、MCA、IRDAI、TRAI、DGFT）的法规：共 22,265 项法令，1,098,577 个可单独寻址的条款。

https://mcp.vaquill.ai/in/mcp        with Authorization: Bearer vq_key_your_key_here
https://mcp.vaquill.ai/in/s/vq_key_your_key_here      key in the path, as above

使用相同的 API 密钥和积分余额，与美国端点相同。

工具	描述
search_acts	搜索印度立法，精确到条款。
list_acts	按司法管辖区、监管机构、年份和状态浏览并筛选法令。
list_act_filters	语料库实际包含的筛选词汇及数量。
get_act_text	获取单项法令的来源链接（文本、PDF、HTML）。
get_act_amendments	修订历史：更改内容、修订该法令的法律及生效时间。
search / fetch	上文所述的同一通用工具对，用于印度立法。
get_corresponding_provisions	将已废止的刑事法典映射到其 2023 年替代版本（IPC 对应 BNS，CrPC 对应 BNSS）。

一个端点仅服务一个司法管辖区，这是有意为之。 美国和印度的 OpenAPI 文档彼此独立，每个应用都从其中一份文档生成完整工具集，因此 /mcp 或 /s/ 下的任何内容都无法提供印度工具，/in/ 下的任何内容也无法提供美国工具。挂载路径用于选择应用，而非筛选应用，因此无需担心每个请求中的检查出错。这样也能让集成方的上下文窗口仅包含其实际处理的司法管辖区。

环境变量

变量	必填	默认值	描述
VAQUILL_API_KEY	是	-	来自 vaquill.ai 的 API 密钥（vq_key_...）
VAQUILL_BASE_URL	否	https://api.vaquill.ai	API 基础 URL
VAQUILL_TIMEOUT	否	120	请求超时时间，单位为秒
VAQUILL_JURISDICTION	否	US	仅适用于 stdio 服务。 US 或 IN。选择 OpenAPI 文档，也就决定了完整工具集。托管服务会忽略此变量，并通过不同路径提供两个司法管辖区。

仅限托管服务

以下变量适用于 vaquill-mcp-remote（部署在 mcp.vaquill.ai 后面的服务），stdio 服务会忽略这些变量。

除非设置了完整的 VAQUILL_OAUTH_* 变量组，否则 OAuth 处于关闭状态，服务 的行为与 OAuth 出现之前完全相同。若变量组不完整，服务会在启动时出错，而不会提供 不完整的发现文档，因为 Claude 会按 URL 在所有用户之间全局缓存发现信息约 五分钟，因此错误信息会在导致它的配置错误消失后仍然存在。

变量	必填	默认值	说明
HOST	否	0.0.0.0	监听地址
PORT	否	8000	监听端口
VAQUILL_PUBLIC_URL	使用 OAuth 时必填	-	此服务的公开 URL（https://mcp.vaquill.ai）。它会成为 OAuth 颁发者，并作为受保护资源文档中的 resource。Claude 要求该值与用户输入的 URL 完全一致，包括路径。
VAQUILL_INTERNAL_SECRET	使用 OAuth 时必填	-	用于将 OAuth 用户解析为其 vq_key_ 的共享密钥。必须与 API 上的 MCP_INTERNAL_SECRET 相同。若未设置，OAuth 调用方会通过身份验证，但在首次工具调用时失败。
VAQUILL_OAUTH_UPSTREAM_JWKS_URI	使用 OAuth 时必填	-	https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json。若 keys 为空，表示项目仍在使用对称 HS256，无法验证任何令牌。
VAQUILL_OAUTH_UPSTREAM_ISSUER	使用 OAuth 时必填	-	https://<project-ref>.supabase.co/auth/v1
VAQUILL_OAUTH_AUTHORIZE_URL	使用 OAuth 时必填	-	https://<project-ref>.supabase.co/auth/v1/oauth/authorize
VAQUILL_OAUTH_TOKEN_URL	使用 OAuth 时必填	-	https://<project-ref>.supabase.co/auth/v1/oauth/token
VAQUILL_OAUTH_CLIENT_ID	使用 OAuth 时必填	-	在上游注册的静态客户端。动态客户端注册保持关闭；此服务本身就是 DCR/CIMD 门面。
VAQUILL_OAUTH_CLIENT_SECRET	使用 OAuth 时必填	-	该客户端的密钥
VAQUILL_OAUTH_ALGORITHM	否	ES256	必须与上游签名密钥匹配。如果项目已迁移到 RSA，则使用 RS256。
VAQUILL_OAUTH_AUDIENCE	否	authenticated	上游令牌中预期的 aud

在上游注册的唯一重定向 URI 是 https://mcp.vaquill.ai/auth/callback。 不要同时注册 Claude 的（https://claude.ai/api/mcp/auth_callback）或 Claude Code 的环回地址：此服务会代理整个流程，因此上游不会看到这些地址；RFC 8252 要求的 临时端口匹配也由此处处理。

示例用法

配置完成后，你可以向 AI 助手提问，例如：

• “17 CFR 240.10b-5 对内幕交易有何规定？”
• “解析 42 U.S.C. § 1983，指出其所属章节并展示全文”
• “查找加利福尼亚州关于房东维修义务的法规”
• “浏览德克萨斯州法典，然后深入查看《刑法典》”

开发

# Clone and install
git clone https://github.com/Vaquill-AI/vaquill-mcp.git
cd vaquill-mcp
uv sync --all-extras

# Run locally
VAQUILL_API_KEY=vq_key_... uv run vaquill-mcp

测试

测试套件无需 API 密钥，也无需访问网络。所有测试都使用已检入的 tests/fixtures/ 中的 OpenAPI 固定数据运行，而 tests/conftest.py 会让 任何未模拟的 HTTP 调用报错，因此克隆项目并运行 uv sync 即可完成全部设置。

uv sync --extra dev --extra remote
uv run pytest                                    # 407 tests
uv run pytest -W error::DeprecationWarning       # what CI runs

CI（.github/workflows/test.yml）运行两个任务，而且它们并非有意重复。 test 会在 Python 3.10-3.13 上使用锁定环境运行测试套件。wheel 会构建软件包， 将其安装到一个不使用锁文件的新建 venv 中，并在那里运行相同的测试套件。第二个任务 复现了客户使用 uvx vaquill-mcp 时的情况：锁文件无法约束通过已发布 wheel 安装的用户， 因此依赖项发布破坏性大版本的问题会在该任务中显现，而不会在其他任务中显现。

# Test with FastMCP inspector
uv run fastmcp dev src/vaquill_mcp/server.py

安全

请向 [email protected] 报告漏洞（参见 SECURITY.md 和 https://www.vaquill.ai/security/vulnerability-disclosure）。

将此服务连接到拥有其他工具的 Agent 前，有两点值得了解：

• 此服务是只读的。 每个工具都带有 readOnlyHint: true 和 destructiveHint: false，且不会写入、发送或删除任何内容。这些提示描述的是工具的能力，并非安全控制措施；除非信任某个服务，否则客户端应将来自任何服务的注释视为不可信内容。
• 返回的文本来自第三方。 法规、公告、机构决定和会期法律来自政府出版方（部分语料还来自供应商收集的内容和 OCR）。我们会清理标记，并将来源链接限制为政府网站，但不会过滤其中的指令性措辞；openWorldHint: false 描述的是可访问范围，而非来源。此服务会发送一条 instructions 说明这一点；即使客户端忽略该说明，也应将工具输出视为不可信内容。

工作原理

此软件包是围绕 Vaquill Developer API 构建的轻量 MCP 封装。启动时，它会从在线 API 获取 OpenAPI 规范，并使用 FastMCP 自动生成 MCP 工具。工具名称会根据每个端点的 OpenAPI operation id 自动生成，因此新增的 API 端点无需更新软件包，就能成为简洁易用的工具；关键描述也经过优化，以提升大模型的表现。唯一的例外是 server.py 中的短排除列表（_ROUTE_MAPS）：SSE 流式传输路由和法律变更提醒路由。这是产品决策，而非技术限制。

由于规范是在启动时获取的（而非随软件包一起打包），工具会自动反映 API 的任何更改，无需更新软件包。

致谢与定价

API 调用会消耗额度。上方表格中的额度费用以撰写本文时为准；get_pricing 工具和每个工具自身的描述始终反映实时价格，因此如有差异，应以它们为准。

1 个额度 = $0.01 USD

许可证

MIT

社区

有问题、想法或想要贡献？加入 Vaquill 的 Discord 社区。