[Bug] 插件 .mcp.json 的 ${VAR:-default} 环境变量插值不生效,字面量被当作 Bearer 发送(context7 报 Invalid API key)
Nobody has claimed this yet.
- 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
- 安装 context7 插件,不设置
CONTEXT7_API_KEY环境变量(注册表、shell profile、用户配置中均无此变量) - 重启 ZCode 使插件 MCP server 连接
- 调用
mcp__plugin_context7_context7__resolve-library-id(任意参数) - 收到 "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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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