游标-MCP管理器

Name: 游标-MCP管理器
Author: zackiles

作者：zackiles2 星标更新：2025-05-30

安装使用来源：spider==github.com

项目介绍

Cursor 的 MCP Server Manager

一个用于 Cursor 的 MCP（模型上下文协议）工作区管理器。这个项目简化了在本地开发环境中管理多个 MCP 服务器时通常繁琐的工作流程。它提供了一致且统一的配置方法和 CLI（命令行界面），可以一次性或单独地启动、停止、更新和检查所有 MCP 服务器的状态。它还自动管理你的全局（或本地）Cursor MCP 配置中的 mcp.json 文件。

你可以通过 deno task 命令（例如 deno task start）运行 CLI，或者直接执行主模块 deno run -A src/mod.ts <command> [options]。

项目概述

目的

管理各种 MCP 服务器，每种服务器都有自己的设置和操作特性，可能会很麻烦。此项目集中化了这种管理。定义好所有服务器后，就可以使用简单的命令来控制它们。无论是通过 HTTP/SSE 还是 STDIO 通信的 MCP 服务器，该管理器都能一致地处理它们。

快速入门

[!警告] 新手 MCP？特别是在企业环境中，你需要知道自己在做什么。在继续之前，请阅读如何安全使用 MCP。

要开始使用 MCP 服务器管理器，你主要会与服务器定义和环境设置进行交互。以下是关键组件的概述：

服务器配置文件：位于 servers/ 目录中，这些 TypeScript 文件（如 mcp-myservice.config.ts）定义了每个 MCP 服务器的属性。你可以从 examples/ 目录中的模板开始（例如，examples/mcp-atlassian.ts.example 用于 HTTP/SSE 服务器，examples/mcp-slack.ts.example 用于 STDIO 服务器）。
环境变量：敏感凭证和特定于服务器的设置存储在 .env 文件中（例如，servers/config/mcp-myservice.env）。examples/ 目录提供了示例环境文件（例如，examples/mcp-myservice.env.example）以指导你。
全局管理设置：servers/config/main.env 文件控制全局行为，例如通过 ENABLED_SERVERS 变量指定哪些服务器处于活动状态。

有关创建和配置新服务器的详细步骤，请参阅主工作流中的添加新 MCP 服务器部分。

[!提示] 为了最佳使用，分叉此仓库以安全地管理个人 MCP 服务器配置。为了更方便地访问 CLI，将 src/mod.ts 别名为 PATH 中的命令，或在其他项目中创建指向 src/mod.ts 的 Cursor 规则。

什么是 MCP 服务器？

MCP（模型上下文协议）服务器充当 Cursor 和外部服务或工具之间的桥梁。它允许 Cursor 访问并与其交互，通过暴露一组标准的“工具”使 Cursor 能够调用这些服务的数据或功能（如 Jira、Slack、Confluence 等）。这使得从 IDE 通过自然语言或特定命令直接检索 Jira 问题、搜索 Confluence 页面或发送 Slack 消息成为可能。

状态管理

MCP 服务器管理器跟踪已配置服务器的状态（例如，HTTP 服务器当前是否正在运行）并在 data/state.json 文件中记录。此文件由 CLI 自动管理。

主工作流

添加新 MCP 服务器

创建配置文件：
- 导航到 examples/ 目录并选择一个模板：
  - 对于 HTTP/SSE 服务器：mcp-atlassian.ts.example
  - 对于 STDIO 服务器：mcp-slack.ts.example
- 将选定的模板文件复制到 servers/ 目录。
- 将复制的文件重命名为反映你的新服务器，例如 mcp-myservice.config.ts。
编辑配置：
- 打开你的新服务器配置文件（例如 mcp-myservice.config.ts）。
- 更新 name、description、type（http 或 stdio）、image 和 args 字段。
- 环境文件（例如 servers/config/mcp-myservice.env）根据你设置的服务器 name 自动被 MCP 管理器使用。
- 对于 HTTP/SSE 服务器：
  - 你可以在 args 数组中可选地包含 --port PORT 来指定固定端口。
  - 如果未指定端口，管理器将在启动服务器时自动分配可用端口。
- 配置 healthValidator 部分以定义如何检查服务器的健康状况。这种标准化配置适用于 HTTP 和 STDIO 服务器。以下是一个示例：
```
healthValidator: {
  method: "mcp/tools/list", // 要调用的 MCP 方法
  params: {},               // 方法参数
  responseContains: "tools", // 响应中必须包含的可选字符串
  timeoutMs:  5000          // 超时时间（毫秒）
}
```
- 在 postStartInstructions 属性中包含测试提示示例，以指导用户在服务器运行后如何测试服务器。
创建环境文件：
- 在 examples/ 目录中创建一个示例环境文件（例如 examples/mcp-myservice.env.example），列出所有需要的环境变量及其占位符值。
- 在 servers/config/ 目录中创建实际环境文件（例如 servers/config/mcp-myservice.env），通过复制示例并填写实际凭证和设置。
- 重要：如果尚未通过通用模式（如 servers/config/*.env）覆盖，请将实际环境文件添加到 .gitignore 中，以避免提交敏感凭证。
测试：
- 现在你可以使用通用工作流（如 deno task start 启动）来管理你的新服务器。

示例 HTTP 服务器配置：

const serverConfig: McpServerConfig = {
  name: 'mcp-atlassian',
  description: 'MCP Atlassian 连接器',
  type: 'http',
  image: 'ghcr.io/sooperset/mcp-atlassian:latest',
  args: [
    '--transport',
    'sse',
    // 如果未指定，端口将自动分配
    // '--port',
    // '9000',
    '-vv',
  ],

  healthValidator: {
    method: 'mcp/tools/list',
    params: {},
    responseContains: 'tools',
    timeoutMs: 5000,
  },

  postStartInstructions: `
Atlassian MCP 服务器现在正在运行！
你现在可以在 Cursor 中使用 Jira 和 Confluence 工具。
确保你的 Atlassian 凭证已在 .env 文件中正确配置。
尝试使用 jira_list_projects 工具检索我有权访问的所有 Jira 项目，并以项目符号列表格式输出结果
`,
}

示例 STDIO 服务器配置：

const serverConfig: McpServerConfig = {
  name: 'mcp-slack',
  description: 'MCP Slack 连接器',
  type: 'stdio',
  image: 'mcp/slack',
  args: [], // STDIO 服务器不需要额外参数
  // 编排器将添加必要的 Docker 参数

  healthValidator: {
    method: 'slack_get_users',
    params: { limit: 1 },
    timeoutMs: 10000,
  },

  postStartInstructions: `
注意：Slack MCP 服务器设计为交互模式运行。
Cursor 根据需要运行服务器，因此不需要持久容器。
你现在可以在 Cursor 中使用 Slack 工具。
尝试使用命令：列出 Slack 工作空间中的所有频道
`,
}

编辑 MCP 服务器

要编辑现有 MCP 服务器：

修改 servers/ 目录中的其配置文件。
如有必要，更新 servers/config/ 目录中的相应环境文件。下次运行命令（例如 deno task start）时，更改将被采用。

移除 MCP 服务器

要移除 MCP 服务器：

删除 servers/ 目录中的其配置文件。
（可选）删除 servers/config/ 和 examples/ 目录中的其环境文件。该服务器将不再由 CLI 管理。

通用工作流（CLI 命令）

所有命令都可以针对所有已配置的服务器或特定服务器运行，使用 --server=<server-name> 标志（例如 deno task start --server=mcp-atlassian）。

启动服务器：
```
deno task start
# 或启动特定服务器：
deno task start --server=mcp-myservice
```
此命令启动已配置的 MCP 服务器。对于 HTTP 服务器，它启动 Docker 容器，并在配置中未指定端口时自动分配可用端口。对于 STDIO 服务器，它验证配置。成功启动后，CLI 将询问你是否希望自动更新 Cursor 配置文件中的服务器设置。如果你拒绝，它将显示你需要手动添加的必要 JSON 配置。
```
# 查看启动服务器后 Cursor MCP 配置的变化而不做实际更改：
deno task start --dry-run
# 或针对特定服务器：
deno task start --server=mcp-myservice --dry-run
# 专用干跑任务：
deno task start:dry-run
```
--dry-run 标志显示将对你的 Cursor MCP 配置文件做出哪些更改，而不会实际进行这些更改。它显示当前配置以及启动服务器后的样子。
停止服务器：
```
deno task stop
# 或停止特定服务器：
deno task stop --server=mcp-myservice
```
这会停止任何正在运行的 HTTP MCP 服务器容器。STDIO 服务器不持续运行，因此此命令主要影响 HTTP 类型。CLI 将自动更新你的 Cursor 配置文件，以反映服务器不再运行的事实，确保 Cursor 与实际服务器状态同步。
```
# 查看停止服务器后 Cursor MCP 配置的变化而不做实际更改：
deno task stop --dry-run
# 或针对特定服务器：
deno task stop --server=mcp-myservice --dry-run
# 专用干跑任务：
deno task stop:dry-run
```
类似于启动命令，--dry-run 标志显示将对你的 Cursor MCP 配置文件做出哪些更改，而不会实际进行这些更改或停止任何服务器。
查看服务器状态：
```
deno task status
# 或针对特定服务器：
deno task status --server=mcp-myservice
```
显示所有已配置 MCP 服务器的当前状态（例如，运行、停止或 STDIO 的验证状态）。
查看服务器日志：
```
deno task logs
# 或针对特定服务器：
deno task logs --server=mcp-myservice
```
显示正在运行的 HTTP MCP 服务器容器的最后 100 行日志。这对于故障排除或监控服务器活动非常有用。
```
# 实时连续流式传输日志：
deno task logs --stream
# 或针对特定服务器：
deno task logs --server=mcp-myservice --stream
# 专用流式传输任务：
deno task logs:stream
```
--stream 标志启用实时日志流式传输，类似于 docker logs --follow。当调试问题或观察服务器活动时特别有用。按 Ctrl+C 退出流式传输模式。
执行健康检查：
```
deno task health-check
# 或针对特定服务器：
deno task health-check --server=mcp-myservice
```
对于 HTTP 服务器，这检查运行容器是否响应且健康。对于 STDIO 服务器，它重新运行验证。
更新服务器镜像：
```
deno task update
# 或针对特定服务器：
deno task update --server=mcp-myservice
```
拉取配置文件中定义的指定服务器的最新 Docker 镜像。

MCP 服务器类型

此管理器支持两种类型的 MCP 服务器，由配置中的 type 属性区分：

1. HTTP/SSE 服务器（例如 Atlassian MCP）

在此代码库中的工作方式：
- 这些服务器作为后台持久的 Docker 容器运行。
- 该管理器启动 Docker 容器，映射必要的端口，并使用标准化的 healthValidator 配置执行健康检查。
- 认证和特定于服务器的逻辑在 Docker 镜像本身内处理，通过从关联的 .env 文件传递的环境变量进行配置。
Cursor 配置：
- Cursor 通过 URL（例如 http://localhost:9000/sse）连接到这些服务器。
- 如果你在服务器配置 args 中指定了端口，管理器将使用该端口。
- 如果未指定端口，管理器将在服务器启动时自动分配可用端口。
- 当服务器成功启动时，CLI 将提供自动更新你的 Cursor MCP 配置文件的选项，以包含适当的设置。
- 如果你偏好手动配置，CLI 将提供要添加到 Cursor 设置的确切 JSON 片段。

2. STDIO 服务器（例如 Slack MCP）

在此代码库中的工作方式：
- 这些服务器设计为按需由 Cursor 启动并通过标准输入/输出（STDIO）通信。
- 它们不作为持久后台服务运行。当你使用 deno task start 命令启动 STDIO 服务器时，此管理器暂时启动 Docker 容器仅用于验证配置和凭据（来自其 .env 文件）是否正确使用 healthValidator 配置。然后容器将退出。这是预期的行为。
Cursor 配置：
- Cursor 配置中的 STDIO 服务器包括 command（例如 docker）和 args 数组，以交互方式运行容器。
- 管理器自动添加 --env-file 标志指向你的环境文件，因此无需在配置中硬编码凭据。
- 当验证成功时，CLI 将提供自动更新你的 Cursor MCP 配置文件的选项，以包含适当的设置。
- 如果你偏好手动配置，CLI 将提供 Cursor 的模板 JSON 片段。

健康验证

HTTP 和 STDIO 服务器都可以使用标准化的健康验证机制：

healthValidator: {
  method: "mcp/tools/list",    // 要调用的 MCP 方法
  params: {},                  // 方法参数
  responseContains: "tools",   // 响应中必须包含的可选字符串
  timeoutMs: 5000              // 超时时间（毫秒）
}

healthValidator 属性是可选的。如果未指定（null、false 或 undefined），则跳过健康检查并返回成功状态。
配置时，验证器使用提供的方法和参数构建 JSON-RPC 2.0 请求。
对于 HTTP 服务器，请求发送到服务器的端点。
对于 STDIO 服务器，请求通过 Docker STDIO 发送到服务器。
检查响应是否有错误，并可选地检查响应中是否包含特定字符串。
这种统一的方法简化了服务器配置，并确保所有服务器类型的一致性健康检查。

健康验证系统还支持传递给验证器的 silent 选项，以抑制跳过健康检查时的日志消息。这主要用于 CLI 内部，在不需要详细日志的情况下检查服务器状态。

高级架构

MCP 服务器管理器采用配置驱动的设计：

服务器配置（servers/*.config.ts）：这些 TypeScript 文件是系统的核心。每个文件定义了一个 MCP 服务器，具有以下属性：
- name：服务器的唯一标识符
- description：人类可读的描述
- type：http 或 stdio
- image：使用的 Docker 镜像
- args：命令行参数（对于 HTTP 服务器，包括 --port 参数）
- healthValidator：可选的健康检查配置
- postStartInstructions：服务器启动后显示给用户的说明，包括示例使用命令
环境文件（servers/config/*.env 和 examples/*.env.example）：凭证和特定于服务器的设置存储在 .env 文件中，与主配置分开。这将敏感数据保留在版本控制之外。
核心逻辑（src/）：
- mod.ts：CLI 的主要入口点。
- config.ts：从 servers/ 目录加载所有服务器配置。
- types.ts：定义服务器配置（如 McpServerConfig）和状态的 TypeScript 类型和接口。
- orchestrator.ts：包含 transformServerConfigForCursor 函数，将服务器配置转换为 Cursor MCP 条目。
- commands/start.ts：实现主要的 start 命令逻辑，解析参数并编排动作。
- commands/stop.ts、commands/status.ts、commands/health-check.ts：实现各自动作的逻辑。
- services/cursor-service.ts：管理读写 Cursor 的 MCP 配置文件。
- services/docker-service.ts：处理与 Docker CLI 的所有交互（拉取镜像、运行/停止容器、检查状态）。
- services/health-validator-service.ts：包含 HTTP 和 STDIO 服务器的标准化健康验证逻辑。
Deno 任务（deno.jsonc）：为常见的 CLI 命令提供便捷快捷方式（如 deno task start）。

用户主要与 servers/ 目录中的配置文件及其相应的 .env 文件进行交互。src/ 目录包含使这一切工作的底层机制。

故障排除

检查日志：CLI 提供了信息性的日志。为了获得更详细的输出，你可以调整 `servers