使用说明

MCP脚手架

一个命令行实用程序，用于管理Claude Code中不同作用域的模型上下文协议（MCP）服务器配置，具有复制、移动和备份配置的增强功能。

安装

# Install from PyPI (future)
pip install mcp-scaffold

# Install from source
git clone <repository>
cd mcp-scaffold
pip install -e .

概述

MCP脚手架通过提供以下内容解决了Claude Code内置MCP管理的局限性：

范围可见性：清楚地看到每个MCP服务器配置在哪个范围内
安全操作：修改前自动备份配置文件
柔性管理：在作用域之间复制或移动服务器
团队协作：MCP配置的轻松共享和同步
项目迁移：简化了新项目和团队成员的设置

问题陈述

Claude Code目前的MCP管理有几个局限性：

claude mcp list 不显示在哪些范围服务器中配置
没有内置的方法在作用域之间复制服务器（只能通过手动重新配置移动）
修改配置文件时没有备份机制
难以跨项目组织和迁移MCP服务器
对分层配置系统的可见性有限

特性

核心功能

列出具有作用域信息的服务器 -增强的列表，准确显示每个服务器所处的范围
在作用域之间复制服务器 -跨本地、项目和用户范围复制服务器配置
在作用域之间移动服务器 -从源范围中删除时传输服务器
自动备份 -在任何配置更改之前创建带时间戳的备份
范围感知操作 -理解并尊重Claude Code的作用域层次结构
导入/导出配置 -共享和备份服务器配置

高级功能

批量操作 -一次复制/移动多个服务器
模板管理 -保存并应用常用服务器配置
项目初始化 -使用标准MCP服务器设置新项目
团队同步 -跨团队成员同步项目范围的服务器
配置差异 -比较不同范围的配置

配置文件位置

MCP脚手架使用Claude Code的三个配置范围：

用户范围: ~/.claude.json -适用于所有项目
项目范围: .mcp.json -通过版本控制与团队共享
本地范围: .claude.json （在当前目录中）-特定于项目的用户设置

范围优先级

当同一服务器存在于多个作用域中时：

本地覆盖项目和用户
项目覆盖用户
用户是退路吗

命令参考

基本命令

# List all servers with scope information
mcp-scaffold list

# List servers organized by scope
mcp-scaffold list --by-scope

# List servers in a specific scope
mcp-scaffold list --scope user|project|local

服务器管理

# Copy server to another scope
mcp-scaffold copy <server-name> --from <source-scope> --to <target-scope>

# Move server to another scope
mcp-scaffold move <server-name> --from <source-scope> --to <target-scope>

# Copy all servers from one scope to another
mcp-scaffold copy-all --from <source-scope> --to <target-scope>

# Remove server from specific scope
mcp-scaffold remove <server-name> --scope <scope>

备份操作

# Create manual backup of all configurations
mcp-scaffold backup create

# Restore from backup
mcp-scaffold backup restore --backup <backup-timestamp>

# List available backups
mcp-scaffold backup list

# Clean old backups (keep last N)
mcp-scaffold backup clean --keep 10

导入/导出

# Export servers from a scope
mcp-scaffold export --scope <scope> --output <file.json>

# Import servers to a scope
mcp-scaffold import --scope <scope> --input <file.json> [--merge]

# Export all configurations
mcp-scaffold export-all --output <directory>

备份策略

所有配置修改都会自动创建带时间戳的备份：

~/.mcp-scaffold/backups/
├── user/
│   └── .claude.json.2025-08-07_14-30-15.bak
├── project/
│   └── .mcp.json.2025-08-07_14-25-10.bak
└── local/
    └── .claude.json.2025-08-07_14-30-15.bak

为以下对象创建自动备份：

copy -修改目标范围之前
move -修改目标范围之前
copy-all -修改目标范围之前
remove -从范围中删除之前
import -导入范围之前

示例使用场景

场景1：建立一个新项目

# Copy essential servers from user scope to project scope
mcp-scaffold copy postgres --from user --to project
mcp-scaffold copy github --from user --to project

# Or copy all at once
mcp-scaffold copy-all --from user --to project

场景2：团队协作

# Export project servers for team sharing
mcp-scaffold export --scope project --output team-servers.json

# Team member imports the servers
mcp-scaffold import --scope project --input team-servers.json --merge

场景3：个人工具组织

# Move personal development tools to user scope
mcp-scaffold move sequential-thinking --from local --to user
mcp-scaffold move puppeteer --from local --to user

# List to verify organization
mcp-scaffold list --by-scope

场景4：安全实验

# Backup before making changes
mcp-scaffold backup create

# Copy production server for testing
mcp-scaffold copy postgres-prod --from project --to local
# Modify local copy for testing...

# Restore if needed
mcp-scaffold backup restore --backup 2025-08-07_14-30-15

错误处理

备份失败 -如果备份创建失败，操作将中止
配置验证 -保存前验证JSON结构
范围冲突 -清除服务器名称冲突的错误消息
文件权限 -优雅地处理只读或拒绝权限的情况
部分操作 -通过备份恢复提供回滚支持

成功标准

易用性 -常见操作需要1-2个命令
安全 -自动备份不会导致数据丢失
清晰度 -始终明确每个服务器所处的范围
团队工作流程 -共享项目上的无缝协作
可靠性 -强大的错误处理和恢复

贡献

看 docs/architecture.md 了解技术实施细节。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。