MCP 集成最佳实践

本指南基于 CCJK 的 MCP（Model Context Protocol）服务集成功能，提供生产环境中的最佳实践建议。

概述

MCP 服务集成是现代 AI 辅助开发中的关键组件，通过合理的配置和管理，可以显著提升开发效率和 AI 助手的能力边界。

核心最佳实践

1. 服务选择策略

按需安装原则

推荐做法：

hljs bash
# 根据团队实际需求选择服务
npx ccjk i -s --mcp-services context7,open-websearch,spec-workflow

为什么这样做：

• 减少系统资源占用
• 降低配置复杂性
• 提升服务启动速度
• 避免不必要的依赖冲突

服务分层配置

hljs mermaid
graph TD
    A[核心服务层] --> B[context7 - 文档查询]
    A --> C[open-websearch - 网页搜索]
    
    D[增强服务层] --> E[spec-workflow - 工作流]
    D --> F[mcp-deepwiki - GitHub 文档]
    
    G[专业服务层] --> H[Playwright - 自动化]
    G --> I[exa - AI 搜索]
    G --> J[serena - 语义检索]

配置建议：

hljs json
// 开发环境 - 最小集合
{
  "essential": ["context7", "open-websearch"],
  "enhanced": ["spec-workflow"],
  "professional": []
}

// 生产环境 - 完整集合
{
  "essential": ["context7", "open-websearch"],
  "enhanced": ["spec-workflow", "mcp-deepwiki"],
  "professional": ["exa", "serena"]
}

2. 环境变量管理

集中化配置

创建环境配置文件：

hljs bash
# ~/.mcp-env
export EXA_API_KEY="your-exa-api-key"
export NODE_ENV="production"
export MCP_LOG_LEVEL="info"

加载配置：

hljs bash
# 在 ~/.bashrc 或 ~/.zshrc 中添加
if [ -f ~/.mcp-env ]; then
    source ~/.mcp-env
fi

多环境配置策略

hljs bash
# 开发环境
cp .env.development .env

# 测试环境  
cp .env.testing .env

# 生产环境
cp .env.production .env

.env.development：

hljs bash
EXA_API_KEY="dev-key"
MCP_LOG_LEVEL="debug"
MCP_TIMEOUT="30000"

.env.production：

hljs bash
EXA_API_KEY="prod-key"
MCP_LOG_LEVEL="error"
MCP_TIMEOUT="10000"

3. 配置文件优化

Claude Code 配置优化

~/.claude/settings.json：

hljs json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context-labs/context7"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "open-websearch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-open-websearch"],
      "timeout": 30000
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-exa"],
      "env": {
        "EXA_API_KEY": "${EXA_API_KEY}"
      },
      "disabled": false
    }
  },
  "globalSettings": {
    "mcpTimeout": 30000,
    "mcpRetries": 3,
    "mcpLogLevel": "info"
  }
}

Codex 配置优化

~/.codex/config.toml：

hljs toml
[global]
mcp_timeout = 30000
mcp_retries = 3
mcp_log_level = "info"

[mcp_server.context7]
command = "npx"
args = ["-y", "@context-labs/context7"]
timeout = 30000

[mcp_server.open-websearch]  
command = "npx"
args = ["-y", "@modelcontextprotocol/server-open-websearch"]
timeout = 30000

[mcp_server.exa]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-exa"]
timeout = 30000
disabled = false

[mcp_server.exa.env]
EXA_API_KEY = "${EXA_API_KEY}"

4. 性能优化策略

服务预热

创建预热脚本：

hljs bash
#!/bin/bash
# scripts/mcp-warmup.sh

echo "开始 MCP 服务预热..."

# 预热 context7
echo "预热 context7..."
timeout 10s npx -y @context-labs/context7 --version

# 预热 open-websearch
echo "预热 open-websearch..."
timeout 10s npx -y @modelcontextprotocol/server-open-websearch --version

echo "MCP 服务预热完成"

开机自动预热：

hljs bash
# 添加到 ~/.bashrc
if [ "$SHELL_STARTUP" != "true" ]; then
    export SHELL_STARTUP=true
    bash ~/scripts/mcp-warmup.sh &
fi

缓存优化

hljs bash
# 预安装常用包，避免运行时下载
npm install -g @context-labs/context7
npm install -g @modelcontextprotocol/server-open-websearch
npm install -g @pimzino/spec-workflow-mcp

5. 监控和日志

健康检查脚本

hljs bash
#!/bin/bash
# scripts/mcp-health-check.sh

LOG_FILE="/tmp/mcp-health.log"

check_service() {
    local service=$1
    echo "检查服务: $service" >> $LOG_FILE
    
    if timeout 5s npx -y $service --version &>/dev/null; then
        echo "✅ $service: 正常" | tee -a $LOG_FILE
        return 0
    else
        echo "❌ $service: 异常" | tee -a $LOG_FILE
        return 1
    fi
}

echo "=== MCP 健康检查 $(date) ===" >> $LOG_FILE

# 检查核心服务
check_service "@context-labs/context7"
check_service "@modelcontextprotocol/server-open-websearch"
check_service "@pimzino/spec-workflow-mcp"

echo "检查完成" >> $LOG_FILE

日志轮转配置

hljs bash
# /etc/logrotate.d/mcp
/tmp/mcp-*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 644 $USER $USER
}

6. 安全配置

API 密钥管理

使用 keyring 存储：

hljs bash
# 安装 keyring
pip install keyring

# 存储 API 密钥
keyring set mcp exa_api_key

在配置中引用：

hljs python
# scripts/get-api-key.py
import keyring
import os

api_key = keyring.get_password("mcp", "exa_api_key")
if api_key:
    os.environ["EXA_API_KEY"] = api_key

权限控制

hljs bash
# 确保配置文件权限安全
chmod 600 ~/.claude/settings.json
chmod 600 ~/.codex/config.toml
chmod 600 ~/.mcp-env

7. 跨平台兼容性

Windows 特定配置

hljs json
{
  "mcpServers": {
    "context7": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@context-labs/context7"],
      "shell": true
    }
  }
}

macOS 特定配置

hljs json
{
  "mcpServers": {
    "context7": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@context-labs/context7"]
    }
  }
}

Linux 特定配置

hljs toml
[mcp_server.context7]
command = "/usr/bin/npx"
args = ["-y", "@context-labs/context7"]

常见错误和解决方案

错误 1：服务启动超时

现象：

Error: MCP server 'context7' failed to start within 30 seconds

原因：

• 网络问题导致 npm 包下载慢
• 系统资源不足
• Node.js 版本不兼容

解决方案：

hljs bash
# 1. 增加超时时间
npx ccjk config set mcp.timeout 60000

# 2. 预安装依赖
npm install -g @context-labs/context7

# 3. 清理 npm 缓存
npm cache clean --force

# 4. 检查 Node.js 版本
node --version  # 需要 >= 18.0.0

错误 2：API 密钥无效

现象：

Error: Invalid API key for service 'exa'

解决方案：

hljs bash
# 1. 验证 API 密钥
echo $EXA_API_KEY

# 2. 重新设置密钥
export EXA_API_KEY="your-valid-key"

# 3. 测试密钥有效性
curl -H "Authorization: Bearer $EXA_API_KEY" https://api.exa.ai/v1/search

# 4. 持久化配置
echo 'export EXA_API_KEY="your-valid-key"' >> ~/.bashrc
source ~/.bashrc

错误 3：配置文件格式错误

现象：

Error: Failed to parse MCP configuration

解决方案：

hljs bash
# 1. 验证 JSON 格式
python -m json.tool ~/.claude/settings.json

# 2. 验证 TOML 格式
python -c "import tomli; tomli.load(open('~/.codex/config.toml', 'rb'))"

# 3. 重新生成配置
npx ccjk
# 选择 4. 配置 MCP

错误 4：Windows 路径问题

现象：

Error: Command not found: npx

解决方案：

hljs bash
# 1. 运行 CCJK 自动修复
npx ccjk

# 2. 手动修正配置
# 将 "npx" 改为 "cmd /c npx"
# 将路径分隔符改为 Windows 格式

错误 5：端口冲突

现象：

Error: Address already in use

解决方案：

hljs bash
# 1. 检查端口占用
netstat -tulpn | grep :8080

# 2. 配置不同端口
npx ccjk config set mcp.port 8081

# 3. 重启服务
npx ccjk restart mcp

部署自动化

CI/CD 集成

GitHub Actions 示例：

hljs yaml
# .github/workflows/mcp-setup.yml
name: Setup MCP Services

on:
  push:
    branches: [main]

jobs:
  setup-mcp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install CCJK
        run: npm install -g ccjk
        
      - name: Configure MCP Services
        run: |
          npx ccjk i -s --mcp-services context7,open-websearch
        env:
          EXA_API_KEY: ${{ secrets.EXA_API_KEY }}
          
      - name: Health Check
        run: bash scripts/mcp-health-check.sh

Docker 容器化

Dockerfile：

hljs dockerfile
FROM node:18-alpine

# 安装 CCJK 和 MCP 服务
RUN npm install -g ccjk
RUN npm install -g @context-labs/context7
RUN npm install -g @modelcontextprotocol/server-open-websearch

# 复制配置文件
COPY config/.claude/settings.json /root/.claude/
COPY config/.codex/config.toml /root/.codex/

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD bash /app/scripts/mcp-health-check.sh

EXPOSE 8080
CMD ["npx", "ccjk", "serve"]

Kubernetes 部署

deployment.yaml：

hljs yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-services
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-services
  template:
    metadata:
      labels:
        app: mcp-services
    spec:
      containers:
      - name: mcp
        image: your-registry/mcp-services:latest
        env:
        - name: EXA_API_KEY
          valueFrom:
            secretKeyRef:
              name: mcp-secrets
              key: exa-api-key
        ports:
        - containerPort: 8080
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
---
apiVersion: v1
kind: Secret
metadata:
  name: mcp-secrets
type: Opaque
data:
  exa-api-key: <base64-encoded-key>

总结

通过遵循这些最佳实践，您可以：

1. 提升性能：通过预热、缓存和优化配置减少延迟
2. 增强稳定性：通过监控、日志和健康检查确保服务可用性
3. 保障安全：通过密钥管理和权限控制保护敏感信息
4. 简化运维：通过自动化部署和配置管理减少人工操作
5. 确保兼容性：通过跨平台配置支持不同环境需求

记住，MCP 服务集成是一个持续优化的过程，建议定期评估和调整配置，以适应团队和项目的变化需求。