# MCP 服务器连接说明

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

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

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

## 工作原理

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

## 在 Cursor 中配置

### 本地运行（开发）

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

### 服务器运行（生产）

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

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

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

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

## 验证连接

### 1. 检查进程是否运行

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

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

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

### 2. 测试 MCP 服务器

```bash
# 直接运行测试
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**: 检查进程：
```bash
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 服务器：

```typescript
// 在 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 协议的标准工作方式