cloud-mcp/MCP_CONNECTION.md

MCP 服务器连接说明

重要：MCP 服务器不监听端口！

MCP (Model Context Protocol) 服务器使用 stdio（标准输入输出） 传输，不监听任何网络端口。

这意味着：

• ❌ 没有 HTTP 端点
• ❌ 没有 WebSocket 连接
• ❌ 不能通过浏览器访问
• ✅ 通过进程间通信（stdin/stdout）与客户端通信

工作原理

Cursor/Claude Desktop (客户端)
    ↓ (启动进程)
bun run src/index.ts (MCP 服务器)
    ↓ (stdio 通信)
工具执行和响应

在 Cursor 中配置

本地运行（开发）

{
  "mcpServers": {
    "cloud-mcp": {
      "command": "bun",
      "args": ["run", "/Users/zijianchen/Desktop/my-project/cloud-mcp/src/index.ts"]
    }
  }
}

服务器运行（生产）

如果 MCP 服务器运行在远程服务器上：

{
  "mcpServers": {
    "cloud-mcp": {
      "command": "ssh",
      "args": [
        "user@your-server",
        "cd /opt/cloud-mcp && bun run src/index.ts"
      ]
    }
  }
}

或者如果服务器上已经通过 PM2/systemd 运行，可以通过 SSH 直接连接：

{
  "mcpServers": {
    "cloud-mcp": {
      "command": "ssh",
      "args": [
        "user@your-server",
        "bun run /opt/cloud-mcp/src/index.ts"
      ]
    }
  }
}

验证连接

1. 检查进程是否运行

# 在服务器上
ps aux | grep "bun.*index.ts"

# 或如果使用 PM2
pm2 list | grep cloud-mcp

# 或如果使用 systemd
sudo systemctl status cloud-mcp

2. 测试 MCP 服务器

# 直接运行测试
cd /opt/cloud-mcp
bun run src/index.ts

# 应该看到：
# [INFO] Registering tools...
# [INFO] All tools registered. Starting MCP server...
# [INFO] MCP Server started

3. 在 Cursor 中测试

1. 配置 MCP 服务器后
2. 重启 Cursor
3. 尝试使用任何工具（如 deploy_status）
4. 如果连接成功，工具会正常执行

常见问题

Q: 为什么看不到端口监听？

A: MCP 使用 stdio，不需要端口。这是 MCP 协议的设计。

Q: 如何知道服务器是否在运行？

A: 检查进程：

ps aux | grep "bun.*index.ts"

Q: 可以添加 HTTP 端点吗？

A: 可以，但需要修改代码使用 SSE 传输。当前实现使用 stdio，这是 MCP 的标准方式。

Q: 如何调试连接问题？

A:

1. 检查 Cursor 的 MCP 日志
2. 在服务器上直接运行 bun run src/index.ts 查看错误
3. 检查 SSH 连接是否正常（如果使用远程服务器）

添加健康检查端点（可选）

如果你需要一个 HTTP 端点来检查服务状态，可以添加一个简单的 HTTP 服务器：

// 在 src/index.ts 中添加
import { serve } from "bun";

// 健康检查端点（可选）
serve({
  port: 3000,
  fetch(req) {
    if (req.url.endsWith("/health")) {
      return new Response(JSON.stringify({ status: "ok" }), {
        headers: { "Content-Type": "application/json" },
      });
    }
    return new Response("Not Found", { status: 404 });
  },
});

console.log("Health check server running on http://localhost:3000/health");

但这只是用于健康检查，MCP 通信仍然通过 stdio。

总结

• MCP 服务器不监听端口，使用 stdio 通信
• 在 Cursor 中配置时，指定 command 和 args 来启动进程
• 服务器运行时，Cursor 会自动启动进程并通过 stdio 通信
• 这是 MCP 协议的标准工作方式