zai-org / zai-org/feedback

[Bug] 插件 .mcp.json 的 ${VAR:-default} 环境变量插值不生效,字面量被当作 Bearer 发送(context7 报 Invalid API key)

Open
#539 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

priority: P2
Dominant language
No language data
Stars
22
Forks
1
PR merge metrics
No merged PRs in 30d

Description

问题类别 · Category: 工具调用 / MCP · Tool use / MCP
Agent 框架 · Framework: ZCode Agent(自研)
严重程度 · Severity: 影响体验 · Major(相关插件无法开箱即用,需手动改缓存文件绕过)
复现频率 · Reproducibility: 必现 · Always

提交前确认:已搜索现有 issue(含 #480 等插件相关 issue),确认不是重复。

问题描述 · Description

插件 .mcp.json(HTTP 型 MCP server)的 headers 中使用了环境变量插值:

"headers": {
  "Authorization": "${CONTEXT7_API_KEY:-}"
}

在未设置 CONTEXT7_API_KEY 的情况下,期望按 ${VAR:-default} 语义回落为空(或不发送该头)。实际 ZCode 没有做插值/回落处理,把字面量 ${CONTEXT7_API_KEY:-} 原样作为 Bearer 令牌发送,远端校验失败,插件完全不可用。

以官方市场的 context7 插件(context7@claude-plugins-official)为例,其 README 明确说明"不设置 key 时匿名访问",但实际调用任何工具都报:

Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix.

复现步骤 · Steps to reproduce

  1. 安装 context7 插件,不设置 CONTEXT7_API_KEY 环境变量(注册表、shell profile、用户配置中均无此变量)
  2. 重启 ZCode 使插件 MCP server 连接
  3. 调用 mcp__plugin_context7_context7__resolve-library-id(任意参数)
  4. 收到 "Invalid API key" 错误

期望表现 · Expected behavior

  • 支持 .mcp.json${VAR} / ${VAR:-default} 形式的环境变量插值;
  • 变量未设置且默认值为空时,不发送该 header(回落到匿名/无认证访问)。

实际表现 · Actual behavior

未设置变量时,请求头被置为字面量 Authorization: ${CONTEXT7_API_KEY:-},远端返回 Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix.

对照验证 · Evidence(curl)

对同一端点 https://mcp.context7.com/mcp 做对照实验:

  • 不带 Authorization 头 → 正常返回文档查询结果(服务端确认匿名通道可用)✅
  • Authorization: ${CONTEXT7_API_KEY:-} 字面量 → 精确复现插件收到的报错 ❌

环境信息 · Environment

  • 系统:Windows 11(10.0.26200 x64)
  • 客户端:Windows 桌面端(日志中 mcpClientVersion: 0.16.5,应用版本号请见评论区补充)
  • 插件:context7@claude-plugins-official 0.0.0

临时解决方案 · Workaround(供其他用户参考)

手动编辑插件缓存副本 ~/.zcode/cli/plugins/cache/claude-plugins-official/context7/0.0.0/.mcp.json,删除整个 headers 字段后重启 ZCode,即可走匿名通道。注意:插件升级/重装会还原该文件,届时需要重新操作。

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the context7 plugin's .mcp.json and reproduce the request against https://mcp.context7.com/mcp with CONTEXT7_API_KEY unset. Trace the ZCode MCP connection and header handling; done means ${VAR} and ${VAR:-default} are handled and an empty default does not send Authorization.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.