Supercoordination MCP Server

# 超协体MCP服务器 - 团队成员接入指南

## 🎯 接入场景

### 场景一：同一台Mac上的多个终端（测试用）✅

**适用场景**: 本地测试、单机多Claude实例

**步骤**:
1. 确保MCP服务器正在运行
   ```bash
   # 查看服务器状态
   curl http://localhost:3000/health
   ```

2. 在**新终端窗口**中启动Claude Code
   ```bash
   cd /path/to/超协体MVP1.0代码库
   claude
   ```

3. 直接使用自然语言操作
   ```
   列出所有成员
   查看我的任务
   创建新任务...
   ```

**优点**: 零配置，立即可用
**限制**: 仅限同一台机器

---

### 场景二：同一局域网内的其他Mac（推荐）✅

**适用场景**: 团队成员在同一办公室/家庭网络

#### 步骤1: 主机（你）- 获取本机IP地址

```bash
# 获取局域网IP
ifconfig | grep "inet " | grep -v 127.0.0.1
```

**示例输出**: `inet 192.168.1.100`（记住这个IP）

#### 步骤2: 主机（你）- 确保服务器监听所有接口

编辑 `src/server.js`:
```javascript
// 修改这一行
const PORT = process.env.PORT || 3000;
const HOST = '0.0.0.0'; // 允许外部访问

// 修改启动代码
app.listen(PORT, HOST, () => {
  console.log(`🌟════════════════════════════════════════════════════🌟`);
  console.log(`     超协体 · 人机协同MCP服务器 v1.0 启动成功！`);
  console.log(`🌟════════════════════════════════════════════════════🌟\n`);
  console.log(`📍 本地访问: http://localhost:${PORT}`);
  console.log(`📍 局域网访问: http://192.168.1.100:${PORT}`); // 使用实际IP
  // ...
});
```

#### 步骤3: 主机（你）- 重启服务器

```bash
# 停止当前服务器（Ctrl+C）
# 重新启动
npm start
```

#### 步骤4: 主机（你）- 测试外部访问

```bash
# 从主机测试
curl http://192.168.1.100:3000/health
```

#### 步骤5: 团队成员 - 配置MCP连接

**方式A: 项目级配置（推荐）**

团队成员在自己的Mac上操作：

```bash
# 1. 克隆项目（或创建新目录）
mkdir -p /path/to/超协体MVP1.0代码库
cd /path/to/超协体MVP1.0代码库

# 2. 创建.mcp.json配置
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "supercoordination": {
      "type": "http",
      "url": "http://192.168.1.100:3000/mcp"
    }
  }
}
EOF

# 3. 启动Claude Code
claude
```

**方式B: 全局配置**

```bash
# 添加到Claude Code全局配置
claude mcp add --transport http supercoordination http://192.168.1.100:3000/mcp
```

#### 步骤6: 团队成员 - 验证连接

在Claude Code中执行：
```
列出所有成员
```

应该能看到现有成员（张三、李四）。

---

### 场景三：远程访问（跨网络）🌐

**适用场景**: 团队成员不在同一网络，远程办公

#### 方案A: 使用ngrok（快速方案）

**主机（你）操作**:

```bash
# 1. 安装ngrok
brew install ngrok

# 2. 启动ngrok隧道
ngrok http 3000
```

**输出示例**:
```
Forwarding  https://abc123.ngrok.io -> http://localhost:3000
```

**团队成员配置**:
```json
{
  "mcpServers": {
    "supercoordination": {
      "type": "http",
      "url": "https://abc123.ngrok.io/mcp"
    }
  }
}
```

**优点**: 立即可用，无需配置路由器
**限制**: 免费版URL会变化，需要重新分享

#### 方案B: 云服务器部署（生产方案）

**1. 部署到服务器（AWS/阿里云/腾讯云）**

```bash
# SSH到云服务器
ssh user@your-server.com

# 克隆项目
git clone <你的仓库>
cd supercoordination-mcp

# 安装依赖
npm install

# 使用PM2守护进程运行
npm install -g pm2
pm2 start src/server.js --name supercoordination
pm2 save
pm2 startup
```

**2. 配置域名（可选）**

```bash
# 假设你有域名 mcp.yourteam.com
# 配置Nginx反向代理
sudo nano /etc/nginx/sites-available/mcp

# 添加配置
server {
    listen 80;
    server_name mcp.yourteam.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
```

**3. 团队成员配置**

```json
{
  "mcpServers": {
    "supercoordination": {
      "type": "http",
      "url": "http://mcp.yourteam.com/mcp"
    }
  }
}
```

---

## 🔐 安全建议

### 基础安全（局域网）

在 `src/server.js` 中添加简单认证：

```javascript
// 添加API密钥验证中间件
const API_KEY = process.env.MCP_API_KEY || 'your-secret-key-here';

app.use('/mcp', (req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});
```

团队成员配置：
```json
{
  "mcpServers": {
    "supercoordination": {
      "type": "http",
      "url": "http://192.168.1.100:3000/mcp",
      "headers": {
        "x-api-key": "your-secret-key-here"
      }
    }
  }
}
```

### 生产安全（公网）

```bash
# 1. 使用环境变量
echo "MCP_API_KEY=$(openssl rand -hex 32)" > .env

# 2. 启用HTTPS
# 3. 添加速率限制
npm install express-rate-limit

# 4. 日志记录
npm install morgan
```

---

## 📋 团队成员快速检查清单

### ✅ 连接前检查

- [ ] 获取MCP服务器地址（从团队负责人）
- [ ] 确认网络可达性（ping测试）
- [ ] 安装Claude Code CLI
- [ ] 准备工作目录

### ✅ 配置步骤

```bash
# 1. 创建工作目录
mkdir -p /path/to/超协体MVP1.0代码库
cd /path/to/超协体MVP1.0代码库

# 2. 创建MCP配置
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "supercoordination": {
      "type": "http",
      "url": "http://你的服务器地址:3000/mcp"
    }
  }
}
EOF

# 3. 启动Claude Code
claude
```

### ✅ 验证连接

在Claude Code中依次测试：

```
# 1. 查看所有成员
列出所有成员

# 2. 注册自己
注册新成员：你的名字，技能包括你的技能列表，五行画像：你的五行分布

# 3. 查看所有任务
列出所有任务

# 4. 查看团队仪表盘
查看团队协作仪表盘，概览视图
```

---

## 🐛 常见问题

### Q1: 无法连接到MCP服务器

**检查步骤**:
```bash
# 1. 验证服务器运行
curl http://服务器IP:3000/health

# 2. 检查防火墙
# macOS
sudo pfctl -s rules

# 3. 检查端口占用
lsof -i :3000

# 4. 查看服务器日志
# 如果使用pm2
pm2 logs supercoordination
```

### Q2: 连接成功但工具不可用

```bash
# 检查MCP manifest
curl http://服务器IP:3000/mcp/manifest | jq .

# 应该返回10个工具的定义
```

### Q3: 局域网IP地址变化

**方案**: 设置静态IP地址

```bash
# macOS: 系统偏好设置 → 网络 → 高级 → TCP/IP → 配置IPv4: 手动
```

---

## 📞 团队协作最佳实践

### 1. 统一工作目录

所有成员使用相同的目录结构：
```
~/ClaudeWorkspace/
└── supercoordination-mcp/
    ├── .mcp.json          # MCP配置
    └── README.md          # 项目说明
```

### 2. 每日同步流程

```
早上：
1. 查看团队仪表盘
2. 查看我的任务
3. 更新昨日进度

工作中：
1. 创建新任务（如需要）
2. 实时更新进度
3. 查看团队五行平衡

晚上：
1. 更新最终进度
2. 记录遇到的问题
3. 准备明日计划
```

### 3. 通信规范

- 任务描述清晰具体
- 进度更新及时准确
- 五行属性标注正确
- 优先级合理设置

---

## 🎯 下一步

### 立即行动

1. **选择接入场景**（局域网/远程）
2. **按步骤配置**（5分钟）
3. **验证连接**（测试命令）
4. **开始协作**（创建真实任务）

### 给团队成员的邀请话术

```
嗨团队，

我搭建了一个基于AI的协作中枢——超协体MCP服务器 🌟

特点：
✅ 五行智能匹配 - 自动找到最适合的人做任务
✅ 自然语言操作 - 直接对话，无需学习命令
✅ 实时协作追踪 - 所有人看到同一个进度

接入只需3步（5分钟）：
1. 创建目录
2. 配置.mcp.json
3. 启动Claude Code

详细指南：团队成员接入指南.md

服务器地址：[待分享]
API Key：[待分享]

让我们一起进入人机协同新时代！🚀
```

---

**五行定位**: 🏔️ 土（连接基础）+ ⚙️ 金（协作规则）
**愿景**: 让每个团队成员都拥有AI助手，通过MCP中枢实现跨节点高效协同