mirror of https://github.com/claude-code-best/claude-code.git synced 2026-06-22 16:25:51 +00:00

Files

claude-code-best 178868175e docs: 添加文档大纲及 superpowers/outline 目录

Co-Authored-By: deepseek-v4-pro <deepseek-ai@claude-code-best.win>

2026-06-15 16:51:29 +08:00

14 KiB

Raw Blame History

第五章：扩展 Claude 的能力 -- MCP Server、插件、Skill

内置工具不够用时，用 MCP 接入外部服务，用插件扩展功能，用 Skill 沉淀工作流。

MCP 是什么？什么时候该用它

MCP（Model Context Protocol）是一种标准化协议，让 Claude Code 能调用外部程序提供的工具和资源。你可以把它理解成一个"工具插件接口"：任何实现了 MCP 协议的程序，都可以把自身能力暴露给 Claude Code 使用。

典型的使用场景包括：

数据库操作：接入一个 MCP server，让 Claude Code 能直接查询和管理数据库
API 交互：接入 Sentry、GitHub、Slack 等服务的 MCP server，让 Claude Code 能直接操作这些服务
文件系统扩展：接入特定格式（比如 Figma 设计文件）的 MCP server

MCP server 通过三种传输方式与 Claude Code 通信：

传输方式	适合场景	典型命令
stdio	本地命令行程序，如 `npx my-mcp-server`	`claude mcp add my-server -- npx my-mcp-server`
SSE	远程服务，通过 Server-Sent Events 通信	`claude mcp add --transport sse my-server https://example.com/sse`
HTTP	远程 HTTP 端点	`claude mcp add --transport http sentry https://mcp.sentry.dev/mcp`

如果你只是想让 Claude Code 做一些固定的本地操作（比如跑测试、读日志），通常写一个 Skill（见本章后半部分）更轻量。MCP 更适合需要持续运行的外部服务或复杂的多工具场景。

用 `claude mcp add` 接入现成 MCP server

最常见的方式是通过 claude mcp add 命令，把一个现成的 MCP server 注册到 Claude Code。

添加 stdio 类型的 server

stdio 类型适用于本地可执行程序，比如通过 npx 运行的 Node.js 包：

# 添加一个 stdio server，自动以 -- 后面的内容为子命令
claude mcp add my-server -- npx my-mcp-server

# 带环境变量
claude mcp add -e API_KEY=xxx my-server -- npx my-mcp-server

# 带额外参数
claude mcp add my-server -- my-command --some-flag arg1

添加 HTTP 或 SSE 类型的 server

对于远程 MCP 服务，需要指定传输方式：

# HTTP server
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 带认证头的 HTTP server
claude mcp add --transport http corridor https://app.corridor.dev/api/mcp \
  --header "Authorization: Bearer your-token"

# SSE server
claude mcp add --transport sse my-server https://example.com/sse

配置范围

-s 参数控制配置写入的位置，影响谁能看到这个 MCP server：

范围	说明	配置文件位置
`local`（默认）	仅当前项目	项目目录下的配置文件
`user`	当前用户所有项目	用户主目录下的全局配置
`project`	项目级共享（可提交到 git）	项目目录下的配置文件

例如，把一个数据库 MCP server 配置为整个团队可用：

claude mcp add -s project my-db -- npx my-db-mcp-server

管理已接入的 server

注册之后，你可以在对话内或通过 CLI 管理这些 MCP server。

CLI 方式

# 列出所有已配置的 MCP server
claude mcp list

# 查看某个 server 的详情
claude mcp get my-server

# 移除一个 server
claude mcp remove my-server

# 从特定范围移除
claude mcp remove -s local my-server

对话内方式

在 REPL 中输入 /mcp 会打开 MCP 管理面板。你可以在这里：

启用/禁用 server：/mcp enable my-server 或 /mcp disable my-server
批量操作：/mcp enable all 或 /mcp disable all
重新连接：/mcp reconnect my-server（当连接断开时）
查看 server 提供的工具和资源：在面板中选择 server 查看详情

启用或禁用是会话级别的操作，不会删除配置。重启 Claude Code 后，之前禁用的 server 会恢复启用状态。

把 Claude Code 自己暴露为 MCP server

claude mcp serve 命令把 Claude Code 自身启动为一个 MCP server，让其他 MCP 客户端（比如 IDE、其他 AI 工具）能调用它的工具：

# 启动 Claude Code MCP server
claude mcp serve

# 带调试信息
claude mcp serve --debug

# 详细输出
claude mcp serve --verbose

这在你想把 Claude Code 的文件操作、搜索、代码编辑等能力暴露给外部工具时很有用。

MCP server 连接了但工具看不到？排查要点

接入 MCP server 后，如果 Claude Code 似乎"不知道"新工具的存在，可能有以下原因：

server 启动失败：用 claude mcp list 检查 server 状态。stdio 类型的 server 如果命令路径不对或依赖缺失，会静默失败。
工具是延迟加载的：非核心工具（包括所有 MCP 工具）默认不会全部加载到上下文。Claude Code 使用 SearchExtraTools 机制，按需搜索和加载延迟工具。当你的请求需要用到 MCP 工具时，它会自动搜索并加载。
OAuth 认证未完成：需要 OAuth 的 HTTP/SSE server 如果认证未通过，工具虽然能被发现但调用会失败。
scope 不对：claude mcp add -s local 添加的 server 只在当前项目目录生效。切换到其他目录后该 server 不可用。

自己写一个 MCP server 的最小骨架

如果你找不到现成的 MCP server 来满足需求，可以自己写一个。核心步骤是：

使用 MCP SDK 创建一个 Server 实例
注册工具（ListTools + CallTool）
通过 stdio 或 HTTP 暴露服务

下面是一个最简单的 stdio MCP server（TypeScript，使用官方 @modelcontextprotocol/sdk）：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "my-mcp-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_weather",
      description: "Get the current weather for a city",
      inputSchema: {
        type: "object",
        properties: {
          city: { type: "string", description: "City name" },
        },
        required: ["city"],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { city } = request.params.arguments as { city: string };
  return {
    content: [{ type: "text", text: `Weather in ${city}: sunny, 22C` }],
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);

写好后注册到 Claude Code：

claude mcp add weather-server -- npx tsx my-mcp-server.ts

接下来在对话里让 Claude Code "查询北京的天气"，它就会自动调用你的 get_weather 工具。

内置 MCP 能力：Computer Use、Chrome 控制、语音输入

除了接入外部 MCP server，Claude Code 本身也提供了几个内置的 MCP 功能，覆盖屏幕控制、浏览器操作和语音输入。

Computer Use（屏幕控制）

通过 --computer-use-mcp 启动参数加载，提供截屏、键鼠控制和应用管理能力。支持 macOS、Windows、Linux 三大桌面平台，共 38 个工具。

claude --computer-use-mcp

启用后，Claude Code 可以看到你的屏幕、模拟鼠标键盘操作、管理应用窗口。比如你可以说"打开系统设置，把亮度调到 80%"，它会截图、识别界面、操作完成。详见 Computer Use 文档。

Chrome 浏览器控制

通过 --chrome-native-host 或 --claude-in-chrome-mcp 启动参数加载。提供两种方案：

Chrome Use MCP（社区开源）：通过 MCP 扩展接入，适合自托管场景
Claude in Chrome（原生集成）：Anthropic 官方扩展，提供完整能力（截图、网络监控、JS 执行等）

详见 Chrome 控制文档。

语音输入

通过 FEATURE_VOICE_MODE=1 启用，支持 Push-to-Talk 语音输入。长按空格键录音，释放后自动转录并发送。支持 Anthropic STT 和豆包 ASR 两种后端。

FEATURE_VOICE_MODE=1 claude

在对话中用 /voice 切换语音模式，/voice doubao 切换到豆包后端。详见 Voice Mode 文档。

插件系统：安装和管理社区插件

插件（Plugin）是在 Claude Code 中扩展功能的另一种方式。与 MCP server 不同，插件可以包含工具、命令、设置项等多种能力，更像一个"功能包"。

浏览和安装插件

在 REPL 中输入 /plugin（或 /plugins、/marketplace）打开插件管理界面。你也可以用命令行子操作：

# 打开插件菜单
/plugin

# 安装插件
/plugin install plugin-name

# 从指定 marketplace 安装
/plugin install plugin-name@marketplace-url

# 管理已安装的插件
/plugin manage

# 启用/禁用/卸载
/plugin enable plugin-name
/plugin disable plugin-name
/plugin uninstall plugin-name

插件市场

插件通过 marketplace 分发。Claude Code 支持管理多个 marketplace 来源：

# 添加一个 marketplace
/plugin marketplace add https://my-marketplace.example.com/registry.json

# 列出已添加的 marketplace
/plugin marketplace list

# 更新 marketplace 索引
/plugin marketplace update

验证插件

安装前可以验证插件的完整性：

/plugin validate path/to/plugin

插件 vs MCP server

两者的界限有时模糊，但大致可以这样区分：

维度	MCP Server	插件
通信方式	标准协议（stdio/SSE/HTTP）	直接集成到 Claude Code
包含内容	工具和资源	工具 + 命令 + 设置 + UI 组件
来源	任何实现了 MCP 的程序	Claude Code 插件市场
管理方式	`claude mcp add/list/remove`	`/plugin install/manage`

简单来说：MCP server 适合对接外部服务，插件适合扩展 Claude Code 自身的行为。

Skill 是什么？

Skill 是一段 Markdown 文本，定义了 Claude Code 在特定场景下应该怎么行动。它不是"可执行代码"，而是一份结构化的行为指南，被 Claude Code 读取后影响它的决策和操作方式。

你可以把 Skill 理解为给 Claude Code 的一份"操作手册"：告诉它在遇到特定类型任务时，应该遵循什么步骤、用什么工具、注意什么事项。

查看可用 Skill

在 REPL 中输入 /skills 打开 Skill 列表面板。你会看到所有可用的 Skill 及其简要描述。每个 Skill 有一个名称和触发条件（whenToUse），Claude Code 会根据对话上下文自动匹配最相关的 Skill。

Skill Store（远程 Skill 市场）

/skill-store 命令打开远程 Skill 市场，可以浏览和安装社区发布的 Skill。它需要 Anthropic API Key 或 workspace API key：

# 打开 Skill Store
/skill-store

# 列出可用 Skill
/skill-store list

# 查看某个 Skill 的详情
/skill-store get skill-id

# 查看版本历史
/skill-store versions skill-id

# 安装 Skill
/skill-store install skill-id

/skill-store 也叫 /ss 或 /cloud-skills，三个别名指向同一个命令。

`/skills` 与 `/skill-store` 的区别

命令	作用	数据来源
`/skills`	查看当前会话可用的所有 Skill（本地 + 远程 + 内置）	本地 `.claude/skills/` 目录 + 内置 Skill
`/skill-store`	浏览和安装远程社区的 Skill	Anthropic Skill 市场（需 API Key）

简单说：/skills 看你"有什么"，/skill-store 去"买新的"。

写一个自己的 Skill 并复用

自定义 Skill 是 Markdown 文件，放在 .claude/skills/ 目录下（项目级）或 ~/.claude/skills/（用户级）。

Skill 文件结构

一个 Skill 文件就是一份结构化的 Markdown：

---
name: my-code-review
description: Review code changes with security and performance focus
---

# Code Review Skill

When asked to review code, follow these steps:

1. Read the changed files using the Read tool
2. Check for common security issues (injection, auth bypass, data leaks)
3. Check for performance anti-patterns (N+1 queries, unnecessary allocations)
4. Verify error handling is complete
5. Report findings in a structured table format

把这个文件保存为 .claude/skills/my-code-review.md 后，Claude Code 在处理代码审查请求时就会参考这个 Skill 的指导。

Skill 搜索与自动匹配

启用 Skill Search（/skill-search start）后，Claude Code 会在每轮对话中自动搜索并加载与当前任务最相关的 Skill。搜索基于 TF-IDF 向量余弦相似度算法，支持英文词干化和中文 bi-gram 分词。

/skill-search start   # 启用自动匹配
/skill-search stop    # 禁用自动匹配
/skill-search status  # 查看当前状态

启用后，Skill Search 会索引 .claude/skills/ 和 ~/.claude/skills/ 下的所有 Markdown 文件，根据对话内容自动匹配并注入相关 Skill 指导。

延迟工具加载：SearchExtraTools 与 ExecuteExtraTools

Claude Code 的工具系统采用延迟加载策略。核心工具（Read、Edit、Write、Bash、Glob、Grep 等 38 个）始终可用，其余工具（包括所有 MCP 工具）需要按需发现和加载。

当你让 Claude Code 执行一个需要非核心工具的操作时，它会自动完成两步：

SearchExtraTools -- 搜索并发现需要的工具
ExecuteExtraTool -- 加载并执行发现的工具

这个过程对用户完全透明。比如你说"帮我创建一个定时任务，每 5 分钟检查部署状态"，Claude Code 会自动搜索 CronCreate 工具，然后执行它。你不需要手动触发任何操作。

下一步

想让 Claude Code 自动执行多步任务，看第六章：子代理、Plan 模式、Task 系统
想省钱和优化性能，看第九章：穷鬼模式、缓存、Hooks、配置文件
遇到 MCP server 连接问题，看第十章：可观测性与排错

14 KiB Raw Blame History Unescape Escape