企业官网建设流程全解析

1. 先搞清楚 Claude Code 工具系统到底在解决什么问题

Claude Code 的工具系统，说白了就是一套让模型从“只会聊天”变成“能动手干活”的机制。你给它一个任务，它需要读文件、搜代码、跑命令、改配置，这些动作背后都是一个个具体的工具在支撑。官方内置了 30 多个工具，覆盖文件操作、搜索、执行、任务管理、信息获取、辅助交互六大类。但真正让这套系统有意思的地方在于：除了内置工具，它还支持 MCP 和 Skills 两种扩展方式，三者都出现在同一个 tools[] 数组里，从 API 角度看长得一模一样，但运行机制完全不同。

如果你正在用 Claude Code 做日常开发，或者想把它接入自己的项目流程，理解这套工具系统的分类和协作方式，能帮你少走很多弯路。比如你知道什么时候该写一个 Skill 而不是配一个 MCP Server，知道为什么有些工具默认不在 tools[] 里出现，知道怎么在本地验证工具调用链路是否正常。这篇文章会从工具分类地图讲起，然后给出 MCP 配置片段和 Skills 目录结构示例，最后用可复现的步骤带你在本地跑通一次完整的工具调用。

我试过在几个不同规模的项目里配置 Claude Code 的工具链，踩过的坑主要集中在 MCP 连接超时和 Skill 目录扫描不到这两个问题上。下面把整理出来的工具清单和配置方法分享给你，照着做基本能跑通。

2. 30+ 内置工具的分类地图与核心设计思路

Claude Code 的内置工具不是随便堆在一起的，它们按职责分成六个族，每个族有清晰的设计边界。下面这张表是我根据实际使用和源码结构整理的分类清单，你可以对照着看自己常用哪些。

文件操作族里最需要留意的是 Write 和 Edit 的区别。Write 是完整覆盖文件，旧内容直接丢失，权限检查最严格；Edit 是精确字符串替换，需要提供 old_string 和 new_string，模型“看到什么改什么”，不需要理解 diff 语法。这个设计选择很聪明，因为 LLM 生成 diff 格式容易出错，但复述文本很擅长。

搜索族的三件套 Glob、Grep、LSP 是互补关系。Glob 按文件名模式匹配，Grep 搜文件内容，LSP 做语义级引用查找。举个例子，你要理解 UserService 这个类：先用 Glob 找到**/UserService.ts，再用 Grep 搜哪些文件 import 了它，最后用 LSP 找所有语义引用。三步下来，这个类的使用情况就清楚了。

执行族的 Bash 工具是权限系统的重点保护对象，它有专门的 AST 权限检查，也是唯一使用沙盒隔离的工具。在 Windows 上会注册 PowerShell 工具，其他平台用 Bash。这个跨平台适配是自动的，你不需要手动切换。

Agent 控制族里 TodoWrite 和 Task 系列定位完全不同。TodoWrite 是同步的任务清单，你在终端里看到 Agent 输出的有序步骤列表就是它生成的；Task 系列是异步任务管理，用来并行执行独立任务。AgentTool 则允许 fork 子 Agent，子 Agent 有自己的上下文和工具池，执行完结果回流。这个递归机制让 Agent 能按需分层，主 Agent 规划、子 Agent 执行、子子 Agent 验证。

信息获取族的 WebFetch 和 WebSearch 受权限和网络策略控制，WebFetch 只能访问允许的域名列表。辅助工具族里 AskUserQuestion 比较特殊，它是唯一一个 bypass 模式也拦不住的工具，因为设计意图就是必须用户参与。

3. MCP 配置片段与 Skills 目录结构实操

理解了内置工具的分类，接下来看 MCP 和 Skills 怎么接入。这两者的配置方式完全不同，MCP 走协议连接，Skills 走文件扫描。

先看 MCP 的配置。Claude Code 通过.mcp.json文件声明 MCP Server，支持 stdio 和 SSE 两种传输方式。下面是一个标准的 MCP 配置片段，你可以直接复制到项目根目录的.mcp.json里：

{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project" ], "env": {} }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here" } } } }

这个配置声明了两个 MCP Server：filesystem 提供文件系统操作工具，github 提供 GitHub 相关工具。启动 Claude Code 时，它会读取这个文件，通过connectToServer()建立连接，然后调用tools/list协议获取工具列表。每个 MCP 工具会被buildTool({ isMcp: true })包装成标准 Tool 接口，和内置工具合并进 tools[] 数组。

如果你用的是 TaoToken 的 API 接入，Base URL 填https://taotoken.net/api，Key 在控制台创建，Model ID 根据你用的模型填。这三件套在 MCP 配置里也需要对应设置，确保 MCP Server 能正常调用模型。

再看 Skills 的目录结构。一个 Skill 就是一个 Markdown 文件，放在特定目录下，Claude Code 启动时会扫描这些目录。标准的 Skills 目录结构是这样的：

.claude/ └── skills/ ├── deploy.md ├── test.md └── format.md

每个.md文件用 frontmatter 定义元信息，正文定义 Prompt。比如deploy.md的内容：

--- name: deploy description: 部署当前分支到 staging 环境 --- ## 部署流程 1. 先用 Bash 跑 `git status` 确认当前分支 2. 跑 `npm test` 确保测试通过 3. 跑 `docker build -t app:staging .` 构建镜像 4. 跑 `kubectl apply -f deploy.yaml` 部署到 staging 5. 输出部署结果和版本号

当模型调用SkillTool(command: "deploy")时，SkillTool 会找到这个文件，fork 一个子 Agent，把 Markdown 内容作为 Prompt 注入，子 Agent 独立执行这些步骤。注意 Skill 不新增能力，它只是编排已有工具的使用方式。

MCP 和 Skills 的 Token 效率都很高。MCP 工具默认不在 tools[] 里，只有 ToolSearchTool 的 description 里有一行摘要；Skills 永远只占 SkillTool 一个条目，正文不传。只有真正调用时才展开完整内容。这是渐进式披露思想在工具层面的体现。

4. 本地验证工具调用链路的可复现步骤

配置写好了，怎么确认工具调用链路是通的？下面是一套可复现的验证步骤，从启动到看到结果，每一步都有明确的预期输出。

第一步，确认 MCP Server 能正常启动。在终端里直接跑配置里的命令：

npx -y @modelcontextprotocol/server-filesystem /path/to/your/project

如果这个命令能正常启动并保持运行，说明 MCP Server 本身没问题。如果报错，先解决依赖安装或路径问题。

第二步，启动 Claude Code 并检查 MCP 连接状态。在项目目录下运行：

claude --mcp-debug

这个参数会输出 MCP 连接的详细日志。你应该能看到类似Connected to MCP server: filesystem和Fetched N tools from filesystem的输出。如果看到MCP server connection failed，检查.mcp.json的路径和命令是否正确。

第三步，验证内置工具调用。在 Claude Code 对话里输入：

帮我读取 package.json 文件的前 20 行

预期结果是模型调用 Read 工具，返回文件内容。如果模型说“我无法读取文件”，说明工具注册有问题，检查是否有 Feature Gate 把 Read 工具裁掉了。

第四步，验证 MCP 工具调用。输入：

列出当前项目根目录下的所有文件

如果 filesystem MCP Server 配置正确，模型会先通过 ToolSearchTool 搜索 filesystem 相关工具，然后调用mcp__filesystem__list_directory返回文件列表。你可以在输出里看到工具调用的完整链路。

第五步，验证 Skill 调用。确保.claude/skills/deploy.md存在，然后输入：

执行 deploy 技能

预期结果是模型调用 SkillTool，fork 子 Agent，子 Agent 按 Markdown 里的步骤依次执行。你会在输出里看到子 Agent 的独立执行过程，最后结果回流到主 Agent。

第六步，检查 Token 消耗。在对话里输入/cost查看当前会话的 Token 使用情况。正常情况下，MCP 工具和 Skills 的 Token 开销应该远低于把所有工具 Schema 都传进去的情况。如果发现 Token 异常高，检查是否有 MCP Server 返回了过多工具。

这套步骤跑下来，基本能确认工具调用链路是通的。如果某一步卡住，下一节的排查清单能帮你定位问题。

5. 常见报错与排查清单

工具调用链路出问题时，报错信息往往比较隐晦。下面是我实际遇到过的几类典型报错和对应的排查方法。

401 Unauthorized：这个报错通常出现在 MCP Server 需要认证但 Token 无效或过期时。检查.mcp.json里对应 Server 的env字段，确认 Token 是否正确。如果是 TaoToken 的 API Key，去控制台确认 Key 状态和额度。另外注意 Base URL 是否填对，API 地址是https://taotoken.net/api，不要多加路径。

local proxy failed：这个报错说明 MCP Server 的本地连接建立失败。常见原因是命令路径不对，或者 npx 包没有正确安装。先在终端里手动跑一遍 MCP Server 的启动命令，确认能正常启动。如果手动能跑但 Claude Code 里报错，检查.mcp.json的 JSON 格式是否有语法错误。

reading choices 相关报错：这个通常出现在模型返回格式不符合预期时。检查你用的 Model ID 是否和 API 端点匹配。如果用的是 TaoToken 的 Coding Plan，确认 Model ID 填的是套餐支持的模型。另外检查 MCP Server 返回的工具 Schema 是否合法，有些第三方 Server 的 Schema 可能不符合规范。

OAuth 相关报错：如果 MCP Server 需要 OAuth 认证，检查回调地址和 Client ID 配置。这类问题通常需要看 MCP Server 的文档，确认认证流程是否正确。

Skill 目录扫描不到：确认.claude/skills/目录存在，且.md文件有正确的 frontmatter。frontmatter 必须包含name和description字段，缺一个都可能导致扫描失败。另外检查文件编码，确保是 UTF-8。

工具调用超时：MCP Server 响应太慢会导致超时。检查 Server 的网络连接和性能，如果是远程 Server，确认网络延迟在可接受范围内。可以在.mcp.json里调整超时参数，但根本解决还是要优化 Server 响应速度。

排查时建议按链路顺序来：先确认 MCP Server 能独立启动，再确认 Claude Code 能连上，最后确认工具能被调用。每一步都有对应的日志输出，--mcp-debug参数能帮你看到详细的连接过程。

6. 把工具系统用起来的几个实用建议

工具系统配置好之后，怎么用得更顺手？分享几个实际经验。

MCP Server 不要配太多。每多一个 Server，启动时就多一次连接和工具发现，Token 开销也会增加。只配当前项目真正需要的，比如文件系统、GitHub、数据库这几类高频的。不常用的按需临时加，用完删掉。

Skills 适合封装重复性流程。如果你发现自己反复让 Claude Code 做同一套操作，比如“跑测试、构建、部署”这个三步流程，就把它写成一个 Skill。Markdown 文件维护成本低，改起来也方便。

内置工具的权限设置要留意。Write 工具权限最严格，Bash 工具有沙盒隔离，这些默认设置不要轻易改。如果确实需要放宽权限，先确认操作范围可控。

验证工具调用链路时，从简单到复杂。先验证 Read 这种只读工具，再验证 Write 这种写操作，最后验证 MCP 和 Skills。这样出问题时容易定位是哪一层的问题。

如果你想把 Claude Code 接入自己的开发流程，建议先从 API Keys 和接入文档开始，把基础连接跑通，再逐步加 MCP 和 Skills。TaoToken 的模型对话功能可以用来快速验证模型响应，Coding Plan 适合长期编码场景。工具系统的配置和验证，本质上是一个逐步迭代的过程，不用一次配到完美。