mcpField
M
mcp-management

mcp-management

github.com/laurigatesAgent 工作流5936 次安装2 天前更新
代码仓库

关于 mcp-management

mcp-management 是一项用于管理 Claude Code 项目中 MCP 服务的技能，介绍运行时控制、远程服务 OAuth、动态工具发现、配置范围和故障排查。

主要功能

  1. 01运行时查看与控制服务
  2. 02远程服务的 OAuth 2.1
  3. 03动态发现工具与资源
  4. 04项目、用户和插件级配置
  5. 05连接与 OAuth 故障排查

适用场景

  1. 01查看已配置服务并启用或停用
  2. 02配置远程 MCP 服务的 OAuth 访问
  3. 03服务能力变化时刷新工具列表
  4. 04诊断连接和授权问题

MCP 相关

该技能介绍在 Claude Code 中配置和运行 MCP 服务，包括本地 stdio 与远程 HTTP+SSE 传输方式，并说明服务状态、OAuth 和动态发现机制。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/laurigates/claude-plugins --skill mcp-management

安装后在 Claude Code 中输入/mcp-management确认已加载。

附带文件REFERENCE.md

详细介绍

MCP 服务管理

关于如何按项目管理 Model Context Protocol（MCP）服务的专业知识，支持运行时管理、OAuth 远程服务和动态服务发现。

服务配置示例、OAuth 深入解析、动态发现详情、故障排查脚本和完整的配置模式示例，请参阅 REFERENCE.md。

何时使用此技能

在以下情况下使用此技能……在以下情况下改用 configure-mcp……
了解 MCP 架构和概念为新项目设置 .mcp.json
在运行时管理服务（启用/禁用）交互式安装新服务
设置 OAuth 远程 MCP 服务对 MCP 配置运行合规性检查
排查连接失败问题从注册表添加特定服务
实现 list_changed 动态发现生成项目标准报告

MCP 架构概述

MCP 通过两种传输类型将 Claude Code 连接到外部工具和数据源：

传输方式用途身份验证配置
Stdio（本地）通过 npx、bunx、uvx、go run 启动的基于命令的服务无需.mcp.json
HTTP+SSE（远程）托管在外部的基于 URL 的服务OAuth 2.1带有 url 字段的 .mcp.json

本地服务声明 command 和 args；远程服务声明 url 和 headers（包含 ${VAR_NAME} 令牌引用，绝不硬编码）。请参阅 REFERENCE.md → 服务配置示例。

运行时服务管理

/mcp 命令（Claude Code 2.1.50+）

无需编辑配置文件即可管理服务：

命令描述
/mcp列出所有已配置的 MCP 服务及其连接状态
/mcp enable <server>为当前会话启用服务
/mcp disable <server>为当前会话禁用服务（仅限当前会话）

注意：启用和禁用仅对当前会话生效。要永久更改，请编辑 .mcp.json。

检查服务状态
jq -r '.mcpServers | keys[]' .mcp.json   # List configured servers
jq '.mcpServers.context7' .mcp.json      # Verify a server's config

OAuth 远程服务（2.1.50+）

远程 HTTP+SSE 服务使用 OAuth 2.1：Claude Code 会从 /.well-known/oauth-authorization-server 发现元数据（按 URL 缓存），用户在浏览器中授权一次；当工具需要更高权限范围时，升级身份验证会再次提示用户。要刷新过期的 OAuth 配置，请先执行 /mcp disable，再对该服务执行 /mcp enable。完整流程、升级身份验证详情和缓存行为请参阅 REFERENCE.md → OAuth 支持。

动态工具发现（list_changed）

声明了 {"tools": {"listChanged": true}} 的服务会在其工具集发生变化时推送 notifications/tools/list_changed，Claude Code 会无需重启会话即可刷新该服务的工具——这对提供特定于项目上下文的工具的服务很有用。resources 和 prompts 也采用相同模式。订阅会自动进行；无需客户端配置。请参阅 REFERENCE.md → 动态工具发现。

故障排查

常见故障模式及相应的诊断脚本（服务无法连接、缺少环境变量、OAuth 问题、SDK MCP 竞态条件）请参阅 REFERENCE.md → 故障排查脚本。 OAuth 快速排查：

症状可能原因操作
授权提示反复出现令牌未持久化检查令牌存储权限
升级身份验证陷入循环权限范围不匹配撤销授权并重新授权
发现失败服务已停机或 URL 错误验证服务 URL 和连接情况
缓存过期服务更改了 OAuth 配置禁用并重新启用服务以刷新

配置模式

三种作用域，每种都在 REFERENCE.md → 配置模式 中提供了 .mcp.json / settings.json / plugin.json 示例：

  • 项目级（推荐）——在项目根目录放置 .mcp.json；个人配置可将其加入 .gitignore，团队配置则可纳入版本控制。
  • 用户级（个人）——使用 ~/.claude/settings.json 配置随处可用的服务。
  • 插件级——在 plugin.json 中声明（或通过 "mcpServers": "./.mcp.json" 引用）。
添加后的审批关卡（项目级）

新添加的项目 .mcp.json 服务需要用户一次性审批后，其工具才能在当前会话中调用——这是预期行为，并非错误。写入配置后，claude mcp list 会立即将该服务显示为 ⏸ Pending approval (run 'claude' to approve)，在用户通过 /mcp 命令批准或重启 CLI 会话之前，该服务都无法调用——这两项操作只能由用户执行，Agent 无法代劳。因此，写入项目 .mcp.json 条目后，应主动告知用户需要进行一次性审批（通过 /mcp 或重启会话），新服务的工具才会变为可用，不要等到检查状态时发现审批关卡后再在流程中途询问。

Agent 式优化

上下文命令
快速检查状态jq -c '.mcpServers | keys' .mcp.json 2>/dev/null
验证 JSONjq empty .mcp.json 2>&1
列出所需环境变量jq -r '.mcpServers[] | .env // {} | keys[]' .mcp.json 2>/dev/null | sort -u
检查特定服务jq -e '.mcpServers.context7' .mcp.json >/dev/null 2>&1 && echo "installed"
查找插件中的服务find . -name '.mcp.json' -maxdepth 2

快速参考

按传输方式划分的服务类型
类型使用场景示例
command（stdio）本地工具，无需身份验证bunx、npx、uvx、go run
url（HTTP+SSE）远程托管服务，需要 OAuthhttps://...
关键文件
文件用途
.mcp.json项目级 MCP 服务配置（可与团队共享）
~/.claude/settings.json用户级 MCP 服务配置（个人）
plugin.json插件级 MCP 服务声明

评论

支持 Markdown