# lark-chat-mcp

飞书 ↔ Cursor / Claude **单会话**远程聊天（v0.1.0）

你在飞书发消息，本机 Agent 通过 MCP 收到并流式回复——**单群、单进程、零配置**。

## 能做什么

| 方向 | 行为 |
|------|------|
| 飞书 → Agent | `lark_chat_watch` 收消息，自动开 ack 流式卡 |
| Agent → 飞书 | `lark_chat_stream` / `lark_chat_progress` 流式更新卡片 |

- 暂不支持多群并行

## 如何使用

1. 配置好mcp，会话中`/mcp` 确认是 `Connected`
2. 输入：`> 持续监听飞书群 <随便起个群名> `
3. 然后就可以远程指挥你的`Claude/Cursor`了

## 前置

- Node.js 18+
- [lark-cli](https://open.feishu.cn) 已 `auth login`（user + bot 均 `ready`）
- 飞书应用已订阅 `im.message.receive_v1` 并发布

首次接入完整步骤见 [docs/how_to_work.md](docs/how_to_work.md)。

## 安装

### npm（推荐）

以 Claude Code 为例：

```bash
# 当前项目
claude mcp add lark-chat-mcp -- npx -y @eos./lark-chat-mcp

# 全局
claude mcp add lark-chat-mcp -s user -- npx -y @eos./lark-chat-mcp

claude mcp list
```

Cursor / Claude Desktop 配置：

```json
{
  "mcpServers": {
    "lark-chat-mcp": {
      "command": "npx",
      "args": ["-y", "@eos./lark-chat-mcp"]
    }
  }
}
```

重载 MCP 后 **新开 Agent 会话**，应看到 **4 个工具**。

### 源码开发

```bash
git clone https://github.com/gitByEOS/lark-chat-mcp
cd lark-chat-mcp
npm install
npm test    # 期望全部通过
```

本地调试时 `args` 用 **server.mjs 绝对路径**：

```json
{
  "mcpServers": {
    "lark-chat-mcp": {
      "command": "node",
      "args": ["/绝对路径/lark-chat-mcp/server.mjs"]
    }
  }
}
```

## MCP 工具

| 工具 | 作用 |
|------|------|
| `lark_chat_session` | `list` 列群 · `find` 搜群 · `create` 建群并绑定 |
| `lark_chat_watch` | 阻塞等消息；`timeout` 时立即再调（单次最长 30s） |
| `lark_chat_stream` | 流式卡片 `append` → `close` |
| `lark_chat_progress` | `step` 逐步汇报，`done=true` 关闭 |

## 单实例与事件消费

全机只能运行 **一个** `server.mjs`：

- 第二实例会因 `~/.lark-chat-mcp/server.lock` 直接退出
- 同进程并发 `watch` 返回 `watch_busy`

```bash
ps aux | grep server.mjs          # 应只有 1 个
lark-cli event status --json      # active_consumers 应为 1
```

## 环境变量（可选）

MCP 日常**不用配**。仅边缘场景：

| 变量 | 说明 |
|------|------|
| `LARK_PEER_OPEN_ID` | 群里只接收该用户（`ou_xxx`）的消息 |