Lancelot

Lancelot

Lancelot 是一个 MCP 服务，可针对本地 LanceDB 数据库响应搜索和检索查询。设置 API 密钥后，它会使用 OpenAI 嵌入进行向量搜索；未设置时，则进行纯文本匹配。

它会读取数据库文件夹，但绝不会写入其中。它通过标准输入输出传输 MCP，也可使用 --http 通过 Streamable HTTP 传输（请参阅 HTTP 模式）。

基于 Ayers 文档的公开只读实例位于 https://mcp.ayers.repair/lancelot。任何支持 Streamable HTTP 的 MCP 客户端都可以使用该 URL。文档已通过 lancelot-index 构建到一个表中。

工具

工具	功能
lancedb_search	搜索表并返回带有简短摘要的排序结果。
lancedb_query	检索与问题相关的文本块，并将其作为一个上下文块返回，长度不超过字符数限制。
lancedb_status	报告连接状态、各表的行数，以及嵌入是否可用。
lancedb_version	报告 Lancelot 版本、其所基于的 SDK 的 MCP 协议版本，以及已启用的功能。

lancedb_search

参数	类型	必填	含义
query	string	是	搜索文本。
limit	number	否	结果数量上限，范围为 1 到 200。默认值：LANCEDB_DEFAULT_LIMIT，即 20。
searchType	vector、text 或 auto	否	vector 使用 OpenAI 将查询转换为嵌入。text 在文本列中匹配单词。auto（默认值）会在设置了 API 密钥时使用向量搜索，否则使用文本搜索。
table	string	否	要搜索的表。默认值：LANCEDB_TABLE。
textColumn	string	否	存放文本的列。默认值：LANCEDB_TEXT_COLUMN。
vectorColumn	string	否	存放向量的列。默认值：LANCEDB_VECTOR_COLUMN。

回复为 JSON。其 searchType 字段表示产生结果的搜索类型，即 vector 或 text。如果与请求的搜索类型不同，note 字段会说明原因：未设置 API 密钥、向量搜索失败，或在 auto 模式下没有找到结果。对于向量结果，score 表示距离，数值越低越接近。对于文本结果，score 表示结果中命中的查询词占比，数值越高越好。

文本搜索会对查询中的词进行不区分大小写的子串匹配。它不使用全文索引，也不会对单词进行词干提取。

lancedb_query

参数	类型	必填	含义
question	string	是	要为其检索上下文的问题。
contextBudget	number	否	上下文的最大字符数。默认值：LANCEDB_CONTEXT_BUDGET，即 8000。
warmStart	boolean	否	检索项目概览，而不是回答 question。默认值：false。
table	string	否	要查询的表。默认值：LANCEDB_TABLE。
limit	number	否	检索文本块的数量上限，范围为 1 到 200。默认值：LANCEDB_DEFAULT_LIMIT。

回复是一个 Markdown 块：包含一个标题（模式、搜索类型、查询），随后每个文本块各有一个部分，列出其标题、来源和文本。超出字符数限制的文本块会被省略，并说明省略了多少个。

lancedb_status

参数	类型	必填	含义
verbose	boolean	否	包含各表的列名。默认值：false。

lancedb_version

无参数。

表结构

Lancelot 从文本列（默认为 text）读取文本。有相应字段时，它会读取 title 作为标题，并读取 chunkSource、docSource 或 path 作为来源；前两个字段是 AnythingLLM 写入的结构，path 则由 lancelot-index 写入。其他列会作为 metadata 返回。向量搜索要求使用与 EMBEDDING_MODEL 相同的模型生成向量。

安装

Claude Code，使用 Claude Code MCP 文档中的 stdio 形式：

claude mcp add --env LANCEDB_PATH=/path/to/db --env OPENAI_API_KEY=... --transport stdio lancelot -- npx -y @ayerselectronics/lancelot

--transport stdio 特意放在最后一个 --env 和服务名称之间：CLI 会直接将 --env 后面的名称读取为另一个变量。-- 后面的所有内容都会运行该服务。

如果只进行文本搜索，请省略 --env OPENAI_API_KEY=...。

其他 MCP 客户端在其 mcpServers 配置中使用相同的命令：

{
  "mcpServers": {
    "lancelot": {
      "command": "npx",
      "args": ["-y", "@ayerselectronics/lancelot"],
      "env": {
        "LANCEDB_PATH": "/path/to/db",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

安装链接

在浏览器或命令行中打开以下链接之一，将服务添加到编辑器。之后将 LANCEDB_PATH 设置为数据库文件夹。

• VS Code：vscode:mcp/install?%7B%22name%22%3A%22lancelot%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ayerselectronics%2Flancelot%400.3.1%22%5D%2C%22env%22%3A%7B%22LANCEDB_PATH%22%3A%22%2Fpath%2Fto%2Fdb%22%7D%7D
• Cursor：cursor://anysphere.cursor-deeplink/mcp/install?name=lancelot&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBheWVyc2VsZWN0cm9uaWNzL2xhbmNlbG90QDAuMy4xIl0sImVudiI6eyJMQU5DRURCX1BBVEgiOiIvcGF0aC90by9kYiJ9fQ==

链接格式来自 VS Code MCP 指南 和 Cursor 安装链接文档。

注册表

MCP 注册表标识：io.github.ayers-software-repair/lancelot。

设置命令

lancelot-init 会询问数据库文件夹和 OpenAI API 密钥，并将其保存供后续运行使用。密钥通过 keytar 存入操作系统钥匙串；如果 keytar 不可用，则存入加密文件。使用 npx -p @ayerselectronics/lancelot lancelot-init 运行。环境变量会覆盖已保存的值。

HTTP 模式

npx -y @ayerselectronics/lancelot --http                      # http://127.0.0.1:3000/mcp
npx -y @ayerselectronics/lancelot --http 8080
npx -y @ayerselectronics/lancelot --http 8080 --host 0.0.0.0  # all interfaces

不使用 --http 时，服务与之前一样采用 stdio。使用该参数时，服务会使用 MCP 2025-06-18 的 Streamable HTTP 传输，这是 Lancelot 所基于的 SDK 协议版本。--http 可选用一个端口（默认为 3000）。除非通过 --host 指定其他地址，否则服务会绑定到 127.0.0.1，这符合规范对本地服务的建议。端点为 /mcp；其他路径均返回 404。

• Origin。 规范要求服务验证 Origin 标头。若请求携带的 Origin 未列在 LANCELOT_ALLOWED_ORIGINS 中，则返回 403。未设置此变量时，所有携带 Origin 的请求都会返回 403。不带 Origin 标头的请求并非来自浏览器，因此会放行；SDK 自身的来源检查会拒绝此类请求，所以由 Lancelot 自行执行检查。
• Host。 LANCELOT_ALLOWED_HOSTS 用于列出允许调用的 Host 标头值，以防止 DNS 重绑定。绑定到环回地址且未设置此变量时，默认值为 127.0.0.1:<port>、localhost:<port> 和 [::1]:<port>。使用 --host 0.0.0.0 且未设置此变量时，不会检查 Host 标头，并会向 stderr 输出警告。未列出的 Host 请求会返回 403。
• 无状态。 不会签发会话 ID。每个 POST 都会创建独立的 MCP 服务和传输，并在响应结束时关闭，然后返回一个 JSON 对象。GET（可选事件流）和 DELETE（结束会话）会返回 405，并带有 Allow: POST；规范允许这种行为。
• 限制。 超过 64 KB 的请求正文会返回 413。非 JSON 格式的请求正文会返回 400。
• 协议版本。 SDK 会检查 MCP-Protocol-Version 标头：不支持的版本会返回 400；如果缺少该标头，则按规范视为 2025-03-26。

两个变量都接受逗号分隔的列表，例如 LANCELOT_ALLOWED_ORIGINS=https://app.example,https://other.example。HTTP 模式不提供身份验证；这些工具是只读的，向网络开放的服务应放在提供身份验证的组件之后。

AWS Lambda

dist/lambda.js 导出适用于 payload format 2.0 的 API Gateway HTTP API 的 handler(event)。 它会将事件转换为 SDK 传输层所需的请求，并返回 { statusCode, headers, body }。它会读取 LANCEDB_PATH、LANCELOT_BASE_PATH（端点所在的路径，例如 /lancelot；未设置时会响应所有路径）以及两个允许列表变量。数据库连接会在首次调用时打开，并在后续热启动中复用。该函数只能写入 /tmp，Lancelot 会在此处保存自己的设置文件。

Dockerfile 会基于 AWS Node.js 24 arm64 基础镜像构建容器映像，处理程序为 dist/lambda.handler。请先构建 dist：

docker buildx build --platform linux/arm64 --provenance=false -t lancelot-lambda .

为文档编制索引

lancelot-index 会根据一个包含 .md、.txt 和 .html 文件的文件夹，构建服务读取的表：

npx -p @ayerselectronics/lancelot lancelot-index ./docs ./db
npx -p @ayerselectronics/lancelot lancelot-index ./docs ./db --table documents

它会遍历文件夹及其子文件夹（跳过名称以点号开头的目录），将 HTML 转换为文本，并按段落边界将每个文件拆分为约 1,200 个字符的块。超出此长度的段落会在空格处截断。每个块都会成为一行 { id, path, title, text }：id 是相对路径和块编号，path 是相对路径，title 是文件中的第一个 Markdown 标题，若没有则使用文件名。这里没有向量，因此搜索是文本搜索。

--table 用于指定表名（默认为 documents）。如果表已存在，此命令会替换该表，因此再次运行时会根据文件夹重新构建表。这是此软件包中唯一会写入数据库的部分；服务本身不会写入。之后请将 LANCEDB_PATH 指向数据库文件夹。

环境变量

设置值依次取自：环境、lancelot-init 写入的文件、默认值。值为空或仅包含空白字符时，视为未设置。MCP 客户端在替换空白的可选值时会传入空字符串，此时 Lancelot 会将该变量视为未设置：不会创建 OpenAI 客户端，搜索仅使用文本，也不会将任何内容记录为错误。

变量	默认值	含义
LANCEDB_PATH	无	LanceDB 数据库文件夹。工具正常工作所必需。该文件夹必须存在；Lancelot 不会创建它。
LANCEDB_TABLE	documents	调用未指定表名时使用的表。
LANCEDB_TEXT_COLUMN	text	存放文本的列。
LANCEDB_VECTOR_COLUMN	vector	存放向量的列。
LANCEDB_DEFAULT_LIMIT	20	调用未设置 limit 时返回的匹配项数量。
LANCEDB_CONTEXT_BUDGET	8000	调用未设置 contextBudget 时，lancedb_query 返回的上下文字符数。
OPENAI_API_KEY	无	启用向量搜索。未设置时，会接着检查凭据存储。
EMBEDDING_MODEL	text-embedding-ada-002	用于嵌入查询的 OpenAI 模型。
EMBEDDING_DIMENSIONS	1536	由 lancedb_status 报告。不会发送给 OpenAI。
LANCELOT_LOG_LEVEL	info	可选值：error、warn、info、http、verbose、debug、silly。
LANCELOT_ALLOWED_ORIGINS	无	HTTP 模式：允许调用的、以逗号分隔的 Origin 值。请参阅 HTTP 模式。
LANCELOT_ALLOWED_HOSTS	该端口上的环回地址名称	HTTP 模式：允许调用的、以逗号分隔的 Host 标头值。
LANCELOT_BASE_PATH	任意路径	仅限 Lambda：端点所在的路径，例如 /lancelot。

标准输出

MCP stdio 传输 规定，服务只能向 stdout 写入有效的 MCP 消息，也可以向 stderr 写入日志。 Lancelot 遵循这一规定：

• 所有日志级别都写入 stderr。日志记录器只有一个传输，即 winston Console 传输；七个级别都列在 stderrLevels 中。
• 服务入口点将 console.log、console.info 和 console.debug 指向 stderr，因此库输出内容也不会破坏数据流。
• 服务持续读取 stdin，直到客户端关闭输入，然后退出。

HTTP 模式也遵循同样的规则：它同样不会向 stdout 写入任何内容。

lancelot-init 和 lancelot-index 会写入 stdout。它们面向终端上的用户，不会作为服务启动。

只读

这四个工具会打开一个表并查询它。服务运行的代码不会创建表、添加、更新或删除行，也不会构建索引；如果路径有误，服务也不会创建数据库目录。src 中唯一的例外是 src/bin/lancelot-index.ts，这是一个用于构建表的独立命令（参见为文档编制索引）；服务从不导入它。 tests/readonly.test.ts 会扫描其余源码，检查是否存在这些调用。

Lancelot 会将自身的设置和凭据保存在每位用户的配置目录中，绝不会放在数据库目录里。

隐私

设置 OPENAI_API_KEY 后，查询文本会发送到 OpenAI 以计算嵌入。未设置密钥时，不会有任何数据离开本机。

隐私政策和 条款：完整说明，包括托管端点会接收哪些内容。

开发

npm ci
npm run check    # typecheck, lint, test, build

Node 20 或更高版本。请参阅 CONTRIBUTING.md。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。

由 Ayers Electronics 发布。