Claude-Code配置学习笔记-MCP-Hooks与ECC插件系统

📅 整理时间：2026-05-01 ~ 2026-05-03 💻 环境：Windows 11 + Node.js v24.12.0 + Git Bash ⏱️ 预计阅读：25 分钟 🏷️ 关键词：Claude Code, MCP, Hooks, Plugins, ECC, Windows 配置

写在前面

这篇文章是我配置 ECC (Everything Claude Code) 插件过程中的完整学习记录。

在尝试安装 ECC 插件时，我遇到了一系列问题：MCP 服务器连接失败、Hooks 不生效、配置文件加载异常……折腾了整整两天，查阅了官方文档、GitHub Issues、社区文章，才逐一解决。

过程中我意识到，Claude Code 的配置体系虽然强大，但学习资料相对分散，尤其是 Windows 平台的坑特别多（根据社区反馈，配置失败率高达 70%）。于是决定把自己的踩坑经历整理成文，希望能帮到同样在配置路上的朋友。

本文特色：

• ✅ 从实际问题出发，而非抽象的概念介绍
• ✅ Windows 平台专属排坑指南
• ✅ 配置验证命令和检查清单
• ✅ 结合官方文档和社区经验的理论总结

前言

Claude Code 是 Anthropic 官方推出的 AI 编程助手 CLI 工具。其扩展体系包含 七大核心系统：

系统关系：Plugins 是容器，打包了 Skills、Rules、Agents、Hooks、Commands；MCP 是独立的工具协议层。

📝 本文范围：本文重点介绍 MCP、Hooks 和 Plugins 三大系统，并涉及 Plugins 内包含的 Skills、Rules、Agents、Commands 组件。这些是我在配置 ECC 插件过程中实际接触和学习的部分。

本文将从实际配置问题出发，并特别针对 Windows 平台提供详细的排坑指南。

一、MCP 服务器配置

1.1 什么是 MCP

MCP (Model Context Protocol) 是 Anthropic 推出的开放协议，允许 Claude Code 连接外部工具和数据源。通过 MCP，Claude 可以：

• 读写本地文件系统
• 搜索 GitHub 仓库
• 查询文档库（如 Context7）
• 操作数据库
• 调用自定义 API

1.2 MCP 服务器类型

1.3 Windows 平台 MCP 配置问题

根据网络搜索结果，Windows 上 MCP 配置失败率高达 70%。以下是主要问题及解决方案。

问题一：缺少 cmd /c 包装器

Windows 的 stdio 管道机制与 Unix 不同。Claude Code 启动 MCP 子进程时，直接使用 "command": "node" 在 Windows 上常常导致 stdio 握手失败。

解决方案：使用绝对路径或 cmd /c 包装

// 方案一：直接使用 node.exe 绝对路径（推荐）{  "command": "C:/Program Files/nodejs/node.exe",  "args": ["path/to/server.js"]}// 方案二：cmd /c 包装{  "command": "cmd",  "args": ["/c", "node", "path/to/server.js"]}

问题二：PATH 环境变量作用域问题

应用启动子进程时不加载 shell 配置文件（.bashrc 等），因此：

• 在终端中 node -v 正常
• 但 MCP 子进程报 spawn node ENOENT（找不到命令）

解决方案：在 settings.json 中正确设置 PATH

// ❌ 错误 - Git Bash 风格，Windows 原生环境不认识"PATH": "...;/c/Program Files/nodejs;{PATH}"

问题三：Health Check 误报

Claude Code 的 claude mcp list 健康检查不会发送 initialize 请求（GitHub Issue #9662），导致 stdio 服务器在 health check 时超时。

⚠️ 这是官方已知问题。health check 失败 ≠ MCP 无法使用，需要在实际对话中测试。

1.4 完整配置示例

~/.claude.json (MCP 服务器配置)

{  "mcpServers": {    "filesystem": {      "command": "C:/Program Files/nodejs/node.exe",      "args": [        "C:/Users/[用户名]/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",        "C:/Users/[用户名]"      ]    },    "context7": {      "type": "http",      "url": "https://mcp.context7.com/mcp",      "headers": {        "CONTEXT7_API_KEY": "your-api-key"      }    },    "memory": {      "command": "C:/Program Files/nodejs/node.exe",      "args": [        "C:/Users/[用户名]/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-memory/dist/index.js"      ]    },    "github": {      "command": "C:/Program Files/nodejs/node.exe",      "args": [        "C:/Users/[用户名]/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-github/dist/index.js"      ],      "env": {        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"      }    }  }}

~/.claude/settings.json (环境变量配置)

{  "env": {    "PATH": "C:/Program Files/nodejs;C:/Users/[用户名]/AppData/Roaming/npm;{PATH}（非 (ls ~/.claude/everything-claude-code/skills/ 2>/dev/null | wc -l)    RULES=(ls ~/.claude/everything-claude-code/agents/ 2>/dev/null | wc -l)    echo "   - Skills: RULES"    echo "   - Agents: $AGENTS"else    echo "⚠️ ECC 插件未安装"fiecho ""echo "=== 检查完成 ==="

九、记忆系统

9.1 什么是记忆系统

Claude Code 提供了记忆（Memory）功能，允许跨会话保存和检索信息。

9.2 记忆存储位置

9.3 记忆相关 MCP 工具

通过 memory MCP 服务器提供以下工具：

9.4 使用场景

• 记住用户偏好和习惯
• 保存项目特定的约定和规则
• 跨会话保持上下文信息

十、常见问题 FAQ

Q1: MCP 服务器显示连接失败，但功能正常？

原因：Claude Code 的 health check 有 Bug（Issue #9662），不会发送 initialize 请求。

解决：忽略 health check 结果，在实际对话中测试 MCP 功能。

Q2: 修改配置后不生效？

原因：Claude Code 可能有残留进程。

解决：

1. 输入 /exit 退出
2. 关闭终端窗口
3. 重新打开终端运行 claude

Q3: Windows 上报 spawn node ENOENT？

原因：子进程不加载 shell 配置，找不到 node 命令。

解决：在 MCP 配置中使用 node.exe 的绝对路径：

{  "command": "C:/Program Files/nodejs/node.exe",  "args": ["path/to/server.js"]}

Q4: Hooks 没有触发？

排查步骤：

1. 检查 matcher 是否正确
2. 检查命令路径是否正确
3. 查看终端是否有错误输出
4. 确认配置文件位置正确

Q5: 如何查看当前加载了哪些 Skills/Rules？

# 查看 ECC 插件的 Skillsls ~/.claude/everything-claude-code/skills/# 查看用户自定义的 Skillsls ~/.claude/skills/# 查看 Rulesls ~/.claude/everything-claude-code/rules/common/ls ~/.claude/rules/

Q6: 插件和用户配置冲突怎么办？

优先级规则：用户目录 > 插件目录

如果用户目录有同名文件，用户版本会覆盖插件版本。建议：

• 不要直接修改插件目录的文件
• 在用户目录创建同名文件进行覆盖
• 或在用户目录创建新文件进行补充

十一、参考资源

官方文档

• Claude Code 官方文档
• Claude Code MCP 文档
• MCP 服务器市场

社区资源

• ECC GitHub
• Claude Code MCP 配置完整指南 - 掘金
• Windows 下 spawn ENOENT 错误解决方案 - 掘金

GitHub Issues

• Issue #9662 - Health Check Bug

结语

写这篇文章的时候，我回顾了自己两天的踩坑历程：从最初 MCP 连接失败的迷茫，到逐一排查 PATH、绝对路径、health check bug；从对 Hooks 一知半解，到理解其事件驱动的工作机制；从手动复制配置文件，到发现插件"一键开启"的便利。

这个过程中最大的感悟是：Claude Code 的配置体系设计得很好，但文档分散、Windows 兼容性问题多。希望这篇文章能帮助后来者少走弯路。

七大核心系统速查：

本文重点：MCP 配置（Windows 排坑）、Hooks 系统、Plugins 插件（含 Skills/Rules/Agents/Commands）。

配置优先级：用户目录 > 插件目录

如果你在配置过程中遇到其他问题，欢迎在评论区交流！

作者：王木木整理工具：Claude Code + Obsidian

附录：文章结构导航

前言：七大核心系统概览（本文聚焦 MCP、Hooks、Plugins）一、MCP 服务器配置   ├── 什么是 MCP   ├── MCP 服务器类型   ├── Windows 平台配置问题（重点）   ├── 完整配置示例   └── 常见错误速查二、Hooks 钩子系统   ├── Hook 生命周期   ├── Hook 类型与匹配规则   ├── 配置结构   └── Token 消耗说明三、Plugins 插件系统   ├── 什么是插件   ├── ECC 插件简介   ├── Skills 详解   ├── Rules 详解   ├── Agents 详解   ├── Commands 详解   └── 加载优先级四、配置生效与重启五、故障排查六、最佳实践七、ECC 插件安装指南八、配置验证清单九、记忆系统十、常见问题 FAQ十一、参考资源