# MCP Server 快速开始指南

> **快速上手**：在 OpenClaw 服务器上部署和管理 MCP Servers
> **预计时间**：30 分钟（基础环境） + 2 小时（FastLog Server）
> **更新日期**：2026-03-18

---

## 📋 目录

1. [环境准备](#环境准备)
2. [安装管理脚本](#安装管理脚本)
3. [安装 FastLog Server](#安装-fastlog-server)
4. [启用和测试](#启用和测试)
5. [日常管理](#日常管理)

---

## 🔧 环境准备

### Step 1: 创建目录结构

```bash
# 创建 MCP Server 根目录
sudo mkdir -p /opt/mcp-servers/{active,inactive,templates,shared/{scripts,libs,utils},logs}

# 创建配置目录
sudo mkdir -p /etc/openclaw/mcp

# 设置权限
sudo chown -R root:root /opt/mcp-servers
sudo chmod 755 /opt/mcp-servers
sudo chmod 755 /opt/mcp-servers/*
```

### Step 2: 创建初始配置

```bash
# 创建 servers.json
sudo tee /etc/openclaw/mcp/servers.json > /dev/null <<EOF
{
  "version": "1.0.0",
  "servers": {}
}
EOF

# 设置权限
sudo chmod 644 /etc/openclaw/mcp/servers.json
```

### Step 3: 安装依赖

```bash
# Python 环境检查
python3 --version
pip3 --version

# 安装 MCP SDK（如果需要）
pip3 install "mcp>=1.2.0"

# Git（用于克隆 Server 源码）
sudo yum install git -y
# 或
sudo apt install git -y
```

---

## 📦 安装管理脚本

### Step 1: 复制脚本

```bash
# 复制脚本到共享目录
sudo cp /root/.openclaw-master/workspace/mcp-scripts/*.sh /opt/mcp-servers/shared/scripts/
sudo cp /root/.openclaw-master/workspace/mcp-scripts/*.py /opt/mcp-servers/shared/scripts/

# 设置可执行权限
sudo chmod +x /opt/mcp-servers/shared/scripts/*.sh

# 验证
ls -la /opt/mcp-servers/shared/scripts/
```

### Step 2: 测试脚本

```bash
# 测试列表脚本
sudo /opt/mcp-servers/shared/scripts/list-servers.sh

# 应该输出：暂无已安装的 MCP Servers
```

---

## 🚀 安装 FastLog Server

### Step 1: 准备 FastLog Server 源码

```bash
# 创建临时工作目录
mkdir -p /tmp/fastlog-mcp-server

# 从现有代码重构（手动）
# 或者从 Git 克隆（如果已上传）
# git clone https://github.com/openclaw/fastlog-mcp-server.git /tmp/fastlog-mcp-server
```

### Step 2: 使用安装脚本

```bash
# 安装 FastLog Server
sudo /opt/mcp-servers/shared/scripts/install-server.sh \
    fastlog \
    python \
    /tmp/fastlog-mcp-server

# 输出应该包括：
# ✅ MCP Server 安装成功！
#    路径: /opt/mcp-servers/active/fastlog-server
```

### Step 3: 验证安装

```bash
# 列出已安装的 Servers
sudo /opt/mcp-servers/shared/scripts/list-servers.sh

# 应该看到 fastlog Server
```

### Step 4: 配置 Server

```bash
# 编辑配置文件
sudo vi /opt/mcp-servers/active/fastlog-server/config/server.json

# 更新 API 配置
{
  "api_base_url": "https://fast.mypaas.com",
  "logstore_id": "665979265166086144",
  "default_env_code": "xc-syzhkj-idc",
  "tenant_code": "skyline"
}
```

---

## ✅ 启用和测试

### Step 1: 启用 Server

```bash
# 启用 FastLog Server
sudo /opt/mcp-servers/shared/scripts/toggle-server.sh fastlog enable

# 输出：✅ Server "fastlog" 已启用
```

### Step 2: 手动测试 Server

```bash
# 进入 Server 目录
cd /opt/mcp-servers/active/fastlog-server

# 手动启动测试
python3 -m fastlog_server

# Server 应该启动并等待 JSON-RPC 请求
# 按 Ctrl+C 停止
```

### Step 3: 集成到 OpenClaw

```bash
# 编辑 OpenClaw 配置
sudo vi /etc/openclaw/gateway/config.yaml

# 添加 MCP 配置
mcp:
  enabled: true
  servers_config: "/etc/openclaw/mcp/servers.json"
  servers_dir: "/opt/mcp-servers/active"
  auto_discovery: true

# 重启 Gateway
sudo systemctl restart openclaw-gateway

# 查看日志
sudo journalctl -u openclaw-gateway -f
```

---

## 📊 日常管理

### 列出所有 Servers

```bash
# 列表
sudo /opt/mcp-servers/shared/scripts/list-servers.sh

# 示例输出：
# ╔════════════════════════════════════════════════════════════╗
# ║                    MCP Servers 列表                           ║
# ╚════════════════════════════════════════════════════════════╝
#
# 名称              类型     状态        安装时间
# ------------------------------------------------------------
# fastlog           python   ✓ active    2026-03-18 12:30
# weather           python   ✗ inactive  2026-03-18 11:15
#
# 总计: 2 个 MCP Servers
```

### 启用/禁用 Server

```bash
# 启用
sudo /opt/mcp-servers/shared/scripts/toggle-server.sh fastlog enable

# 禁用
sudo /opt/mcp-servers/shared/scripts/toggle-server.sh fastlog disable

# 提示：重启 OpenClaw Gateway 以应用更改
```

### 查看 Server 日志

```bash
# FastLog Server 日志
tail -f /opt/mcp-servers/logs/fastlog-server.log

# 所有 MCP Servers 日志
ls -la /opt/mcp-servers/logs/
```

### 更新 Server

```bash
# 进入 Server 目录
cd /opt/mcp-servers/active/fastlog-server

# 拉取最新代码
git pull

# 重新安装依赖
pip3 install -r requirements.txt

# 重启 OpenClaw Gateway
sudo systemctl restart openclaw-gateway
```

---

## 🔍 故障排查

### 问题 1：Server 无法启动

**症状**：`Error starting MCP Server`

**排查步骤**：
```bash
# 检查 Python 版本
python3 --version  # 需要 >= 3.10

# 检查依赖
cd /opt/mcp-servers/active/fastlog-server
pip3 list | grep mcp

# 手动测试
python3 -m fastlog_server

# 查看日志
tail -f /opt/mcp-servers/logs/fastlog-server.log
```

### 问题 2：OpenClaw 无法连接 Server

**症状**：`MCP Server connection failed`

**排查步骤**：
```bash
# 检查配置
cat /etc/openclaw/mcp/servers.json

# 验证 Server 路径
ls -la /opt/mcp-servers/active/fastlog-server

# 检查 Gateway 日志
sudo journalctl -u openclaw-gateway -n 50

# 重启 Gateway
sudo systemctl restart openclaw-gateway
```

### 问题 3：API 调用失败

**症状**：`FastLog API error`

**排查步骤**：
```bash
# 检查网络连接
curl -I https://fast.mypaas.com

# 检查 API 凭证
cat /opt/mcp-servers/active/fastlog-server/config/server.json

# 手动测试 API
curl -X POST https://fast.mypaas.com/api/data/logstore/... \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'
```

---

## 📚 进阶配置

### 日志轮转

```bash
# 配置日志轮转
sudo tee /etc/logrotate.d/mcp-servers > /dev/null <<EOF
/opt/mcp-servers/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0644 root root
}
EOF

# 测试日志轮转
sudo logrotate -d /etc/logrotate.d/mcp-servers
```

### 健康检查

```bash
# 创建健康检查脚本
cat > /opt/mcp-servers/shared/scripts/health-check.sh <<'EOF'
#!/bin/bash
# MCP Server 健康检查

CONFIG_FILE="/etc/openclaw/mcp/servers.json"

python3 <<'PYSCRIPT'
import json
import subprocess
from datetime import datetime

config_file = '/etc/openclaw/mcp/servers.json'

with open(config_file, 'r') as f:
    config = json.load(f)

servers = config.get('servers', {})
total = len(servers)
active = sum(1 for s in servers.values() if s.get('enabled'))

print(f"MCP Servers 健康检查 ({datetime.now().strftime('%Y-%m-%d %H:%M:%S')})")
print(f"总计: {total}, 活跃: {active}")

for name, info in servers.items():
    status = "✓" if info.get('enabled') else "✗"
    print(f"  {status} {name}")
PYSCRIPT
EOF

chmod +x /opt/mcp-servers/shared/scripts/health-check.sh

# 定时执行
# 添加到 crontab：*/5 * * * * /opt/mcp-servers/shared/scripts/health-check.sh >> /opt/mcp-servers/logs/health.log 2>&1
```

---

## 📖 参考资料

### 完整文档

- **架构规划**：[MCP-SERVER-架构规划.md](./MCP-SERVER-架构规划.md)
- **案例展示**：[AI原生应用案例展示.md](./AI原生应用案例展示.md)

### MCP 官方文档

- [MCP 官方文档](https://modelcontextprotocol.io/)
- [FastMCP SDK](https://github.com/jlowin/fastmcp)
- [构建 MCP Server](https://modelcontextprotocol.io/docs/develop/build-server)

### OpenClaw 文档

- [OpenClaw 文档](https://docs.openclaw.ai/)
- [MCP 集成指南](https://docs.openclaw.ai/mcp/integration)

---

## 🎯 下一步

### 立即执行

1. ✅ 完成环境准备（10 分钟）
2. ✅ 安装管理脚本（5 分钟）
3. ✅ 安装 FastLog Server（15 分钟）
4. ✅ 启用和测试（10 分钟）

### 持续优化

- 📝 添加更多 MCP Servers
- 🔧 完善监控和日志
- 📊 构建管理仪表板
- 🔐 加强安全配置

---

*快速开始指南由 AI 助手达达自动生成* ⚡