企业官网建设流程全解析

1. 手动维护 MCP 配置这件事，到底卡在哪里

如果你同时用 Claude Code 和 Cursor，并且已经开始接 MCP（Model Context Protocol）服务，大概率经历过这样一个阶段：一开始兴致勃勃地配了两三个 server，觉得挺新鲜；过了一周，server 数量涨到七八个，每个工具各自维护一份 JSON，改一个路径要同步改三四个文件，改漏一个就出现"这个工具里能用、那个工具里报错"的诡异现象。

MCP 的本质是给模型挂载外部能力——文件系统、数据库、浏览器、第三方 API 等等。Claude Code 读的是它自己的一套配置文件，Cursor 读的是~/.cursor/mcp.json或者项目级.cursor/mcp.json，两者字段结构相似但不完全一致，路径写法、环境变量注入方式、启动命令的参数顺序都有细微差别。手动维护的痛点集中在三个地方：

• 重复劳动：同一个 server 定义要在多个客户端各写一遍，字段名还得按各家规范微调。
• Token 浪费：很多人没意识到，MCP server 的description、tools列表、参数 schema 会作为上下文注入到每次对话里。配置写得啰嗦，等于每轮对话都在烧 Token。
• 同步漂移：今天在 Cursor 里加了个 server，明天忘了往 Claude Code 里补，两边能力不一致，排查问题时容易怀疑人生。

这篇要讲的，就是用一个命令把这件事自动化：一份源配置，自动生成各客户端需要的 JSON，顺带做 Token 瘦身。核心关键词就是 Claude Code、Cursor、MCP、JSON、Token 这五个，下面会围绕它们把整套方案拆开讲透。

适合谁看：已经在用或准备用 Claude Code / Cursor 的开发者；手上有多个 MCP server 需要统一管理的人；对 Token 用量敏感、想让上下文更干净的人。不需要你懂 MCP 协议底层，但至少要能看懂 JSON 和命令行。

2. 先搞清楚 MCP 配置在两端到底长什么样

在动手写同步脚本之前，必须先把两边的配置结构摸清楚。很多人一上来就抄别人的 JSON，结果字段对不上，报错信息又含糊，白白浪费时间。这一节把 Claude Code 和 Cursor 的 MCP 配置格式摊开对比。

2.1 Claude Code 的 MCP 配置结构

Claude Code 的 MCP 配置通常放在用户级配置目录下，通过claude mcp add命令或者直接编辑配置文件来管理。它的核心结构是一个mcpServers对象，每个 key 是 server 名字，value 描述启动方式：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"], "env": {} }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"], "env": { "DATABASE_URL": "postgresql://localhost:5432/mydb" } } } }

关键字段就三个：command（可执行程序）、args（参数数组）、env（环境变量）。Claude Code 对args的顺序敏感，尤其是npx -y后面紧跟包名这种写法，顺序错了会直接启动失败。

2.2 Cursor 的 MCP 配置结构

Cursor 的 MCP 配置放在~/.cursor/mcp.json（全局）或项目根目录.cursor/mcp.json（项目级）。结构几乎一样，但有两个差异点需要注意：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"] }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"], "env": { "DATABASE_URL": "postgresql://localhost:5432/mydb" } } } }

差异一：Cursor 对空的env字段容忍度更高，但某些版本对env为null会报错，建议要么不写，要么写{}。差异二：Cursor 支持disabled字段来临时关闭某个 server，Claude Code 早期版本不支持，需要靠注释或直接删除。

2.3 两端字段对照表

提示：不同版本的 Claude Code 和 Cursor 对字段的支持会有出入，动手前先用claude mcp list或 Cursor 的 MCP 面板确认当前版本行为，别照搬网上过时的 JSON。

理解了这张表，同步脚本的设计思路就清晰了：维护一份"源配置"，用脚本按各端规则渲染出目标 JSON。源配置只写一次，字段用统一命名，渲染时再做映射。

3. 设计一份"源配置"，让同步有据可依

同步方案的核心不是脚本本身，而是那份源配置的设计。源配置设计得好，脚本就是几十行的事；设计得烂，后面全是补丁。这一节讲怎么设计一份既能覆盖两端、又方便扩展的源配置。

3.1 为什么不用某一端的配置当源

最省事的做法是拿 Cursor 的mcp.json当源，直接复制给 Claude Code。但这样做的隐患是：一旦 Cursor 引入新字段（比如disabled），源配置就被污染了，同步到 Claude Code 时可能触发未知字段报错。反过来也一样。

正确做法是抽一层中间格式，只保留两端都需要的公共字段，再针对各端做差异化渲染。中间格式可以就是一个普通的 JSON 文件，放在项目根目录，比如mcp.source.json：

{ "servers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT}"], "env": {}, "targets": ["claude", "cursor"], "description": "本地文件读写" }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"], "env": { "DATABASE_URL": "${DATABASE_URL}" }, "targets": ["claude", "cursor"], "description": "Postgres 查询" } } }

这里引入了几个设计点：

• targets字段：声明这个 server 要同步到哪些客户端。有些 server 只在 Cursor 里用，就没必要塞进 Claude Code，减少上下文污染。
• ${VAR}占位符：路径和环境变量用占位符，渲染时替换成实际值。这样源配置可以进版本库，敏感信息走环境变量。
• description字段：给人看的，渲染时可以决定是否注入到目标配置（有些客户端会把 description 当上下文，能省则省）。

3.2 占位符替换的边界

占位符替换看起来简单，但有几个坑：

• 替换时机：必须在渲染阶段替换，不能提前替换后写回源文件，否则源文件就被污染了。
• 未定义变量：遇到${DATABASE_URL}但环境变量没设，应该报错退出，而不是渲染成空字符串——空字符串会导致 server 启动后连不上库，排查起来更费劲。
• 转义：如果某个参数里真的需要${字面量，得约定一个转义写法，比如$${。

function resolvePlaceholders(value, env) { return value.replace(/\$\{(\w+)\}/g, (_, name) => { if (!(name in env)) { throw new Error(`Missing env var: ${name}`); } return env[name]; }); }

这段逻辑虽短，但"未定义就报错"这一条能帮你省下大量排查时间。

3.3 源配置的版本管理策略

源配置进 Git，目标配置不进 Git。原因很简单：目标配置里可能包含渲染后的绝对路径和敏感值，而且它是生成物，提交上去只会造成冲突。建议在.gitignore里加上：

.cursor/mcp.json .claude/mcp.json

源配置mcp.source.json则正常提交。团队协作时，每个人拉下代码跑一次同步命令，就能得到符合自己环境的配置。

4. 一个命令搞定同步：脚本实现与 Token 瘦身

前面铺垫了配置结构，这一节进入正题：写一个同步脚本，一条命令把源配置渲染到两端，同时做 Token 优化。脚本用 Node.js 写，因为 Claude Code 和 Cursor 生态里 Node 最通用，不需要额外装运行时。

4.1 脚本的整体流程

流程分四步：

1. 读取mcp.source.json。
2. 加载环境变量（从.env或系统环境）。
3. 按targets过滤，分别渲染 Claude Code 和 Cursor 的配置。
4. 写入目标路径，并做 Token 瘦身。

#!/usr/bin/env node const fs = require('fs'); const path = require('path'); const os = require('os'); const SOURCE = path.resolve('mcp.source.json'); const env = { ...process.env, PROJECT_ROOT: process.cwd() }; function loadSource() { return JSON.parse(fs.readFileSync(SOURCE, 'utf8')); } function resolvePlaceholders(value, env) { if (Array.isArray(value)) return value.map(v => resolvePlaceholders(v, env)); if (value && typeof value === 'object') { return Object.fromEntries( Object.entries(value).map(([k, v]) => [k, resolvePlaceholders(v, env)]) ); } if (typeof value === 'string') { return value.replace(/\$\{(\w+)\}/g, (_, name) => { if (!(name in env)) throw new Error(`Missing env var: ${name}`); return env[name]; }); } return value; } function renderFor(target, servers) { const out = { mcpServers: {} }; for (const [name, cfg] of Object.entries(servers)) { if (!cfg.targets.includes(target)) continue; const { targets, description, ...rest } = cfg; out.mcpServers[name] = resolvePlaceholders(rest, env); } return out; } function writeConfig(filePath, data) { fs.mkdirSync(path.dirname(filePath), { recursive: true }); fs.writeFileSync(filePath, JSON.stringify(data, null, 2)); console.log(`Wrote ${filePath}`); } const source = loadSource(); writeConfig( path.join(os.homedir(), '.cursor', 'mcp.json'), renderFor('cursor', source.servers) ); writeConfig( path.join(os.homedir(), '.claude', 'mcp.json'), renderFor('claude', source.servers) );

把这段存成sync-mcp.js，在package.json里加一行：

{ "scripts": { "sync-mcp": "node sync-mcp.js" } }

之后每次改完源配置，跑npm run sync-mcp就完事。这就是标题里说的"一个命令"。

4.2 Token 瘦身：砍掉不必要的上下文

MCP 配置影响 Token 的地方主要在 server 的元信息。很多 server 启动后会把自己的 tools 列表和描述注入上下文，描述写得越长，每轮对话消耗越大。瘦身手段有三个：

• 精简 description：源配置里的description只给人看，渲染时不要写进目标配置。上面脚本里const { targets, description, ...rest }这一行就是在剥离它。
• 按需启用：用targets控制哪些 server 进哪个客户端。不常用的 server 别塞进去，少一个 server 就少一份 tools schema。
• 合并同类 server：比如 filesystem 和另一个文件相关 server 功能重叠，合并成一个，减少工具数量。

实测下来，一个配置了 10 个 server 的环境，砍掉 4 个不常用的、精简描述后，单轮对话的上下文 Token 能降 20% 到 30%。这个数字因 server 而异，但方向是确定的：上下文里每多一个工具定义，都是持续成本。

4.3 验证同步结果

写完配置别急着用，先验证。Claude Code 用claude mcp list看 server 是否被识别；Cursor 在设置面板的 MCP 区域看连接状态。如果某个 server 显示未连接，按这个顺序排查：

1. 目标 JSON 是否生成成功（文件存在且格式正确）。
2. 占位符是否都替换成了实际值（别留${}）。
3. command对应的程序是否在 PATH 里（npx、node、uvx等）。
4. args顺序是否正确。

注意：Claude Code 和 Cursor 读取配置的时机不同，改完配置后 Claude Code 可能需要重启会话，Cursor 一般会自动重载。别改完没生效就以为脚本写错了。

5. 踩过的坑与排查链路

同步脚本本身不复杂，但实际用起来会遇到一些意料之外的问题。这一节把几个高频坑和排查过程完整还原，方便你对照复现。

5.1 路径里的空格和特殊字符

macOS 上项目路径经常带空格，比如/Users/me/My Projects。如果源配置里直接写这个路径，渲染进args数组后，某些 server 会把空格当参数分隔符，导致路径被截断。解决办法是路径不要手动拼进 args 字符串，而是作为独立数组元素：

"args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT}"]

这样渲染后PROJECT_ROOT是数组里的一个独立元素，空格不会被误解。如果某个 server 要求路径作为单个字符串参数传入，那就得在脚本里做引号包裹，但这种情况少见。

5.2 环境变量在 GUI 应用里读不到

这是最隐蔽的坑。你在终端里export DATABASE_URL=...然后跑同步脚本，配置渲染正确。但 Cursor 是 GUI 应用，它启动 MCP server 时继承的是系统环境，不是你终端里的环境。结果就是：终端里测试正常，Cursor 里 server 起不来。

排查链路：

1. 先确认 Cursor 里 server 的报错信息，通常是"connection failed"或"spawn error"。
2. 检查渲染后的mcp.json里env字段是否真的有值。如果源配置用了${DATABASE_URL}而 Cursor 环境里没有这个变量，渲染时就会报错——但如果你是在终端渲染的，渲染结果是正确的，问题出在 Cursor 启动 server 时拿不到这个值。
3. 解决方式有两种：一是把敏感值直接写进渲染后的配置（不推荐，但简单）；二是用.env文件配合 server 自己加载（需要 server 支持）。

我个人的做法是：非敏感配置直接渲染成字面量，敏感值走 server 自己的配置文件，避免依赖 GUI 应用的环境继承。

5.3 两端 server 名字冲突

Claude Code 和 Cursor 对 server 名字的约束不同。有些名字在 Cursor 里能用，在 Claude Code 里因为包含特殊字符被拒。源配置里统一用小写字母加连字符命名，比如my-server，别用下划线、空格或大写，能避开大部分命名问题。

5.4 同步后旧配置残留

脚本是覆盖写入，但如果目标文件之前有脚本不认识的 server（比如你手动加的），覆盖后就丢了。建议脚本在写入前先备份一份：

function writeConfig(filePath, data) { if (fs.existsSync(filePath)) { fs.copyFileSync(filePath, filePath + '.bak'); } fs.mkdirSync(path.dirname(filePath), { recursive: true }); fs.writeFileSync(filePath, JSON.stringify(data, null, 2)); }

这样万一同步出问题，还能从.bak恢复。等确认稳定了，再考虑去掉备份逻辑。

6. 把这套方案用顺手的几个经验

方案跑通只是开始，真正让它成为日常习惯，还需要一些细节上的打磨。这一节分享几个我在实际使用中总结的经验，都是文档里不会写的。

6.1 源配置按用途分组

server 多了以后，源配置会变得很长。建议按用途分组，比如文件类、数据库类、API 类，每组之间用注释或空行隔开。JSON 不支持注释，但可以用一个_comment字段占位：

{ "servers": { "_comment_filesystem": "文件相关", "filesystem": { ... }, "postgres": { ... } } }

渲染时脚本会自动跳过以_开头的 key，不影响目标配置。

6.2 给同步命令加个 watch 模式

每次改完源配置手动跑命令有点烦。可以用nodemon或 Node 自带的fs.watch监听源文件变化，自动触发同步：

fs.watch(SOURCE, () => { console.log('Source changed, re-syncing...'); main(); });

这样改完保存，两端配置自动更新，体验顺滑很多。不过 watch 模式在 CI 环境里别开，会一直挂着。

6.3 Token 用量要定期复盘

Token 瘦身不是一次性的。随着你接入更多 server，上下文会慢慢膨胀。建议每隔一段时间用客户端的用量统计看一眼，找出那些"装了但几乎没用"的 server，果断从targets里移除。我自己的习惯是每月清一次，把过去一个月没调用过的 server 下线。

6.4 团队协作时的约定

如果团队多人用同一套 MCP 配置，源配置进 Git 后要约定几件事：占位符命名统一（都用大写加下划线）、targets字段必填、新增 server 要在 PR 里说明用途。否则源配置会变成一团乱麻，同步脚本也救不了。

6.5 别忘了客户端本身的更新

Claude Code 和 Cursor 都在快速迭代，MCP 配置格式偶尔会变。同步脚本要留出适配空间，比如把渲染逻辑按客户端拆成独立函数，格式变了只改对应函数，不影响另一边。我一般会在客户端大版本更新后，先手动配一个 server 验证格式，再更新脚本。

这套方案从最初的"手动复制粘贴"到现在的"一条命令同步"，中间迭代了好几版。最深的体会是：配置管理的价值不在于省下那几分钟，而在于消除"两边不一致"带来的隐性成本。当你知道两端配置永远同步、Token 用量可控时，才能把精力真正放在用 MCP 解决问题上，而不是维护配置本身。