neo4j-mcp-canary

Neo4j MCP Canary — 金丝雀先行，帮助我们了解接下来会发生什么

Neo4j MCP Canary 是 Neo4j MCP 服务的快速迭代实验版，面向希望在新兴功能被考虑纳入官方服务之前先行探索的客户。

此版本基于 Neo4j 官方 Model Context Protocol (MCP) 服务的源代码，旨在通过实验探索潜在的新功能。

由于这是一个实验项目，请注意：

• 不提供支持
• 自身版本之间以及与官方 Neo4j MCP 服务之间可能存在重大变更
• 使用前应先进行测试

不要假定 Canary 适用于你的场景。请先进行测试。

先决条件

• 一个正在运行的 Neo4j 数据库实例；可选方案包括 Aura、Neo4j Desktop 或自托管。
• Neo4j 实例中已安装 APOC 插件（必需——get-schema 使用 apoc.meta.schema）。
• 任意兼容 MCP 的客户端（例如，VSCode 并启用 MCP 支持）。

⚠️ 已知问题：Neo4j 5.26.18 的 APOC 存在一个错误，会导致 get-schema 工具失败。此问题已在 5.26.19 及更高版本中修复。如果你使用的是 5.26.18，请升级。详情请参阅 #136。

启动检查与自适应运行

服务会执行多项检查，以确保你的环境配置正确。

STDIO 模式——必需条件 在 STDIO 模式下，服务会验证以下各项。如果任何检查失败（例如，配置无效、凭据不正确或缺少 APOC），服务将无法启动：

• 能够连接到 Neo4j 实例。
• 能够执行查询。
• 已安装 APOC 插件。
• 检查使用 Query API 与数据库通信所需的最低版本。

HTTP 模式——跳过验证 在 HTTP 模式下，服务会跳过启动验证检查，因为凭据来自每个请求的身份验证标头。服务会立即启动，不连接 Neo4j。唯一的例外是 Query API 模式：其最低版本检查会在两种传输模式下均于启动时运行，因为该检查只需要一个未经身份验证的 GET 请求，且不依赖每个请求的凭据。

可选条件 如果缺少可选依赖项，服务会以自适应模式启动。例如，如果未检测到 Graph Data Science (GDS) 库，服务仍会启动，但会自动禁用依赖 GDS 的工具，例如 list-gds-procedures。同样，当所连接的服务不支持 Cypher 25 时，graph、traversal 和 patterns 工具也会被禁用。其他所有工具仍可使用。

安装（二进制文件）

发行版：Canary MCP 发行版

1. 下载适用于你的操作系统和架构的压缩包。
2. 解压，并将 neo4j-mcp-canary 放入 PATH。

Mac / Linux：

在 Mac 上，首次尝试运行二进制文件时，系统可能会向你发出警告。如有提示，请通过系统设置 → 隐私与安全性批准运行。

chmod +x neo4j-mcp-canary
sudo mv neo4j-mcp-canary /usr/local/bin/

Windows（PowerShell / cmd）：

move neo4j-mcp-canary.exe C:\Windows\System32

验证安装：

neo4j-mcp-canary -v

应输出已安装的版本。

从源代码构建

需要 Go 1.26+（参见 go.mod）。

使用 Task 为当前平台构建：

task build

这会生成 bin/neo4j-mcp-canary。如果不使用 Task，等效命令为：

go build -C cmd/neo4j-mcp -o ../../bin/

为 macOS / Linux 交叉编译

设置 GOOS / GOARCH 并禁用 cgo 即可进行交叉编译（代码库完全由 Go 编写，因此 CGO_ENABLED=0 会生成完全静态的二进制文件，目标机器上无需运行时依赖）：

CGO_ENABLED=0 GOOS=darwin  GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_amd64
CGO_ENABLED=0 GOOS=darwin  GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_arm64
CGO_ENABLED=0 GOOS=linux   GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_amd64
CGO_ENABLED=0 GOOS=linux   GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_arm64

要将版本写入二进制文件（-v / --version），请传入 ldflags 覆盖值——发布流水线在构建带标签的版本时就是这样做的：

go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary \
  -ldflags "-X 'main.Version=$(git rev-parse --short HEAD)'"

如果不传入该值，Version 默认是 "development"，无论 NEO4J_TELEMETRY 的设置如何，都会禁用遥测（请参阅遥测）。

官方多平台发布归档（包括 Windows）由 GoReleaser 根据 .goreleaser.yaml 构建——如需下载而非本地构建，请参阅安装（二进制文件）。

MCP 传输模式

Neo4j MCP Canary 服务支持两种通信传输模式

• STDIO（默认）：通过 stdin/stdout 进行标准 MCP 通信，适用于桌面客户端（Claude Desktop、VSCode）。
• HTTP：RESTful HTTP 服务，支持每个请求使用 Bearer 令牌或 Basic Authentication，适用于 Web 客户端和多租户场景。如果无法使用标准 Authorization 标头，可配置自定义标头名称。

主要区别

方面	STDIO	HTTP
启动验证	必需——服务会验证 APOC、连接和查询	跳过——服务立即启动
凭据	通过环境变量设置	每个请求通过 Bearer 令牌或 Basic Auth 标头提供
遥测	启动时收集 Neo4j 版本、版本类型和 Cypher 版本	报告 unknown-http-mode——每个请求单独提供凭据，因此无法进行自省

有关两种模式的配置说明，请参阅客户端设置指南。HTTP 模式还支持一种可选的多实例配置，即一个服务同时面向多个 Neo4j 实例——请参阅 docs/MULTI_INSTANCE.md。

未经身份验证的 MCP 客户端请求

默认情况下，使用 HTTP(S) 传输时，MCP 客户端可以发送四种未经身份验证的请求。某些集成（AWS AgentCore、AWS Gateway 等）会依赖这些请求进行初始运行状况检查：

• ping
• initialize
• tools/list
• notifications/initialize

如果不需要这些请求，可通过以下变量分别强制执行身份验证。

环境变量	CLI 标志	默认值	用途
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING	--neo4j-http-allow-unauthenticated-ping	true	允许未经身份验证的 ping 运行状况检查
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST	--neo4j-http-allow-unauthenticated-tools-list	true	允许未经身份验证的工具列表请求
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE	--neo4j-http-allow-unauthenticated-initialize	true	允许未经身份验证的 initialize 请求
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE	--neo4j-http-allow-unauthenticated-notifications-initialize	true	允许未经身份验证的 notifications/initialize 请求

TLS/HTTPS 配置

使用 HTTP 传输时，请通过以下变量启用 TLS，以实现安全通信。

环境变量	CLI 标志	默认值	用途
NEO4J_MCP_HTTP_TLS_ENABLED	--neo4j-http-tls-enabled	false	启用 TLS/HTTPS
NEO4J_MCP_HTTP_TLS_CERT_FILE	--neo4j-http-tls-cert-file	—	TLS 证书路径（启用 TLS 时必需）
NEO4J_MCP_HTTP_TLS_KEY_FILE	--neo4j-http-tls-key-file	—	TLS 私钥路径（启用 TLS 时必需）
NEO4J_MCP_HTTP_PORT	--neo4j-http-port	启用 TLS 时为 443，否则为 80	HTTP 服务端口
NEO4J_HTTP_AUTH_HEADER_NAME	--neo4j-http-auth-header-name	Authorization	用于读取凭据的标头名称
NEO4J_MCP_HTTP_TOOLS_HEADER_NAME	--neo4j-mcp-http-tools-header-name	X-MCP-Tools	客户端用于在单个请求中按名称选择工具的标头
NEO4J_MCP_HTTP_TOOL_CATEGORIES_HEADER_NAME	--neo4j-mcp-http-tool-categories-header-name	X-MCP-Tool-Categories	客户端用于在单个请求中按类别选择工具的标头

安全配置

• 最低 TLS 版本： TLS 1.2（可用时会协商 TLS 1.3）
• 密码套件： Go 的安全默认密码套件
• 默认端口： 启用 TLS 时自动使用 443

示例

export NEO4J_URI="bolt://localhost:7687"
export NEO4J_TRANSPORT_MODE="http"
export NEO4J_MCP_HTTP_TLS_ENABLED="true"
export NEO4J_MCP_HTTP_TLS_CERT_FILE="/path/to/cert.pem"
export NEO4J_MCP_HTTP_TLS_KEY_FILE="/path/to/key.pem"

neo4j-mcp-canary
# Server listens on https://127.0.0.1:443 by default

生产环境用法： 在生产部署中，请使用受信任的 CA（Let's Encrypt、贵组织的 CA 等）颁发的证书。

有关证书生成、TLS 测试和生产部署的详细说明，请参阅 CONTRIBUTING.md。

配置选项

neo4j-mcp-canary 服务通过环境变量、CLI 标志和／或可选配置文件进行配置。CLI 标志的优先级高于环境变量，而环境变量的优先级高于可选配置文件。

环境变量

核心连接与行为：

环境变量	默认值	用途
NEO4J_URI	—	Neo4j 连接 URI（必填）
NEO4J_USERNAME	—	数据库用户名（STDIO 模式下必填；HTTP 模式下必须未设置）
NEO4J_PASSWORD	—	数据库密码（STDIO 模式下必填；HTTP 模式下必须未设置）
NEO4J_DATABASE	neo4j	数据库名称
NEO4J_READ_ONLY	false	为 true 时，不会注册 write-cypher 工具
NEO4J_MCP_ENABLED_TOOLS	(all)	要启用的工具名称，以逗号分隔；为空时启用所有工具
NEO4J_MCP_ENABLED_TOOL_CATEGORIES	(all)	要启用的类别，以逗号分隔（cypher、gds、feedback、search、graph、traversal、patterns）
NEO4J_TELEMETRY	true	启用/禁用匿名遥测
NEO4J_SCHEMA_SAMPLE_SIZE	1000	APOC 推断架构时每个标签检查的节点数
NEO4J_LOG_LEVEL	info	debug、info、notice、warning、error、critical、alert、emergency
NEO4J_LOG_FORMAT	text	text 或 json
NEO4J_OUTPUT_FORMAT	json	发送给大模型客户端的工具响应格式：json、toon 或 markdown
NEO4J_TRANSPORT_MODE	stdio	stdio 或 http（取代已弃用的 NEO4J_MCP_TRANSPORT）
NEO4J_MCP_EMBEDDING_PROVIDER	—	set-vector-property 的 text 字段 / check-embedding-dimensions 使用的 GenAI 嵌入提供商：openai、azure-openai、vertexai 或 bedrock-titan；未设置时会同时禁用这两项
NEO4J_MCP_EMBEDDING_CONFIGURATION	—	以逗号分隔的提供商 key=value 设置（例如 token=sk-xxx,model=text-embedding-3-small）——各提供商所需的键请参阅多实例 HTTP 模式；不可与 neo4j_instances 同时使用（请改为在其中按实例配置嵌入）

通过 Query API 而非 Bolt 连接

NEO4J_URI 的协议方案决定了服务器与 Neo4j 通信时使用的线缆协议，无需单独设置标志：

• bolt://、bolt+s://、neo4j://、neo4j+s:// 等 → Bolt 驱动程序（默认，行为不变）。
• http:// 或 https:// → Neo4j Query API，Neo4j 基于 HTTP 的查询接口。适用于仅开放 HTTP 或出于其他原因不想使用 Bolt 的部署。

Query API 模式要求 Neo4j 2026.07 或更高版本（按日历版本号发布），或者 5.26-aura 或更高版本（仅限经典版本号的 Aura 版本——不支持不带 -aura 后缀的经典版本，因为自托管的经典服务器早于此服务器的 Query API 客户端所依赖的类型化 JSON 媒体类型版本）。此最低版本比 Query API 正式普遍可用版本（2026.06）晚一个发行版：read-cypher 对写入查询的拒绝依赖于查询响应中的 queryType 字段，而 Neo4j 直到 2026.07 才引入该字段——2026.06 服务器在运行查询前无法可靠判断查询是否为只读。服务器会在启动时检查已连接实例报告的版本是否达到此最低要求（通过对基础 URI 发起未经身份验证的 GET 请求）；如果版本过低，则拒绝启动，并在错误中说明检测到的版本和要求的最低版本。

在 Query API 模式下，NEO4J_USERNAME/NEO4J_PASSWORD 和每个请求的 Basic/Bearer 凭据与 Bolt 模式下的用法相同，详见传输模式和身份验证方法（HTTP 模式）。

Cypher 执行防护措施（详见 Cypher 执行防护措施）：

环境变量	默认值	用途
NEO4J_CYPHER_MAX_ROWS	1000	read-cypher / write-cypher 每次调用的行数上限；0 表示禁用
NEO4J_CYPHER_MAX_BYTES	900000	文本和结构化输出每次调用的总字节数限制（约 900 KB）；0 表示禁用
NEO4J_CYPHER_TIMEOUT	30	执行超时时间（秒）；0 表示禁用
NEO4J_CYPHER_MAX_ESTIMATED_ROWS	1000000	EXPLAIN 阶段的规划器估算值超过此上限时，read-cypher 会拒绝查询；0 表示禁用

HTTP 传输、TLS 和身份验证（见上方表格）。

CLI 标志

你可以使用 CLI 标志覆盖任何环境变量：

neo4j-mcp-canary \
  --neo4j-uri "bolt://localhost:7687" \
  --neo4j-username "neo4j" \
  --neo4j-password "password" \
  --neo4j-database "neo4j" \
  --neo4j-read-only false \
  --neo4j-telemetry true

可用标志：

连接与行为

• --neo4j-uri — 覆盖 NEO4J_URI
• --neo4j-username — 覆盖 NEO4J_USERNAME
• --neo4j-password — 覆盖 NEO4J_PASSWORD
• --neo4j-database — 覆盖 NEO4J_DATABASE
• --neo4j-read-only — 覆盖 NEO4J_READ_ONLY（true / false）
• --neo4j-mcp-enabled-tools — 覆盖 NEO4J_MCP_ENABLED_TOOLS（逗号分隔的工具名称）
• --neo4j-mcp-enabled-tool-categories — 覆盖 NEO4J_MCP_ENABLED_TOOL_CATEGORIES（逗号分隔的类别）
• --neo4j-telemetry — 覆盖 NEO4J_TELEMETRY（true / false）
• --neo4j-schema-sample-size — 覆盖 NEO4J_SCHEMA_SAMPLE_SIZE
• --neo4j-output-format — 覆盖 NEO4J_OUTPUT_FORMAT（json / toon / markdown）
• --neo4j-mcp-embedding-provider — 覆盖 NEO4J_MCP_EMBEDDING_PROVIDER
• --neo4j-mcp-embedding-configuration — 覆盖 NEO4J_MCP_EMBEDDING_CONFIGURATION（逗号分隔的 key=value 键值对）

Cypher 执行保护措施

• --neo4j-cypher-max-rows — 覆盖 NEO4J_CYPHER_MAX_ROWS（0 表示禁用）
• --neo4j-cypher-max-bytes — 覆盖 NEO4J_CYPHER_MAX_BYTES（0 表示禁用）
• --neo4j-cypher-timeout — 覆盖 NEO4J_CYPHER_TIMEOUT（秒；0 表示禁用）
• --neo4j-cypher-max-estimated-rows — 覆盖 NEO4J_CYPHER_MAX_ESTIMATED_ROWS（0 表示禁用）

传输 / HTTP

• --neo4j-transport-mode — stdio 或 http
• --neo4j-http-host — 覆盖 NEO4J_MCP_HTTP_HOST
• --neo4j-http-port — 覆盖 NEO4J_MCP_HTTP_PORT
• --neo4j-http-allowed-origins — 覆盖 NEO4J_MCP_HTTP_ALLOWED_ORIGINS（逗号分隔的 CORS 来源）
• --neo4j-http-tls-enabled — 覆盖 NEO4J_MCP_HTTP_TLS_ENABLED
• --neo4j-http-tls-cert-file — 覆盖 NEO4J_MCP_HTTP_TLS_CERT_FILE
• --neo4j-http-tls-key-file — 覆盖 NEO4J_MCP_HTTP_TLS_KEY_FILE
• --neo4j-http-auth-header-name — 覆盖 NEO4J_HTTP_AUTH_HEADER_NAME
• --neo4j-mcp-http-tools-header-name — 覆盖 NEO4J_MCP_HTTP_TOOLS_HEADER_NAME
• --neo4j-mcp-http-tool-categories-header-name — 覆盖 NEO4J_MCP_HTTP_TOOL_CATEGORIES_HEADER_NAME
• --neo4j-http-allow-unauthenticated-ping — 覆盖 NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING
• --neo4j-http-allow-unauthenticated-tools-list — 覆盖 NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST
• --neo4j-http-allow-unauthenticated-initialize — 覆盖 NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE
• --neo4j-http-allow-unauthenticated-notifications-initialize — 覆盖 NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE

运行 neo4j-mcp-canary --help，查看包含说明的完整列表。

配置文件

作为优先级最低的替代方式，neo4j-mcp-canary 可以从可选的 JSON 或 YAML 文件读取配置：

neo4j-mcp-canary --config-file /etc/neo4j-mcp/config.yaml
# or
NEO4J_CONFIG_FILE=/etc/neo4j-mcp/config.yaml neo4j-mcp-canary

键名是对应环境变量名称的小写形式：

neo4j_uri: bolt://localhost:7687
neo4j_username: neo4j
neo4j_password: password
neo4j_read_only: false
neo4j_transport_mode: http
neo4j_http_tls_enabled: true
neo4j_cypher_max_rows: 500

也接受等效的 JSON（.json 扩展名）。除两个键外，每个键都只支持标量值（字符串、数字、布尔值）；在其他任何键下使用嵌套对象或列表都会导致启动错误。CLI 标志或环境变量中的值始终优先于配置文件；无法读取或解析 --config-file 指定的文件会导致启动错误。

唯一的例外是 neo4j_instances：这是 Neo4j 实例定义列表，启用多实例 HTTP 模式，让一个服务可以同时连接多个 Neo4j 实例，每个实例都可通过自己的 URL 路径访问。它只能通过配置文件设置——完整的配置结构、各实例的身份验证类型，以及客户端如何选择实例，请参阅 docs/MULTI_INSTANCE.md。

另一个只能在文件中设置的键是 custom_tools，可用于定义自己的 Cypher 工具——请参阅 docs/CUSTOM_TOOLS.md。

运行 neo4j-mcp-canary --validate-config（并附上常用标志、环境变量和 --config-file），即可检查完整配置——它会报告所有问题，而不只是第一个问题——且不会启动服务。如果存在错误，程序会以状态码 1 退出。检查内容请参阅 docs/CUSTOM_TOOLS.md。

要为服务添加新的配置参数（同时添加环境变量、CLI 标志和配置文件键），只需在 internal/config/schema.go 中的 fields 切片添加一项——具体结构请参阅该文件中的文档注释。

响应格式（JSON、TOON 或 Markdown）

默认情况下，工具响应（上表中的每个工具）都以 JSON 格式呈现。将 NEO4J_OUTPUT_FORMAT（或 --neo4j-output-format）设为 toon 或 markdown，即可使用其他格式呈现：

neo4j-mcp-canary --neo4j-output-format toon
# or
NEO4J_OUTPUT_FORMAT=toon neo4j-mcp-canary

read-cypher 的 JSON 格式结果：

{
  "rows": [
    { "name": "Alice", "age": 30 },
    { "name": "Bob", "age": 25 }
  ],
  "rowCount": 2,
  "truncated": false
}

相同结果的 TOON（面向 Token 的对象表示法）格式——这是一种精简且仍便于阅读的格式，与 JSON 相比可减少 LLM 的 Token 用量，尤其适合这些工具返回的表格行结构：

rowCount: 2
rows[2]{age,name}:
  30,Alice
  25,Bob
truncated: false

相同结果的 markdown 格式——统一的扁平行数组会呈现为表格；嵌套或不统一的数据（例如 get-schema 的输出）则会呈现为嵌套列表：

- **rowCount**: 2
- **rows**:
| age | name |
| --- | --- |
| 30 | Alice |
| 25 | Bob |
- **truncated**: false

markdown 是对 toon 的补充，而非严格意义上的升级：针对表格数据的独立基准测试发现，Markdown 表格的 accuracy 高于 TOON，尽管它使用了更多 Token；而 TOON 的原始 Token 数量仍然更少。最关注 Token 预算时，优先使用 toon；最关注结果准确性时，优先使用 markdown。

无效值会回退到 json，并在 stderr 上输出警告，处理方式与 NEO4J_LOG_FORMAT 相同。

结构化输出（structuredContent / outputSchema）

每次工具调用的结果还包含 MCP 的结构化输出扩展：除了上述文本块（格式由 NEO4J_OUTPUT_FORMAT 选择）之外，结果的 structuredContent 字段始终以规范 JSON 格式携带相同数据，并与工具定义中声明的 outputSchema 相匹配。想以编程方式使用结果的客户端可以直接读取 structuredContent，而不必重新解析文本块，无论配置了哪种文本格式。

由于 structuredContent 会重复文本块中已有的负载，read-cypher/write-cypher 会将 NEO4J_CYPHER_MAX_BYTES 作为总预算执行：流式处理时实际应用的字节上限是配置值的一半，因此文本和结构化内容合计仍低于下文所述约 900 KB/1 MB 的目标，而不会翻倍。

Cypher 执行保护措施

read-cypher 和 write-cypher 受到四层保护措施的保护，它们共同防止过于积极的 LLM 卡住 MCP 传输或耗尽数据库。每一层针对不同的故障模式；它们共同构成纵深防御。

层	设置	默认值	触发时机
规划器估算	NEO4J_CYPHER_MAX_ESTIMATED_ROWS	1000000	执行前——如果规划器的根节点 EstimatedRows 超过阈值，则拒绝查询
执行超时	NEO4J_CYPHER_TIMEOUT	30s	执行期间——超过截止时间后取消查询
行数上限	NEO4J_CYPHER_MAX_ROWS	1000	流式传输期间——达到行数上限时截断响应
字节数上限	NEO4J_CYPHER_MAX_BYTES	900000	流式传输期间——信封大小超过配置值的一半时截断响应（参见 结构化输出）

将任意值设为 0 可禁用对应的保护层。

截断信封

触发行数上限或字节数上限时，工具会返回已收集的行以及一个截断信封：

{
  "rows": [ /* ... */ ],
  "rowCount": 1000,
  "truncated": true,
  "truncationReason": "rows",
  "maxRows": 1000,
  "hint": "Results were truncated at 1000 rows. Add a LIMIT clause or a more selective filter and retry for a complete result."
}

调用方（包括 LLM Agent）可以通过程序读取 truncated / truncationReason / hint，并使用更严格的查询重试，而不是遇到不透明的传输层故障。

超时与取消错误

触发 NEO4J_CYPHER_TIMEOUT 时，工具会返回一个分类错误，其中会指出配置的限制，并提供针对工具的修正建议（对于 read-cypher，可限制可变长度模式、添加 WHERE 筛选条件或使用 LIMIT；对于 write-cypher，可减小批次大小、缩小 MATCH 范围或使用 apoc.periodic.iterate）。调用方取消（与超时不同）会显示为简洁的 cancelled 消息，不提供修正建议。

拒绝规划器估算

规划器估算保护会在查询运行前读取 EXPLAIN 计划根节点的 EstimatedRows。由于 Neo4j 会将 LIMIT 纳入根节点估算，合法的 MATCH ... LIMIT 100 查询会以约 100 的估算值顺利通过；而对包含数百万行的标签执行不带限制的 MATCH，则会在开始前被拒绝。

身份验证方式（HTTP 模式）

使用 HTTP 传输模式时，Neo4j MCP Canary 服务支持两种身份验证方式，以适应不同的部署场景。（本节介绍单实例 HTTP 模式；多实例模式有自己的逐实例身份验证类型，包括由服务端验证的 Bearer 令牌——参见 docs/MULTI_INSTANCE.md。）

Bearer 令牌身份验证

Bearer 令牌身份验证可与使用 SSO/OAuth/OIDC 进行身份管理的 Neo4j Enterprise Edition 和 Neo4j Aura 环境无缝集成。此方式适用于：

• 使用集中式身份提供商（Okta、Azure AD 等）的企业部署
• 配置了 SSO 的 Neo4j Aura 数据库
• 要求符合 OAuth 2.0 标准的组织
• 多因素身份验证场景

示例：

curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Bearer 令牌从身份提供商处获取，并传递给 Neo4j 进行身份验证。MCP 服务充当透传通道，将令牌转发到 Neo4j 的身份验证系统。

基本身份验证

传统的用户名/密码身份验证，适用于：

• Neo4j Community Edition
• 开发和测试环境
• 无需 SSO 的直接数据库凭据

示例：

curl -X POST http://localhost:8080/mcp \
  -u neo4j:password \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

客户端配置

有关如何配置 MCP 客户端（VSCode、Claude Desktop 等）以使用 Neo4j MCP Canary 服务，请参阅：

📘 客户端设置指南 – STDIO 和 HTTP 模式的完整配置说明。

工具与用法

提供的工具：

工具	类别	只读	用途	备注
get-schema	cypher	true	探查标签、关系类型和属性键	使用 apoc.meta.schema。采样由 NEO4J_SCHEMA_SAMPLE_SIZE 控制。
read-cypher	cypher	true	执行任意只读 Cypher	拒绝写入、模式/管理 DDL、EXPLAIN 和 PROFILE。参见Cypher 执行保护措施。
write-cypher	cypher	false	执行任意 Cypher（写入模式）	**注意：**LLM 生成的查询可能造成损害。仅在开发环境中使用。拒绝 EXPLAIN/PROFILE 前缀（见下文）。设置 NEO4J_READ_ONLY=true 时不会注册。
explain-cypher	cypher	true	返回查询计划，但不执行查询	读写语句均适用，因为 EXPLAIN 从不执行查询。参见查询规划与性能分析。
profile-cypher	cypher	false	执行查询并返回结果，以及包含运行时统计信息的性能分析计划	每个运算符的 dbHits/rows/time/页面缓存统计信息。设置 NEO4J_READ_ONLY=true 时不会注册。
list-constraints-and-indexes	cypher	true	列出数据库的约束和索引	结构化发现——包含 VECTOR/FULLTEXT 条目（如有）。参见模式管理工具。
create-constraint	cypher	false	创建 UNIQUENESS、KEY 或 PROPERTY_EXISTENCE 约束	KEY/PROPERTY_EXISTENCE 需要 Enterprise Edition。仅需结构化字段——无需 Cypher。
drop-constraint	cypher	false	按名称删除约束	幂等（DROP CONSTRAINT ... IF EXISTS）。
create-index	cypher	false	创建 RANGE、TEXT、POINT 或 LOOKUP 索引	VECTOR/FULLTEXT 索引改用 search 类别中的 create-vector-index/create-fulltext-index 创建。
drop-index	cypher	false	按名称删除索引	适用于任何索引类型，包括 vector/fulltext。
vector-search	search	true	针对向量索引执行近似最近邻相似度搜索	自动检测索引的目标标签/关系类型。参见向量和全文搜索工具。
fulltext-search	search	true	针对全文索引执行基于 Lucene 的全文搜索	与 vector-search 一样会自动检测。
create-vector-index	search	false	创建用于相似度搜索的向量索引	filterableProperties 会注册可在之后 vector-search 的 filters 中使用的属性。
create-fulltext-index	search	false	创建用于文本搜索的全文索引	支持多个标签/关系类型。
set-vector-property	search	false	设置节点或关系的嵌入向量属性	使用 db.create.setNodeVectorProperty/setRelationshipVectorProperty。至少需要一个筛选条件。可接受预先计算的 vector，也可接受 text，由服务器端生成嵌入（前提是实例已配置嵌入提供程序）——参见多实例 HTTP 模式。
check-embedding-dimensions	search	true	验证已配置的嵌入提供程序/模型是否与向量索引的维度匹配	会生成一个临时嵌入，不写入任何内容。需要在实例上配置嵌入提供程序。
create-node	graph	false	创建带有标签和属性的节点	mergeOn 可将其设为幂等的插入或更新操作。返回节点的 id。参见图操作工具。
find-nodes	graph	true	按标签、属性值和/或筛选条件查找节点	支持分页（limit/skip）；returnProperties 可精简输出。
get-node	graph	true	获取一个节点及其按类型和方向统计的关系数量	按 id 或唯一键选择。
update-node	graph	false	设置/删除属性，并为现有节点添加/移除标签	受 maxAffected（默认为 1）和 dryRun 保护；需要 id、match 或 filters。
delete-node	graph	false	删除节点	**具有破坏性。**删除相关节点需设置 detach；受 maxAffected 和 dryRun 保护。
count-nodes	graph	true	统计符合标签/属性/筛选条件的节点数量	只需要数量时，比 find-nodes 更省资源。
create-relationship	graph	false	在两个现有节点之间创建有向关系	两端都必须精确选中一个节点。除非设置 allowDuplicate，否则会复用相同的关系。
find-relationships	graph	true	按类型、端节点和/或属性查找关系	返回端节点摘要，无需后续再查找。
update-relationship	graph	false	设置/删除现有关系的属性	受 maxAffected 和 dryRun 保护。
delete-relationship	graph	false	删除关系（保留端节点）	**具有破坏性。**受 maxAffected 和 dryRun 保护。
traverse	traversal	true	从一个节点向外遍历：返回可达节点及深度，或返回路径	受 maxDepth 限制（最大为 10）。适用于依赖项、层级结构和影响分析。
expand-neighbors	traversal	true	获取距一个节点恰好一跳的所有内容	按相对于起始节点的方向报告。
find-shortest-path	traversal	true	两个节点之间的最短路径（或所有并列最短路径）	使用 Cypher 25 ANY/ALL SHORTEST。
find-all-paths	traversal	true	枚举两个节点之间的路径，按从短到长排序	受 maxDepth（最大为 8）和 limit 限制。
match-pattern	patterns	true	查找符合所描述模式的实例；返回行、计数或是否存在	模式以节点和关系描述，不使用 Cypher。必须连通。
find-common-connections	patterns	true	查找 2–5 个给定节点共享的节点（共同邻居）	适用于协作、共享依赖项和共同连接。
find-motif	patterns	true	检测 star、fan-in、fan-out、triangle 或 cycle 结构	指定 relationshipTypes/nodeLabels 以提高速度；start 用作锚点。
find-relationship-chain	patterns	true	从一个节点沿精确、按序排列的关系序列遍历	每一步都要指定类型、方向和可选的目标节点条件。
find-subgraph	patterns	true	将一个节点周围的邻域提取为节点和关系	受 maxDepth（最大为 4）和 maxNodes（最大为 200）限制。
list-gds-procedures	gds	true	列出 Neo4j 实例中可用的 GDS 过程	如果未安装 GDS，则自动禁用。
give-feedback	feedback	true	提交关于 MCP 服务本身的自由文本反馈	用于反馈服务（工具、行为、文档）问题，而非 Cypher/数据库问题。最多 300 个字符。参见反馈。

选择要公开的工具

每个工具都恰好属于一个类别（cypher、gds、feedback、search、graph、traversal 或 patterns，见上表），并带有一个标签——即其 MCP 标题注释（例如“读取 Cypher”），会显示给使用友好工具名称的客户端。

可以通过两种方式缩小工具选择范围；它们会与现有的 NEO4J_READ_ONLY/GDS 可用性/搜索版本/Cypher-25 过滤条件组合使用（选择只能进一步缩小范围，不能重新启用已被这些过滤条件排除的工具）：

在启动时静态设置，通过 NEO4J_MCP_ENABLED_TOOLS 和/或 NEO4J_MCP_ENABLED_TOOL_CATEGORIES（以逗号分隔；工具匹配任一列表即可保留——参见配置选项）：

# Only expose the two Cypher read tools:
export NEO4J_MCP_ENABLED_TOOLS="read-cypher,get-schema"

# Only expose the cypher category (equivalent to the above plus write-cypher):
export NEO4J_MCP_ENABLED_TOOL_CATEGORIES="cypher"

在 HTTP 模式下按请求设置，通过 X-MCP-Tools 和 X-MCP-Tool-Categories 标头（名称可通过 NEO4J_MCP_HTTP_TOOLS_HEADER_NAME / NEO4J_MCP_HTTP_TOOL_CATEGORIES_HEADER_NAME 配置）。未设置这两个标头的请求会像往常一样看到静态启用的完整工具集；设置任一标头的请求只会看到该请求匹配的工具，调用被排除的工具时会失败，方式与调用不存在的工具相同：

curl -X POST https://your-server/mcp \
  -H "Authorization: Basic <credentials>" \
  -H "X-MCP-Tool-Categories: gds" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

只读模式标志

将 NEO4J_READ_ONLY=true 设为启用只读模式（可接受的值：true / false；默认值：false）。

也可以使用 CLI 标志：

neo4j-mcp-canary \
  --neo4j-uri "bolt://localhost:7687" \
  --neo4j-username "neo4j" \
  --neo4j-password "password" \
  --neo4j-read-only true

启用后，写入工具（例如 write-cypher）不会向客户端公开。

查询分类

read-cypher 会在调用方的查询前添加 EXPLAIN，以便在执行前将其分类为读取或写入操作。具体影响如下：

• 写入操作（CREATE、MERGE、DELETE、SET、REMOVE 等）——拒绝执行，并提示调用方使用 write-cypher。
• 架构/DDL 操作（CREATE INDEX、DROP CONSTRAINT 等）——拒绝执行，并显示相同提示。
• 管理命令（SHOW USERS、SHOW DATABASES 等）——拒绝执行，并显示相同提示。
• EXPLAIN 前缀——拒绝执行，并提示使用 explain-cypher 获取查询计划，或使用 profile-cypher 获取包含运行时统计信息的分析计划。
• PROFILE 前缀——拒绝执行，并提示使用 profile-cypher；该工具会执行查询并返回结果和分析计划。write-cypher 也会因相同原因拒绝带有 EXPLAIN/PROFILE 前缀的查询——参见查询计划和性能分析。
• 只读 SHOW 命令（SHOW INDEXES、SHOW CONSTRAINTS、SHOW PROCEDURES、SHOW FUNCTIONS）——允许执行。

如果包装后的查询产生语法错误，服务会在返回错误前，从错误文本、列偏移量和插入符对齐位置中移除内部的 EXPLAIN 前缀，因此错误信息会像调用方直接提交原始查询时一样显示。

查询计划和性能分析

explain-cypher 和 profile-cypher 涵盖了 read-cypher/write-cypher 特意不处理的查询调优工作流：explain-cypher 会返回规划器为任意语句生成的计划树，无论该语句是读取还是写入；由于 EXPLAIN 不会运行查询，因此不会执行该语句。profile-cypher 会执行语句，并返回结果以及包含各运算符运行时统计信息的分析计划（dbHits、rows、time、页缓存命中率）。这两个工具都不接受已带有 EXPLAIN/PROFILE 前缀的查询——每个工具都会在内部添加自己的前缀；如果调用方自行提供前缀，工具会拒绝执行，并在调用方实际想要使用另一个工具时提示相应工具。

架构管理工具

list-constraints-and-indexes、create-constraint、drop-constraint、create-index 和 drop-index 只能通过结构化字段管理约束和索引——它们都不接受或返回原始 Cypher。create-constraint 支持 UNIQUENESS、KEY 和 PROPERTY_EXISTENCE 约束（KEY/PROPERTY_EXISTENCE 需要 Enterprise Edition；Community Edition 会在创建时拒绝它们——重试也无济于事）。create-index 支持 RANGE、TEXT、POINT 和 LOOKUP 索引；向量索引和全文索引则通过 search 类别中的 create-vector-index/create-fulltext-index 创建。drop-index 适用于任何索引类型，包括向量索引和全文索引。每个 create-* 工具在生成的语句中始终包含 IF NOT EXISTS/IF EXISTS，因此使用相同参数重试是安全的；如果省略 name，响应中会返回自动生成的名称，供之后与对应的 drop-* 工具搭配使用。

向量和全文搜索工具

search 类别——vector-search、fulltext-search、create-vector-index、create-fulltext-index、set-vector-property、check-embedding-dimensions——只能通过结构化字段使用 Cypher 25 的 SEARCH 子句；该类别中的工具都不接受或返回原始 Cypher。vector-search/fulltext-search 会根据索引自动检测目标节点标签或关系类型，因此调用方只需提供索引名称。vector-search 的 filters 仅对通过 create-vector-index 的 filterableProperties 在创建索引时注册为可过滤的属性有效——对任何其他属性进行过滤，是 Neo4j 的硬性限制，而非工具限制。set-vector-property 接受调用方提供的嵌入向量（vector），或用于生成嵌入的原始 text——后者仅在所连接的 Neo4j 实例配置了嵌入提供方时有效：单实例模式（STDIO 或单实例 HTTP）通过 NEO4J_MCP_EMBEDDING_PROVIDER/NEO4J_MCP_EMBEDDING_CONFIGURATION 配置，多实例 HTTP 模式则通过每个条目自己的 embedding 块配置（完整的提供方/必需键表见 多实例 HTTP 模式，该表适用于这两种模式）。实际生成嵌入的一方取决于提供方：openai 由此 MCP 服务通过直接 HTTP 调用自行生成（其 baseUrl 配置键可将请求重定向到 LM Studio 或 Ollama 等本地兼容 OpenAI 的服务，完全不涉及 Neo4j 端），而 azure-openai/vertexai/bedrock-titan 则由 Neo4j 自己的 GenAI 插件（ai.text.embed）生成，并复用其已实现的身份验证方案。无论哪种方式，如果已存在匹配的向量索引，写入前都会检查生成向量的维度是否与之匹配；check-embedding-dimensions 则允许调用方提前验证提供方/模型与索引是否兼容，而不写入任何内容。

此类别要求服务的日历版本 >= 2026.09.0 或经典 Aura >= 5.27-aura（原生全文 SEARCH 子句支持随 Neo4j 的 2026.09 版本发布；仅向量搜索从 2026.01 起即可使用，但为保持一致，整个类别都设置了更高的版本门槛）。低于此门槛时，这六个工具会自动从 tools/list 中排除，而不会在调用时失败——这与未安装 GDS 时排除 list-gds-procedures 的方式相同。

图操作工具

graph、traversal 和 patterns 类别让 Agent 无需编写任何 Cypher，即可创建、读取、更新、删除和探索图数据。每个输入都是结构化字段；这些类别中的工具都不接受或返回原始 Cypher。值始终作为查询参数绑定；标签、类型和属性键会使用反引号转义；过滤运算符和枚举会在传入数据库前根据固定列表进行校验。

• graph — 节点和关系的 CRUD：create-node、find-nodes、get-node、update-node、delete-node、count-nodes、create-relationship、find-relationships、update-relationship、delete-relationship。
• traversal — 导航连接：traverse（可达性、依赖关系、层级结构）、expand-neighbors（一跳）、find-shortest-path、find-all-paths。
• patterns — 结构性问题：match-pattern、find-common-connections、find-motif、find-relationship-chain、find-subgraph。

这些工具的协作方式：

• 每个节点和关系都会返回一个 id（即其 elementId），其他工具都接受该值，因此无需编写查询即可串联处理结果。所有工具选择节点的方式都相同：使用 id、labels、精确相等的 match 映射和／或 filters（{property, operator, value}，其中运算符为 =、<>、<、>、<=、>=、IN、CONTAINS、STARTS WITH、ENDS WITH、IS NULL、IS NOT NULL）。
• 返回结果精简：如果节点或关系没有你请求的属性，该属性会被省略，而不是以 null 返回。
• 所有操作都有边界：结果有默认 limit 和硬上限；可变长度工具的 maxDepth 有上限；常规行数上限、字节数上限和 NEO4J_CYPHER_TIMEOUT 同样适用。超时错误会告知调用方如何缩小请求范围。
• 写入工具在设计上就具备安全性。update-* 和 delete-* 不允许仅凭标签或类型运行；它们最多更改 maxAffected 个实体（默认值为 1，最大值为 1000），当选中实体数量超过上限时，会返回匹配数量并报告 performed: false，而不会执行操作；同时支持使用 dryRun 预览效果。如果节点仍有关系，delete-node 不会删除该节点，除非设置了 detach。所有写入工具都带有相应注解，因此在 NEO4J_READ_ONLY=true 时不会注册。
• 工具描述会说明何时应使用该工具而非其同类工具；错误消息会指出问题所在、有效选项以及后续操作。

这些工具会生成 Cypher 25。当所连接的服务不支持该版本时（日历版本早于 2025.06 的发行版、自托管的经典 5.x 服务，或早于 5.26-aura 的经典 Aura），这三个类别会从 tools/list 中排除，而不会在调用时失败——与未安装 GDS 时排除 list-gds-procedures 的方式相同。

工具设计原则

新工具遵循以下原则。这些原则也列在 AGENTS.md 中，供在此仓库中工作的 AI 编码 Agent 参考。

1. 意图 — 一个工具解决用户会明确提出的一项具体任务。使用动词-名词的 kebab-case 格式命名，并在描述中说明何时应使用它，而不是同类工具。
2. 上下文 — 工具不得让模型困惑或增加其负担。参数列表应简短，优先使用枚举而非自由文本，并说明工具返回什么以及不会做什么。每个工具都会占用所有客户端的上下文，因此应合并功能重叠的工具，而不是添加近似重复的工具；还应将工具归入不同类别，以便部署时可以关闭不需要的类别。
3. 粒度 — 将总是需要一起执行的 3–4 个原子操作合并为一个高层工具（解析目标、检查防护条件、写入、返回结果）。按任务合并，而不是通过标志在一个工具中堆叠多种模式。
4. 效率 — 仅返回 LLM 需要的字段：用于串联调用的 ID、默认返回摘要，其余内容通过投影选项获取，并为 limit / maxDepth 设置默认值和硬性上限。
5. 安全性 — 危险工具（删除、覆盖及任何不可逆操作）必须明确声明：设置 readOnly: false，添加破坏性提示注解，并在 NEO4J_READ_ONLY 下移除该工具。读写操作应使用不同的工具。必须指定精确目标（绝不能使用“所有标签为 X 的对象”），限制影响范围（maxAffected），并提供 dryRun。
6. 错误处理 — 错误信息必须告诉 LLM 如何修正：哪里出错、有效值有哪些、接下来可以尝试什么，以及重试是否有帮助。
7. 仅使用参数 — 工具接收结构化字段，绝不接收 Cypher。值应绑定为参数，标识符应转义，运算符和枚举值应使用白名单。
8. 有界 — 每个工具都必须对行数、深度和执行时间设定硬性上限，确保任何单次调用都不会失控。
9. 幂等 — 优先采用可安全重试的操作（MERGE、IF NOT EXISTS、设置为指定值），并在描述中说明何时可以安全重试。
10. 可组合 — 输出具有稳定的结构，并包含其他工具可接受为输入的 ID。
11. 经过验证 — 工具生成的 Cypher 应由纯函数构建，并配有单元测试；每个会访问数据库的工具都应有集成测试。

read-cypher / write-cypher 的响应格式

驱动程序类型会封装为符合 Cypher 约定的 camelCase JSON 结构：

• 节点： { "elementId": "...", "labels": [...], "properties": {...} }
• 关系： { "elementId": "...", "startElementId": "...", "endElementId": "...", "type": "...", "properties": {...} }
• 路径： { "nodes": [...], "relationships": [...] }
• 点： { "x": ..., "y": ..., "srid": ... }（3D 点还包含 z）
• 日期 / 时间 / 日期时间 / 本地时间 / 本地日期时间 / 时长： ISO 8601 字符串

已弃用的数字型 id / startId / endId 标识符不会返回——返回的标识符仅有 elementId / startElementId / endElementId。

反馈

give-feedback 允许 Agent 通过单个 feedback 字符串参数，提交关于 MCP 服务本身的自由文本反馈，可以是正面或负面的，最多 300 个字符（工具公开的 schema 和处理程序都会强制执行此限制，以防客户端发送前未验证 schema）。此工具用于反馈服务的工具、行为或文档，而不是报告 Cypher/数据库错误。

反馈会作为 Mixpanel 事件与服务的其他遥测数据一同发送，因此只有启用遥测时才会被记录（参见 遥测）——无论是否启用遥测，工具调用本身都会成功。

使用指南

Canary 测试的经验教训，可帮助大模型（或人类）更好地使用 read-cypher：

1. 在数据库中执行聚合。 count、sum、avg、collect、reduce、percentileCont、stDev 等归约操作会将结果合并为一行，不受行数上限影响。像 UNWIND range(1, 50000) AS i RETURN sum(i) 这样的查询可以顺利运行；而逐行流式返回相同范围的数据则会被行数上限截断。
2. 探索性查询始终使用 LIMIT。 不带限制的 MATCH 返回结果会被行数上限截断；截断信息中的 hint 字段会提示调用方添加 LIMIT。最好使用你自行指定的 LIMIT，而不是由服务强加的限制。
3. 缩小宽节点的 RETURN 投影范围。 如果记录包含许多属性（例如有 19 个字段的完整 Company 节点），字节数上限会先于行数上限触发。只返回所需字段（例如 RETURN c.name, c.companyNumber），而不是整个节点。
4. 使用参数，包括嵌套映射。 参数占位符（$name）会从 params 对象中绑定；支持嵌套访问（$config.thresholds.pr）。缺少必需参数时会产生清晰的 ParameterMissing 错误；多余参数则会被静默忽略。
5. 比较时明确类型。 跨类型比较（如 t.amount > "foo"）的结果为 null，并会静默过滤掉所有内容——不会报错，只会返回空结果集。如果结果形态出乎意料，请在调用方验证传入的参数类型。
6. 允许使用 SHOW INDEXES / SHOW CONSTRAINTS。 在编写依赖索引的查询前，或排查匹配速度为何缓慢时，这些命令很有用。
7. read-cypher / write-cypher 不提供 EXPLAIN 和 PROFILE。 查询失控保护已由规划器估算保护机制和执行超时处理。使用 explain-cypher 查看查询计划，或使用 profile-cypher 查看包含运行时统计信息的分析计划。
8. 返回路径时留意重复载荷。 RETURN p, nodes(p), relationships(p) 会使序列化载荷增至三倍。返回路径或其组成部分即可，不要同时返回两者。
9. 长时间运行的查询会返回分类错误。 触发 NEO4J_CYPHER_TIMEOUT 时，错误会指出超时值并建议补救措施（限制可变长度模式、添加 WHERE 过滤条件、使用 LIMIT），而不是返回驱动程序的原始 context deadline exceeded 错误。
10. 缺失数据时使用 OPTIONAL MATCH。 按 ID 查找时，如果某些 ID 可能不存在，OPTIONAL MATCH 会对未命中的结果返回 null，而不是丢弃对应行——更适用于批量查找。
11. 默认值经过校准，并非随意设定。 1000 行 / ~900 KB / 30s / 1M 规划器估算值涵盖了绝大多数探索性和生产查询。批量导出工作负载可提高这些值；服务高流量 Agent 部署时则可降低这些值。

自然语言提示词示例

可在 Copilot 或任何其他 MCP 客户端中尝试以下提示词：

• “我的 Neo4j 实例中有什么内容？列出所有节点标签、关系类型和属性键。”
• “查找所有 Person 节点，并显示它们最重要的关系，结果最多 50 条。”
• “我的数据库中有哪些索引和约束？”
• “总结事务图：总数、平均金额，以及 PageRank 最高的 5 位客户。”

安全提示

• 使用权限受限的 Neo4j 用户进行探索。
• 在生产数据库中执行 LLM 生成的 Cypher 前，请先审核。
• 对任何不应修改图数据的部署，保持 NEO4J_READ_ONLY=true。
• 除非有具体理由需要更改，否则将 Cypher 安全防护设置保持为默认值。

日志记录

该服务使用结构化日志，支持多种日志级别和输出格式。

配置

日志级别（NEO4J_LOG_LEVEL，默认值：info）

控制日志详细程度。支持所有 MCP 日志级别：debug、info、notice、warning、error、critical、alert、emergency。

日志格式（NEO4J_LOG_FORMAT，默认值：text）

• text — 易于阅读（默认值）
• json — 结构化 JSON（适用于日志聚合）

遥测

默认情况下，neo4j-mcp-canary 会收集匿名使用数据，以帮助改进产品。这些数据包括所使用的工具、操作系统和 CPU 架构等信息。不会收集任何个人或敏感信息。

如需停用遥测，请设置 NEO4J_TELEMETRY=false（可接受的值：true / false；默认值：true）。也可以使用 --neo4j-telemetry CLI 标志。

文档

📘 客户端设置指南 – 配置 VSCode、Claude Desktop 和其他 MCP 客户端（STDIO 和 HTTP 模式） 📚 贡献指南 – 贡献工作流、开发环境、模拟对象与测试

问题 / 反馈：请提交 GitHub issue，并附上复现详情（请勿包含敏感数据）。