LightNow MCP Proxy

LightNow MCP 代理

将 AI 客户端连接到 MCP 服务，并在一个地方安全管理。

LightNow MCP 代理是 LightNow 配置文件背后的本地运行时。 只需连接一次 Codex、Claude Desktop、Cursor、VS Code 或 Antigravity，然后在 LightNow 中管理该客户端可用的 MCP 服务，无需将服务配置和密钥复制到每个工具中。

• 在个人和组织配置文件中整理 MCP 访问权限。
• 通过单一入口连接本地 stdio 和远程 Streamable HTTP 服务。
• 在用户的设备上解析凭据，而不是将其嵌入 MCP 客户端配置。
• 应用配置文件和策略变更，无需重建每个客户端设置。
• 观察客户端、配置文件、服务健康状况和工具使用情况。默认会捕获工具参数， 并对类似凭据的字段进行脱敏；此功能可以禁用。绝不会收集工具结果和已解析的密钥。

安装后的命令仍为 lightnow-proxy。它在本地运行，使用与身份绑定的 LightNow CLI 会话，解析所选配置文件，并将工具和资源请求路由到该配置文件的 MCP 服务。

能力取决于你的 LightNow 配置文件

代理不会附带演示工具。它的 MCP 能力来自当前 LightNow 配置文件中所选服务实际公开的工具和资源，因此会因团队和客户端而异。诸如 github__create_issue 的名称会同时标识上游服务及其工具，避免多个服务使用同一工具名称时发生冲突。

代理支持官方 MCP 2026-07-28 修订版，采用无状态、逐请求的协议元数据和 server/discover。它还会自动兼容截至 2025-11-25 采用握手机制的服务和客户端。

工具发现会从实际配置的上游服务读取完整分页结果。遇到重复游标、完全相同的名称重复，或达到 30 秒、100 页、2,000 个工具及 4 MiB 定义的限制时，会明确报错。完整的空清单会与不完整的发现结果区分开来。现代 HTTP 调用会基于同一完全发现的客户端准备其参数标头架构。 托管分发原语会先验证该清单的授权，再发送一次请求；架构不匹配后的恢复和交互式重试必须重新经过策略门控。

当 Registry API 请求可选的脱敏设置预览时，代理只会从原生托管上下文中提取公开输入 ID、绑定布尔值、类型化占位符，以及明确获准的公开选项索引。它不会解析启动命令，也不会将配置值、文件、端点或工具元数据复制到预览中。不受支持或不匹配的描述符会导致预览不可用，但不会使成功的私有发现失败。分享仍是单独的显式 API/UI 操作；此代理不会创建或发布贡献。完整工作流详见 Registry API #1340。 对于托管连接，现有设备心跳会声明 managed-connections.v1，并获取由执行主体拥有的运行时客户端 ID，即使 已禁用可选活动捕获也是如此。 兼容的同步代理每 15 秒轮询一次，并发执行的排队私有发现任务最多为两个。 它们会解析当前的准确分配，在打开上游连接前比较排队的配置文件、策略和凭据修订版本， 并使用 If-Match 向原始请求报告。关闭时会取消尚未完成的 发现任务；失败时会报告范围受限的代码，不包含私有定义或原始上游错误。仅支持旧版在线状态的客户端仍采用 120 秒间隔。 Registry 提供规范连接、分配和范围受限的引导上下文。完整的私有清单报告 会返回准确的允许原始名称，且与分发使用相同的后端授权器。 Proxy 会筛选发现结果，并在实际的上游会话中、业务调用前再次检查该决策。预期的托管拒绝会返回正常的 MCP 工具错误，其中包含不含内容的原因代码。绝对过期时间和单调时钟截止时间都会生效；报告不会续租。托管上下文不授权资源方法。同步配置文件会绕过持久化工具缓存和过期回退。规范别名优先；必需的组织准入也会将本地静态和旧版运行时覆盖项排除在托管配置文件之外。 托管线路名称使用 ln_<full assignment UUID hex>__<original tool name>。 描述和元数据会保留易读的别名。因此，包含下划线的别名、重命名和替换分配都无法转移工具身份。 分配移除后，保留的 UUID 命名空间不会回退到静态／旧版路由；普通旧版工具名称仍保持现有形式。

无论是否启用可选活动捕获，托管调用也会保留不含内容的必需证据。CLI 会话旁的私有 SQLite 日志会在启动前提交每次尝试，并在分发前记录交接意图。它只会重试原始事件 UUID、主题和报告回执， 绝不会重试业务调用。原生操作系统锁会区分正在进行的调用和中断的调用。丢失的结果会保持未知状态。Registry 明确返回的 RUNTIME_PROFILE_FORBIDDEN 响应会使用原始报告回执记录被拒绝的调用；这不属于基础设施中断。存储不可用或容量耗尽时会阻止分发。本地 /status 会显示待处理／未解决数量和已关闭的交付代码。此范围受限的日志会保留被拒绝／已过期事实，以供显式解决。请参阅 证据契约。

安装

要求：

• Python 3.11 或更高版本
• pipx
• LightNow 账户
• LightNow CLI

pipx install lightnow-cli
lightnow login

使用 Homebrew 安装代理：

brew tap lightnow-ai/tap
brew install lightnow-proxy

或使用 pipx 安装：

pipx install lightnow-proxy

或使用 uv 安装：

uv tool install lightnow-proxy

Python 包会安装 MCP 客户端使用的 lightnow-proxy 命令。

进行仓库本地开发：

uv tool install --from . lightnow-proxy

通过 LightNow CLI 更新受支持的 CLI 和 Proxy 安装：

lightnow update --check
lightnow update

Homebrew、pipx 和 uv 均由包管理器管理。代理只会在仅含元数据的心跳中报告其检测到的版本和更新状态；它绝不会调用包管理器，也不会为了检查是否有新版本而延迟 MCP 启动。

配置客户端

使用 LightNow CLI。它会写入客户端 MCP 条目和每客户端的 Local Proxy 配置。

lightnow sync --client codex --local-proxy
lightnow sync --client claude-desktop --local-proxy
lightnow sync --client cursor --local-proxy
lightnow sync --client vscode --local-proxy
lightnow sync --client antigravity --local-proxy

同步后重启 MCP 客户端。

多个账户和组织

对于需要在同一个 MCP 客户端中显示的每个账户、组织或配置文件，请使用不同的 --connection 别名：

lightnow login
lightnow sync --client codex --local-proxy \
  --connection lightnow-personal --profile default

# Sign in with the organization account before creating this connection.
lightnow login
lightnow sync --client codex --local-proxy \
  --connection lightnow-acme --tenant <tenant-id> --profile engineering

每个生成的代理配置都有一个稳定的连接 ID，并指向 ~/.lightnow/sessions/ 下一个已命名的 CLI 会话。配置还会记录预期的签发者和主体。如果这些值不匹配，代理会拒绝 Registry 请求，因此后续 CLI 登录不会在不知情的情况下切换现有连接。代理 YAML 中不会写入访问令牌或刷新令牌。

检查本地设置：

lightnow config-status --client codex

检查代理能否解析所选配置文件并连接到其上游 MCP 服务：

lightnow-proxy --health
lightnow-proxy --health --json

默认情况下，此操作会读取 ~/.lightnow/lightnow-proxy/default.yaml。将默认配置文件同步到 Local Proxy 模式时会写入此文件。对于特定客户端的配置，请显式传入生成的路径：

lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json

已命名的连接使用单独的文件，例如 ~/.lightnow/lightnow-proxy/codex-lightnow-acme.yaml。JSON 健康报告会显示其非敏感连接别名、ID、账户标签、范围、配置文件和身份绑定状态。使用 cli_config_path 的旧版配置仍可读取，但仅限于配置的身份验证签发者。

启用遥测后，活动健康检查和运行时事件会发送到 LightNow Control Plane。默认情况下会捕获工具调用参数，也可以在 Local Proxy 设置中单独关闭。传输前会对类似凭据的字段进行脱敏。代理还会在启动时立即发送设备状态信息，之后每两分钟发送一次。Control Plane 随后可以显示哪些设备、客户端和配置文件处于活动、健康、降级或故障状态，以及 CLI/Proxy 版本和更新状态。不会存储工具结果、解析后的 LightNow 密钥、未脱敏的授权值、网络地址、硬件标识符和本地路径。类似凭据的参数字段（包括授权标头）会在传输前替换为 [REDACTED]。

为运行时解析配置的 Vault 提供程序会在此主机上解析，此时 Registry API 已返回不含凭据或密钥值的提供程序引用。默认使用 HashiCorp Vault Proxy 在 127.0.0.1:8200 上进行自动身份验证。可在生成的 YAML 中通过 runtime_secrets.providers 映射提供程序专用的本地回环监听器；后续同步时，LightNow CLI 会保留这些非敏感映射。可通过 lightnow-proxy[keyring] 使用可选的 OS 密钥环路径。解析失败时会默认拒绝，明文值绝不会加入工具架构缓存。

受管理的运行时文件

STDIO 服务可以在其 Runtime Profile 客户端配置中附加有大小限制的非敏感 runtime_files。LightNow Proxy 会在上游进程启动前，将每组文件写入 ~/.lightnow/runtime-files 下不可变的内容寻址目录。文件权限为 0600；受管理目录的权限为 0700。

在参数、环境变量值或工作目录中使用 ${LIGHTNOW_RUNTIME_DIR} 引用解析后的目录：

{
  "transport": "stdio",
  "command": "npx",
  "args": [
    "@bytebase/dbhub@latest",
    "--config",
    "${LIGHTNOW_RUNTIME_DIR}/dbhub.toml"
  ],
  "env": {
    "DBHUB_DSN": "${DBHUB_DSN}"
  },
  "runtime_files": [
    {
      "path": "dbhub.toml",
      "content": "[[sources]]\nid = \"analytics\"\ndsn = \"${DBHUB_DSN}\"\n"
    }
  ]
}

运行时文件必须为 UTF-8 文本，且每组配置最多包含 16 个文件，每个文件不超过 64 KiB，每个服务配置不超过 256 KiB。路径必须是相对路径，且不得包含路径遍历片段或反斜杠。密钥值必须保留在 LightNow 的运行时密钥存储区中；文件可以引用相应的环境变量名称，但不得嵌入明文凭据。无效或被修改的物化文件会在上游启动前默认拒绝。

更多文档

详细的设置指南、示例、图表、支持的客户端路径、遥测行为和故障排除内容均见 LightNow 文档：

• 连接 MCP 客户端
• CLI 参考
• 发布流程

本地开发

适用于参与此代码库开发的贡献者：

uv venv
uv pip install -e .[dev]
make test

Jenkins 会构建运行时镜像，在镜像中运行 make lint test 中的 Ruff 和 pytest 命令，然后检查 lightnow-proxy --help。 代码库检出目录以只读方式挂载，测试环境位于容器中。 Jenkinsfile 使用原生的 build-agent 能力池，并且只移除自己的验证镜像。超时时间包含分配 Agent 的耗时。 GitHub Actions 继续运行 Python 版本矩阵。在合并 Ops 依赖更新之前，要求 Jenkins 在当前 PR 最新提交上成功完成。 该流水线会验证更改，不会发布镜像或更改账户。

使用示例配置运行代理：

uv run lightnow-proxy --config config.example.yaml

将代理作为 stdio MCP 服务运行：

uv run lightnow-proxy --config config.example.yaml --transport stdio

使用示例配置运行本地运行状况检查：

uv run lightnow-proxy --config config.example.yaml --health