1. 项目概述一个为AI开发者设计的MCP服务器管理器如果你和我一样每天都在Cursor、VS Code和Windsurf这几个AI驱动的编辑器之间切换同时又在捣鼓各种Model Context ProtocolMCP服务器来扩展AI助手的能力那你肯定也经历过这种混乱。每个编辑器都有自己的配置文件路径、不同的JSON结构、五花八门的传输协议stdio、SSE、HTTP管理起来简直是一场噩梦。我经常在.cursor/mcp.json里配好了GitHub服务器转头到VS Code里又要对着settings.json再配一遍环境变量、命令参数稍有差池AI助手就“罢工”了。这就是我开发Raycast MCP Server Manager的初衷。它不是什么庞大的企业级工具而是一个纯粹的效率工具——一个Raycast扩展让你能在一个统一的界面里管理所有编辑器目前支持Cursor、VS Code、Windsurf的MCP服务器配置。想象一下不用再手动翻找和编辑那些散落在各处的JSON文件通过Raycast的命令面板就能完成服务器的增删改查、连接测试和快速切换。这个工具解决的核心痛点就是配置管理的碎片化它把原本需要跨多个编辑器、记忆不同路径和语法的操作统一成了一个直观的CRUD创建、读取、更新、删除界面。它适合谁用首先是像我这样的全栈或AI应用开发者尤其是那些深度依赖Cursor或Windsurf进行AI辅助编程的同行。其次是MCP服务器的开发者或爱好者你需要频繁地测试、部署不同的服务器到不同环境。最后任何希望提升AI编辑器使用效率厌倦了重复配置工作的人都能从中受益。这个工具不改变MCP协议本身它只是让协议的使用和管理变得无比顺畅。2. 核心功能与设计思路拆解2.1 为什么选择Raycast作为平台在决定开发这个工具时我评估过几种方案独立的桌面应用、VS Code插件、或者命令行工具。最终选择Raycast扩展是基于几个非常实际的考量。首先Raycast的定位是“生产力启动器”它的核心交互模式是通过快捷键呼出命令面板输入关键词执行操作。这与MCP服务器管理的场景完美契合我通常在编码时突然需要启用或禁用一个服务器或者快速检查某个配置是否生效。我不希望离开当前的编辑器窗口去打开另一个应用或终端。Raycast的全局呼出特性默认CmdSpace让我能在任何应用、任何窗口状态下瞬间调出管理器进行操作操作完成后界面自动消失流程极其流畅对心流状态的打断最小。其次Raycast提供了成熟且优雅的扩展开发框架。它基于React和TypeScript这对于前端开发者来说几乎没有学习成本。其UI组件库ActionPanel、Form、Detail等已经为工具类应用设计好了最佳实践我能快速搭建出美观、一致且符合macOS设计规范的界面。更重要的是Raycast内置了文件系统访问、剪贴板、网络请求等常用API并且封装得很好让我能专注于业务逻辑即解析和操作不同编辑器的配置文件而不是底层系统交互的细枝末节。最后生态与分发优势。Raycast拥有一个活跃的扩展商店用户安装扩展就像在App Store下载应用一样简单搜索、点击安装。这极大地降低了用户的使用门槛。相比之下一个独立的CLI工具需要用户处理环境变量、PATH配置一个VS Code插件则只能管理VS Code自身的配置无法触及Cursor或Windsurf。Raycast作为一个中立、全局的平台恰好成为了连接这几个“数据孤岛”各编辑器的配置文件的理想桥梁。2.2 统一抽象层化解编辑器差异的策略MCP协议本身是统一的但各个编辑器的实现却各有“个性”。我的核心设计思路是在工具内部构建一个统一的“服务器配置”数据模型然后为每个支持的编辑器编写一个“适配器”Adapter。这个统一的数据模型包含了管理一个MCP服务器所需的所有信息基础信息name服务器名称、editor所属编辑器。传输配置transport协议类型如stdio/sse/http、command/args针对stdio、url/serverUrl针对SSE/HTTP。环境变量env对象用于存储API密钥等敏感信息。元数据configPath配置文件绝对路径、isProtected是否受保护防止误删。而每个编辑器的“适配器”则负责两件事读取Read定位到该编辑器的配置文件全局或工作区解析其特定的JSON结构将原始配置“翻译”成我定义的统一数据模型。例如Cursor的配置在mcpServers对象下而VS Code可能嵌套在mcp.servers里适配器需要知道这些细节。写入Write接收统一数据模型再“翻译”回该编辑器特定的JSON结构并写回对应的配置文件。这样设计的好处是巨大的所有核心业务逻辑如列表展示、搜索过滤、添加/删除表单都只需要与这套统一模型打交道完全不用关心底层是Cursor还是VS Code。当需要支持一个新的编辑器时我只需要为它实现一个新的适配器核心功能代码几乎无需改动。这种“面向接口编程”的思想极大地提升了代码的可维护性和可扩展性。实操心得路径处理的坑不同操作系统macOS, Windows, Linux的配置文件路径完全不同。比如VS Code在macOS的全局配置在~/Library/Application Support/Code/User/settings.json而在Windows则在%APPDATA%\Code\User\settings.json。我的适配器在初始化时必须首先通过Node.js的os模块和path模块来动态判断并构建正确的路径。一个常见的错误是硬编码了macOS的路径导致工具在其他系统上完全失效。我的做法是预先定义好各系统路径的映射表运行时根据process.platform进行选择。3. 核心功能实现与实操要点3.1 服务器列表与搜索高效浏览的基石“List MCP Servers”和“Search MCP Servers”是两个最常用的功能。实现它们的关键在于性能和信息密度。性能方面我不能在用户每次打开列表时都去同步读取所有编辑器的所有配置文件。磁盘I/O是昂贵的尤其是当用户工作区下有多个嵌套的.cursor或.vscode文件夹时。我的策略是缓存结合惰性更新。启动Raycast扩展时我会异步预加载一次所有已知编辑器配置文件的路径和最后修改时间戳存入内存缓存。当用户执行“列出”命令时我首先检查缓存中各个文件的mtime修改时间。如果文件自上次缓存后未被修改就直接使用缓存的数据。只有当检测到文件被修改过或者用户手动触发刷新我提供了一个Refresh的Action才会重新读取并解析该文件。这个检查过程是并行的使用Promise.all以最大化利用现代CPU的多核能力确保列表弹出速度在毫秒级用户感知不到延迟。信息密度方面Raycast的List组件非常适合展示结构化数据。我为每个服务器条目设计了清晰的元信息展示主标题服务器名称name。副标题显示编辑器图标Cursor/VS Code/Windsurf和传输类型stdio/SSE/HTTP一眼就能区分。附件显示配置文件路径是全局配置还是工作区配置以及一个状态指示器例如对SSE/HTTP服务器我会尝试一个快速的HEAD请求来显示“在线”或“离线”对stdio服务器则标记为“本地”。快捷键我为每个条目绑定了CmdO直接打开配置文件CmdT测试连接CmdBackspace删除受保护的服务器此操作会被拦截并提示。搜索功能则基于Raycast内置的过滤能力。我不仅对服务器名称进行模糊匹配还将编辑器类型、传输协议甚至环境变量中的关键字段如API_KEY也纳入索引。这样用户搜索“github”时不仅能找到名为“github”的服务器也能找到环境变量里配置了GITHUB_TOKEN的服务器非常实用。3.2 添加服务器智能表单与配置生成“Add MCP Server”功能是整个工具交互最复杂的部分。我需要引导用户输入必要信息并最终生成正确的、符合目标编辑器语法的JSON配置。我的表单设计遵循了渐进式披露的原则第一步选择编辑器。用户首先选择目标编辑器Cursor, VS Code, Windsurf。这个选择会直接影响后续可用的选项。第二步配置服务器基础信息。输入服务器名称、选择传输类型stdio/SSE/HTTP。这里有一个关键细节当用户选择Windsurf且传输类型为SSE时表单上的标签会自动从“URL”变为“Server URL”因为Windsurf使用的是非标准的/sse类型和serverUrl字段。这个动态变化能有效防止用户填错。第三步根据传输类型动态渲染表单。如果选择stdio出现“Command”和“Args”输入框。Args是一个可添加多个条目的列表控件。如果选择SSE或HTTP出现“URL”输入框并附带一个“Test Connection”的按钮允许用户即时验证URL是否可达。第四步环境变量配置。这是一个键值对列表。对于VS Code我会特别说明其强大的${input:xxx}变量替换机制并引导用户如果需要使用此功能需先在VS Code的mcp.json中定义inputs部分我们的工具目前专注于服务器配置本身inputs的定义仍需手动编辑。第五步作用域选择。询问用户是将此配置添加到“全局”还是当前“工作区”。工具会根据用户当前在Finder中选中的文件夹通过Raycast API获取或默认的Home目录自动建议工作区配置文件的路径。表单填写完毕后点击提交背后的逻辑开始工作调用对应编辑器的适配器将表单数据统一模型转换为该编辑器的原生配置对象。读取目标配置文件如果不存在则创建。采用安全的深度合并策略将新的服务器配置合并到原有配置中。这里必须小心不能直接覆盖整个文件而要精准地修改mcpServers或servers下的特定属性。使用fs.writeFile配合JSON.stringify带2个空格缩进写回文件保证生成的文件格式美观、可读。最后显示一个成功提示并询问用户是否要立即“测试连接”或“打开配置文件”。注意事项JSON合并的陷阱直接使用Object.assign或展开运算符...进行合并是危险的因为这会浅合并。如果原有配置里某个服务器已经有复杂的嵌套env对象浅合并会导致旧的env被完全替换。我使用了lodash.merge库来进行深度合并它能递归地合并对象属性确保原有配置的其他部分毫发无损。这是保证工具稳定性的一个关键点。3.3 连接测试与错误处理“Test Connection”功能看似简单实则需要对不同传输协议实现不同的测试逻辑并且要有健壮的超时和错误处理。对于stdio服务器测试最为直接但也最危险。我的做法是绝不直接执行用户配置的命令。因为命令可能包含副作用比如启动一个长期运行的后台进程。我采用了一种“无害探测”法尝试执行command --version或command --help如果args的第一个元素看起来像是一个子命令则拼接上--help。同时必须设置一个很短的超时如2秒并使用spawn而非exec来避免shell注入风险。如果命令不存在或无法执行会捕获错误并给出友好提示如“命令 ‘python3’ 未找到请检查是否已安装并加入PATH”。对于SSE服务器发送一个HTTPGET请求到提供的URL并设置Accept: text/event-stream头部。我不需要等待事件流只需要确认服务器响应了正确的状态码通常是200和Content-Type: text/event-stream。这里同样需要设置超时5秒并处理网络错误、CORS错误等。对于HTTP服务器发送一个简单的POST请求到MCP的初始化端点通常是/或/initialize主体包含一个最小化的mcp/protocol初始化参数。检查是否返回200 OK及正确的JSON响应。对于Windsurf的/sse类型逻辑与SSE类似但URL路径必须正确。所有测试结果都会以清晰的方式反馈给用户绿色对勾加“连接成功”红色叉号加具体的错误信息如“连接超时5秒”、“收到无效的响应格式”或“服务器返回401未授权”。对于环境变量缺失导致的错误我会特别提示“请检查API_KEY等环境变量是否已正确配置”。3.4 服务器保护机制的实现“Server Protection”是一个防呆设计防止用户误删一些核心的、系统自带的或极其重要的MCP服务器。但必须清醒认识到这种保护仅限于本工具的UI层面。实现原理很简单我在代码里维护了一个protectedServerNames的数组默认包含了像mcp-server-time一个提供当前时间的官方示例服务器等。在“Remove MCP Server”命令的流程中当用户选择一个服务器并尝试删除时我会检查其名称是否在这个保护名单内。如果是受保护的服务器UI会拦截删除操作并弹出一个警告提示明确告知用户“这是一个受保护的系统服务器无法通过本工具删除。如需移除请直接编辑配置文件。” 同时在服务器列表的展示上受保护的服务器旁边会显示一个锁形图标并在详情中加以说明。我必须反复强调这个机制的局限性它只是一个UI层面的软保护。用户完全可以通过“View Raw Configs”功能直接编辑JSON文件或者用任何文本编辑器手动删除配置项。在文档和提示中我明确写明了“Don‘t rely on this if you’re editing configs directly. You break it, you own it.”如果你直接编辑配置文件别指望这个保护机制。搞砸了自己负责。这是一种对用户技术能力的尊重也是明确责任边界。4. 编辑器适配详解与配置实战4.1 Cursor适配聚焦stdio与自动管理Cursor是目前对MCP集成最深入、体验最流畅的AI编辑器之一。它的配置相对直观主要支持stdio和sse两种传输方式。配置文件位置全局配置~/.cursor/mcp.json。这里存放着你希望在所有Cursor项目中都可用的服务器比如公司内部的通用工具服务器。工作区配置项目根目录下的.cursor/mcp.json。这里配置的服务器仅对当前项目生效非常适合存放项目特定的API密钥或工具。配置结构解析 Cursor的配置是一个顶层mcpServers对象其每个属性名就是服务器名称。{ mcpServers: { github-explorer: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: ghp_... } }, weather-service: { command: python, args: [-m, my_weather_mcp], env: { OPENWEATHER_API_KEY: ... } }, remote-sse-server: { url: https://api.my-mcp-service.com/sse } } }实操要点与避坑指南stdio进程管理Cursor会自动启动和停止stdio服务器进程。这意味着你配置的command必须在系统的PATH中或者使用绝对路径。一个常见错误是使用像./venv/bin/python这样的相对路径这在全局配置中会失效。我的建议是对于Python项目在项目内的.cursor/mcp.json中配置时使用相对于项目根目录的路径对于全局工具确保命令全局可用或使用npx -y来运行npm包。环境变量安全env对象中的敏感信息会以明文形式存储在JSON文件中。虽然文件通常有用户级权限但这仍然存在风险。切勿将包含真实密钥的配置文件提交到公共Git仓库我个人的做法是将mcp.json添加到.gitignore然后提交一个mcp.json.example模板文件其中用占位符如YOUR_GITHUB_TOKEN替换真实密钥。SSE服务器的可访问性如果你配置的是远程SSE服务器确保其URL能从你的开发机器访问并且没有防火墙或CORS策略阻拦。Cursor内部会处理SSE连接。工具数量限制Cursor对单个服务器可提供的工具数量似乎有软性限制根据社区反馈大约在40个左右。如果你开发的MCP服务器工具非常多可能需要考虑拆分。4.2 VS Code适配强大的输入管理与灵活配置VS Code的MCP支持虽然较新从1.99版本开始预览但其设计非常专业尤其是安全的输入管理机制解决了密钥配置的一大痛点。配置文件位置与结构 VS Code提供了更大的灵活性。你可以在用户设置中配置也可以在项目工作区中配置。用户设置settings.json中的mcp.servers对象。不推荐在这里放敏感信息。工作区配置推荐在项目根目录创建.vscode/mcp.json。这是最佳实践因为它与项目绑定并且支持inputs定义。一个完整的.vscode/mcp.json示例{ // 1. 定义输入项用于安全地收集密钥 inputs: [ { id: github-pat, type: promptString, description: Enter your GitHub Personal Access Token, password: true // 输入内容会被隐藏 }, { id: openai-api-key, type: promptString, description: Your OpenAI API Key, password: true } ], // 2. 定义MCP服务器 servers: { github: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ${input:github-pat} // 引用上面定义的输入 } }, openai-completion: { type: sse, url: http://localhost:3000/sse, headers: { Authorization: Bearer ${input:openai-api-key} } }, local-filesystem: { type: stdio, command: python, args: [./local_scripts/filesystem_server.py] } } }VS Code适配器的核心挑战inputs的只读性inputs数组是VS Code特有的配置用于在UI中弹窗提示用户输入。Raycast MCP Server Manager不直接管理inputs。当我们的工具检测到用户为VS Code添加一个服务器并且其env中使用了${input:xxx}语法时我们会在保存后的提示信息中明确告知用户“此配置引用了输入变量‘xxx’。请确保在.vscode/mcp.json的inputs部分已正确定义该变量。” 我们无法、也不应该尝试通过Raycast来动态修改inputs因为这涉及到VS Code内部的安全输入流程。配置合并的复杂性VS Code的配置可能同时存在于settings.json和mcp.json中且settings.json本身结构复杂。我的适配器会优先查找并操作.vscode/mcp.json。如果不存在则尝试在用户或工作区的settings.json中找到mcp.servers进行修改。这要求适配器的代码有很好的容错性能够处理各种边界情况如文件不存在、JSON格式错误、目标属性不存在等。版本兼容性由于MCP支持在VS Code中尚处预览阶段不同小版本之间可能有变化。我的工具在读取VS Code配置时会首先检查其mcp对象的结构如果发现不认识的字段或格式会以保守的方式处理尽量不破坏原有配置并记录警告。4.3 Windsurf适配处理非标准传输类型Windsurf的集成方式与Cursor类似但有一个关键区别它对SSE传输使用了非标准的标识符。配置文件位置全局配置~/.codeium/windsurf/mcp_config.json工作区配置.windsurf/mcp.json关键差异/sse传输类型 在标准MCP或Cursor/VS Code中SSE传输的配置使用transport: sse和url: ...。 而在Windsurf中你必须使用{ mcpServers: { my-sse-server: { transport: /sse, // 注意这里的斜杠 serverUrl: https://example.com/your-endpoint/sse // 字段名也不同 } } }注意两点1)transport的值是/sse而非sse2) 连接地址的字段名是serverUrl而非url。这个差异很可能源于Windsurf内部实现的历史原因或特定设计。我们的工具如何应对 在Windsurf适配器的“读取”阶段当检测到transport为/sse时我会在统一数据模型内部将其标准化为sse同时记录下原始的serverUrl值。在“写入”阶段当需要为Windsurf生成配置时如果传输类型是sse我会自动将其转换回/sse并使用serverUrl字段。在用户界面上我们始终向用户展示标准的“SSE”选项和“URL”字段只是在背后默默完成转换。这保证了用户体验的一致性用户无需记忆Windsurf的特殊语法。其他注意事项Windsurf也有一个“插件商店”里面可能有一些预验证的MCP服务器。通过我们的工具手动添加的服务器与从商店安装的服务器是共存的都会出现在Windsurf的MCP服务器列表中。和Cursor一样修改Windsurf的配置文件后通常需要重启Windsurf或在其界面内手动刷新更改才会生效。我们的工具在保存配置后可以给出这样的提示。5. 开发、调试与贡献指南5.1 本地开发环境搭建如果你想自己修改或扩展这个Raycast扩展以下是完整的本地开发流程环境准备# 确保已安装Node.js (18) 和 npm node --version npm --version # 全局安装Raycast开发工具如果尚未安装 npm install -g raycast/api克隆项目并安装依赖git clone https://github.com/rmncldyo/raycast-mcp-server-manager.git cd raycast-mcp-server-manager npm install启动开发模式npm run dev执行这个命令后Raycast会自动打开并在扩展列表中加载你正在开发的这个本地版本通常带有一个“小锤子”开发图标。你对代码的任何修改保存后都会在Raycast中热重载可以立即测试效果。项目结构速览raycast-mcp-server-manager/ ├── src/ │ ├── commands/ # Raycast命令入口文件 │ │ ├── list-servers.ts │ │ ├── add-server.ts │ │ └── ... │ ├── lib/ │ │ ├── adapters/ # 编辑器适配器 │ │ │ ├── cursor-adapter.ts │ │ │ ├── vscode-adapter.ts │ │ │ └── windsurf-adapter.ts │ │ ├── models/ # 统一数据模型定义 │ │ ├── utils/ # 工具函数路径解析、网络测试等 │ │ └── constants.ts # 常量如保护服务器列表 │ └── types.ts # TypeScript类型定义 ├── assets/ # 图标等静态资源 ├── package.json ├── tsconfig.json └── README.md5.2 调试技巧与常见问题排查开发过程中你肯定会遇到各种问题。以下是我积累的一些调试经验查看Raycast开发者日志在开发模式下Raycast会输出详细的日志到终端。这是排查问题的第一站。任何未捕获的异常、网络请求失败、文件读写错误都会在这里打印出来。使用console.log是的在TypeScript里用console.log。Raycast的运行时环境会将这些日志输出到上述的开发者终端。这对于跟踪变量状态、函数执行流程非常有效。记得在提交代码前清理掉不必要的log。模拟不同编辑器环境你的机器上可能只安装了Cursor。要测试VS Code或Windsurf的适配器一个技巧是创建模拟的配置文件。在对应的全局或临时目录创建测试用的mcp.json或settings.json然后在适配器的路径解析逻辑中临时修改为指向这些测试文件。这样你就能在不安装实际编辑器的情况下验证读写逻辑是否正确。处理权限问题在macOS上特别是涉及~/Library/Application Support目录时可能会遇到权限错误。确保你的开发环境有读写这些目录的权限。有时VS Code会以沙盒模式运行其配置文件路径可能略有不同。适配器代码需要包含足够的错误处理当无法访问某个路径时优雅地降级或给出明确提示而不是直接崩溃。测试连接超时为stdio和HTTP/SSE测试函数设置合理的超时时间非常重要。在本地测试时可以故意配置一个不存在的命令或不可达的URL观察错误信息是否清晰友好。使用Promise.race来实现超时控制是一个好方法。5.3 如何贡献代码从问题到PR我深知目前的代码“functional but not particularly elegant”功能可用但不够优雅。这正是开源协作的意义所在。如果你发现了bug或者有改进的想法非常欢迎提交PR。贡献流程建议Fork仓库点击GitHub仓库页面的“Fork”按钮创建你自己的副本。创建特性分支在你的副本中基于main分支创建一个新的分支名称最好能描述你的修改例如fix/vscode-env-merge或feat/add-zed-editor-support。进行修改在本地进行开发。请遵循现有的代码风格主要是TypeScript和Raycast的React风格。如果你添加了新功能请务必同时更新README.md中的相关文档。编写测试如果可能目前项目缺乏自动化测试这是一个亟待改进的领域。如果你添加的功能逻辑比较复杂尝试在__tests__目录下添加一些单元测试会是巨大的贡献。Raycast扩展可以使用Jest进行测试。提交代码使用清晰的提交信息。推荐使用类似git commit -m feat: add support for Zed editor或git commit -m fix: handle missing config file gracefully in cursor adapter的格式。推送并创建Pull Request将你的分支推送到你的GitHub副本然后在原仓库的页面发起Pull Request。在PR描述中详细说明你修改了什么、为什么修改、以及如何测试。一些明确的、需要帮助的方向代码重构目前的适配器代码中有一些重复的逻辑可以抽象成更通用的函数。错误处理也可以更加统一和健壮。支持更多编辑器比如Zed这是一个新兴的高性能编辑器它也可能在未来支持MCP。为其编写适配器会很有价值。增强UI/UX例如在服务器列表中添加“启用/禁用”开关需要编辑器配置支持或者提供服务器配置的“复制到其他编辑器”的一键操作。完善错误处理目前一些边缘情况的错误信息还不够友好。可以系统性地检查所有可能抛出异常的地方并用更用户友好的语言包装它们。添加测试如前所述为核心的适配器和工具函数添加单元测试和集成测试。这个工具源于我个人的需求但它应该服务于所有有同样痛点的开发者。通过社区的力量我们可以让它变得更强大、更稳定、更好用。期待看到你的贡献。