kconfig-mcp

kconfig-mcp

“为什么无法启用 CONFIG_X？”答案附有文件名和行号，以及经过验证的修复方案。

kconfig-mcp 是一个 MCP 服务，可让 AI Agent 分析 Kconfig——Linux 内核、Zephyr、U-Boot、Buildroot 等项目使用的配置系统。

配置过内核的人都遇到过这种情况：想要的选项不在 menuconfig 中，或者虽然在，但显示为灰色；原因却藏在另一个目录中，隔着五层 depends on。kconfig-mcp 会为你追踪这条依赖链。然后，它会搜索能够解锁该选项的最小改动集合，并在向你展示之前，将其应用到实际源码树中进行验证。

效果展示

以下是在当前 Linux 源码树（18,913 个符号）上针对 x86 的真实输出：

> kconfig_why_not X86_X2APIC
X86_X2APIC = n (default), needs y - bool at arch/x86/Kconfig:463
  its prompt (arch/x86/Kconfig:463) is visible only if
  X86_LOCAL_APIC && X86_64 && (IRQ_REMAP || HYPERVISOR_GUEST), which is n:
    needs any one of (2 options, all currently too low):
      IRQ_REMAP = n (default), needs y - bool at drivers/iommu/Kconfig:201
        its prompt is visible only if X86_64 && X86_IO_APIC && PCI_MSI && ACPI && IOMMU_SUPPORT:
          PCI_MSI = n (default), needs y - bool at drivers/pci/Kconfig:44
            its prompt is visible only if PCI, which is n:
              PCI = n (default) - set PCI=y directly.
      HYPERVISOR_GUEST = n (default), needs y - bool at arch/x86/Kconfig:787
        its prompt is visible - set HYPERVISOR_GUEST=y directly.

Verified fix (2 change(s)): HYPERVISOR_GUEST=y, X86_X2APIC=y
  HYPERVISOR_GUEST: arch/x86/Kconfig:787
  X86_X2APIC: arch/x86/Kconfig:463
Unverified alternatives: PCI=y, PCI_MSI=y, IRQ_REMAP=y, X86_X2APIC=y

> kconfig_set HYPERVISOR_GUEST y
CONFIG_HYPERVISOR_GUEST: 'n' -> 'y'.
1 other symbol(s) changed as a consequence: X86_X2APIC n->y

对于 32 位构建（ARCH=i386）提出同样的问题时，最终发现无论如何更改符号都无法实现目标；工具会如实说明，而不是编造修复方案：

64BIT = n (default), needs y - bool at arch/x86/Kconfig:3
  requires "i386" = "x86", which compares two constants and is always false here.
  One side was probably expanded from an environment variable (like $(ARCH)) when
  the tree was loaded: no symbol change can fix this - reload with a different env.
No verified fix: every route ends in something no assignment can change.

构建理念

• 修复经过验证，而非猜测。 Kconfig 有许多边界情况：三态值 m 需要 MODULES，bool 会将 m 提升为 y，choice 会取消选择其他成员， select 会覆盖 depends on，而 default y 则会静默启用选项。因此，每个候选方案都会应用到已加载的源码树中并进行检查。只有确实能实现目标的方案才会作为修复方案展示，同时还会列出其副作用（哪些其他选项会因 select/imply/默认值而启用或关闭）。
• 可解析当前版本的 Linux。 它基于 Kconfiglib 构建；Kconfiglib 自 2020 年以来就没有发布过新版本，无法解析 Linux 中较新的 modules、transitional 和 depends on X if Y 语法。kconfig-mcp 会在读取文件时重写这些行，同时精确保留每一行的行号。depends on X if Y 的转换逐行移植了 scripts/kconfig/expr.c 中的 expr_trans_compare，因此行为与 kconfig 完全一致，包括 kconfig 对 S 为 m 时 !S 的处理方式。
• 明确指出环境问题。 Linux 会加载 arch/$(SRCARCH)/Kconfig，而未设置的变量会静默变成 ""。kconfig-mcp 会追踪未定义的变量，并在错误信息中指出它们（undefined variable(s): SRCARCH (the arch/ directory to use, ...)），而不是只告诉你找不到 arch//Kconfig。

安装

pip install kconfig-mcp
claude mcp add kconfig -- kconfig-mcp

需要 Python 3.10 或更高版本。无需内核构建环境，只需包含 Kconfig 文件的源码树，即使是稀疏检出也可以：

git clone --depth 1 --filter=blob:none --sparse https://github.com/torvalds/linux.git
cd linux && git sparse-checkout set --no-cone '/Kconfig' '**/Kconfig*' '/arch/*/configs/*'

加载源码树

源码树	kconfig_load 参数
Linux	kconfig_path="linux/Kconfig"，env={"SRCARCH": "x86", "ARCH": "x86"}（或 arm64/arm64、riscv/riscv 等）。对于已有配置，添加 config_path=".config"。
Linux，无编译器 / Windows	同上，另加 shell="dry"
其他源码树	顶层 Kconfig，以及它展开时所需的变量。加载错误会指出每个缺失的变量。

shell 控制源码树中的 $(shell,...) 调用；Linux 会用这种方式探测编译器：

• "run"（默认）使用 POSIX sh 运行这些调用，与 make menuconfig 的行为相同。 依赖编译器的符号会反映你的实际工具链。
• "dry" 不运行任何命令。Linux 的探测惯用写法会得到固定结果：功能探测结果为不存在，工具链则报告为 GCC 13.2。$(error-if) 检查会变为警告。此时结果会附带说明：像 CC_HAS_* 这样的依赖编译器的符号会被视为不存在。

工具

工具	功能
kconfig_load	将树（以及可选的 .config）解析到命名会话中。报告未定义的变量和警告。
kconfig_why_not	递归说明 symbol 未达到 y/m/n 的未满足条件，并提供带文件:行号的说明、经过验证的最小修复方案及其副作用。
kconfig_symbol	类型、提示词、值及该值的原因、可赋值的值、依赖项、默认值、双向的 select/imply、帮助文本。
kconfig_what_selects	所有会选择或暗示此符号的符号、它们当前的值以及哪些处于生效状态。
kconfig_search	在名称、提示词和帮助文本中进行正则搜索，并优先显示名称匹配结果。
kconfig_set	像 menuconfig 一样设置值，并报告所有发生变化的其他符号。若拒绝赋值，会说明原因。
kconfig_diff	与另一个 .config、defconfig 或使用 fragment=True 指定的片段进行比较。
kconfig_save	写入 .config，或使用 minimal=True 写入最小 defconfig。
kconfig_sessions / kconfig_unload	管理已加载的树。

符号名称可带或不带 CONFIG_。名称拼写错误时，会提示“Did you mean: ...”。

限制

• transitional 符号始终为 n。 真实的 kconfig 会从旧 .config 中读取这些符号，以便在重命名时迁移值。Kconfiglib 没有对应功能。
• 修复搜索有范围限制。 只有当符号无法通过自身提示词触达时，才会探索 select 和默认值；搜索还设有扩展预算。如果找不到经过验证的修复方案，结果会说明是预算耗尽，还是所有路径都确实受阻。
• why_not 适用于 bool 和 tristate 符号。 对于 int/hex/string 符号，请使用 kconfig_symbol 和 kconfig_set。
• Dry 模式会笼统回答编译器探测问题（见上文），因此只有在真实工具链上使用 shell="run" 时，才应相信 CC_HAS_* 这类符号。
• 它依赖 Kconfiglib 14.1.0，并固定使用此版本，因为 compat.py 会挂接其两个内部方法。CI 每周解析最新的 Linux 树，因此下一个新增关键字会导致构建失败，而不是悄然给出错误答案。

测试

pip install ".[test]" "ruff==0.16.0" "mypy==2.3.0"
ruff check src tests && mypy --strict src
pytest tests                                   # unit + stdio tests, fixture trees
LINUX_SRC=/path/to/linux pytest tests/test_linux_integration.py

tests/fixtures/tree 中的测试树涵盖了解释器处理的所有结构：depends on、select、imply、choice、visible if、menuconfig/if 块、默认值、tristate 和 modules，以及由 $(SRCARCH) 选择的架构目录。Linux 测试会断言真实情况，例如 x2APIC 的依赖项、i386 的死路，以及 x86_64 defconfig 已启用它。CI 会针对当前树的稀疏检出运行这些测试。

许可证

MIT。Kconfiglib 采用 ISC 许可证。