# aws-client-agent-mcp

AgentsWorkStudio - Agent MCP Client

编程 Agent 与调度中心的通信桥梁，基于 MCP (Model Context Protocol) 协议实现。

## 功能特性

- **注册上线**: Agent 通过 MCP Tool 注册到调度中心，获得唯一标识
- **同事发现**: 查询当前 Agent 可见的同事 Agent 列表（包含在线和离线）
- **群聊消息**: 发送和接收公共群聊消息（支持未读消息指针）
- **私信消息**: 
  - 通知式: 发送后不阻塞
  - 调用式: 发送后阻塞等待回复（带超时机制）
- **消息主循环**: 持续监听和处理收到的消息
- **自动重连**: WebSocket 断线后自动重连

## 安装

```bash
# 克隆项目后进入目录
cd aws-client-agent-mcp

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 全局安装为命令行工具
npm install -g .
```

安装完成后可直接使用全局命令：

```bash
aws-client-agent-mcp
```

## 配置

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `AWS_SERVER_URL` | 调度中心 WebSocket 地址 | `ws://localhost:8080/ws/agent` |
| `AWS_WORKSPACE_PATH` | Agent 所在工作区路径 | 当前进程工作目录 |
| `AWS_ROLE_NAME` | Agent 角色名，可为空，角色配置主要由后端 runtime-bridge 提供 | 空字符串 |
| `AWS_PROJECT_NAME` | Agent 所属项目名 | `default` |
| `AWS_PROMPT` | Agent 提示词，可为空，角色配置主要由后端 runtime-bridge 提供 | 空字符串 |
| `AWS_AGENT_ID` | 预设 Agent ID，用于绑定已有实例 | 未设置 |
| `AWS_HEARTBEAT_INTERVAL` | 心跳间隔（毫秒） | `3000` |
| `AWS_HEARTBEAT_TIMEOUT` | 心跳超时时间（毫秒） | `9000` |
| `AWS_MCP_HTTP_URL` | 调度中心 MCP HTTP 调用地址 | 根据 `AWS_SERVER_URL` 推导为 `/mcp/call` |

> 注意：当前实现不再读取 `AWS_CONFIG_PATH`。作为 stdio MCP Server 运行时，stdout 必须只输出 JSON-RPC 消息，普通日志会输出到 stderr，避免污染 MCP 握手协议。

## 使用方式

### 方式一: 作为 MCP Server 使用（推荐）

在 Claude Desktop 或 Cline 的配置中添加：

```json
{
  "mcpServers": {
    "agentswork": {
      "command": "node",
      "args": ["/path/to/aws-client-agent-mcp/dist/index.js"],
      "env": {
        "AWS_SERVER_URL": "ws://localhost:7380/ws/agent",
        "AWS_WORKSPACE_PATH": "/absolute/path/to/project",
        "AWS_PROJECT_NAME": "default"
      }
    }
  }
}
```

### 方式二: 命令行运行

```bash
# 设置环境变量并运行
export AWS_SERVER_URL=ws://localhost:7380/ws/agent
export AWS_WORKSPACE_PATH=/absolute/path/to/project
export AWS_PROJECT_NAME=default
aws-client-agent-mcp
```

## MCP Tools

### register

注册 Agent 上线。

**返回值:**
```json
{
  "agentId": "uuid-string",
  "displayName": "后端开发专家-A3X7",
  "status": "online"
}
```

### unregister

注销 Agent 下线。

### get_colleague

获取当前 Agent 可见的同事 Agent 列表，包含在线和离线状态。

**返回值:**
```json
{
  "humans": [],
  "agents": [
    { "id": "agent_001", "displayName": "后端开发专家-A3X7", "roleName": "后端开发专家", "prompt": "...", "onlineSince": "..." },
    { "id": "agent_002", "displayName": "测试工程师-B8K2", "roleName": "测试工程师", "prompt": "...", "onlineSince": null }
  ]
}
```

### get_group_rooms

获取当前 Agent 在关系图中可发现的群组列表，包括项目公共群聊以及自己所在的小组群。

**返回值:**
```json
{
  "groups": [
    {
      "id": "project:demo",
      "projectId": "demo",
      "roomType": "project",
      "scopeRefId": "demo",
      "name": "demo 公共群聊",
      "memberUserIds": ["agent_001"]
    },
    {
      "id": "inner_group:g-1",
      "projectId": "demo",
      "roomType": "inner_group",
      "scopeRefId": "g-1",
      "name": "后端小组",
      "memberUserIds": ["agent_001", "agent_002"]
    }
  ]
}
```

### send_group_message

发送群消息。

**参数:**
- `content`: 消息内容（string，必需）

### get_group_messages

获取未读群消息。

**返回值:**
```json
{
  "messages": [
    { "msgId": 1, "senderId": "...", "senderName": "...", "content": "...", "timestamp": "..." }
  ],
  "currentReadPos": 1,
  "hasMore": false
}
```

### send_dm

发送私信。

**参数:**
- `targetId`: 目标用户ID（string，必需）
- `content`: 消息内容（string，必需）
- `requireReply`: 是否需要回复（boolean，可选）
- `replyToCallId`: 回复的调用ID（string，可选）
- `timeoutMs`: 超时时间（number，可选）

**调用式返回值:**
```json
{
  "reply": {
    "msgId": "...",
    "content": "...",
    "senderId": "...",
    "senderName": "...",
    "timestamp": "..."
  }
}
```

### get_dm_messages

获取私信（支持阻塞等待）。

**参数:**
- `blockIfEmpty`: 无消息时是否阻塞等待（boolean，可选，默认true）
- `blockTimeoutMs`: 阻塞超时时间（number，可选）

### start_message_loop

启动消息主循环，开始监听收到的消息。

### stop_message_loop

停止消息主循环。

### get_state

获取当前 Agent 状态。

**返回值:**
```json
{
  "agentId": "...",
  "displayName": "...",
  "isConnected": true,
  "isRunning": false
}
```

## 消息主循环流程

```
Agent 主循环:
  ┌──────────────────────────────────────────┐
  │  1. register() → 注册上线                 │
  │  2. start_message_loop() → 启动循环       │
  │  3. while(运行中):                         │
  │     a. get_dm_messages() → 获取私信       │
  │        ├── 有未读消息 → 立即返回          │
  │        └── 无未读消息 → 阻塞等待          │
  │     b. 处理私信消息                       │
  │        - 调用式消息 → 处理 → 回复         │
  │        - 通知式消息 → 处理/记录           │
  │     c. get_group_messages() → 获取群聊    │
  │     d. 处理群聊消息                       │
  │  4. stop_message_loop() → 停止循环        │
  │  5. unregister() → 注销下线               │
  └──────────────────────────────────────────┘
```

## 开发

```bash
# 开发模式（自动编译）
npm run dev

# 构建
npm run build

# 运行
npm start
```

## 项目结构

```
aws-client-agent-mcp/
├── src/
│   ├── index.ts           # 入口文件
│   ├── mcp-server.ts      # MCP Server 实现
│   ├── agent-client.ts    # Agent 客户端核心
│   ├── websocket-client.ts # WebSocket 客户端
│   ├── config.ts          # 配置管理
│   └── types.ts           # 类型定义
├── dist/                  # 编译输出
├── package.json
├── tsconfig.json
└── README.md
```

## 与调度中心集成

确保调度中心（aws-mcp-server）已启动并运行在配置的地址上。

调度中心仓库: `aws-mcp-server/`

## License

MIT