yuppie-mcp-feishu 0.5.1
飞书MCP服务器 - 提供多维表格和电子表格的MCP工具
License: MIT
Requires Python: >=3.10
Keywords: bitable, feishu, integration, lark, mcp, model-context-protocol, spreadsheet

# 飞书MCP服务器

飞书（Feishu）MCP服务器 - 提供多维表格和电子表格的MCP工具

## 功能特性

- ✅ 自动token管理（2小时有效期自动刷新）
- ✅ 多维表格完整支持（10个工具）
- ✅ 所有参数使用JSON字符串格式
- ✅ 统一错误处理
- ✅ JSON格式响应

## 已实现功能

### 多维表格（Bitable）

**应用管理**：
- 创建多维表格应用
- 复制多维表格应用

**数据表操作**：
- 创建数据表

**记录操作**：
- 创建/更新/查询记录
- 批量创建/更新/获取/删除记录
- 支持分页查询

### 电子表格（Sheets）

待实现（计划17个工具）

## 安装

### 1. 克隆项目

```bash
git clone <repository-url>
cd yuppie-mcp-feishu
```

### 2. 配置环境变量

复制环境变量模板：

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入你的飞书应用凭证：

```bash
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
```

### 3. 安装依赖

```bash
uv sync
```

## 使用

### 测试运行

```bash
uv run python test_mcp.py
```

### 作为MCP服务器运行

```bash
uv run yuppie-mcp-feishu
```

或使用模块方式：

```bash
uv run python -m yuppie_mcp_feishu
```

## Claude Desktop配置

在Claude Desktop配置文件中添加：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "feishu": {
      "command": "/path/to/yuppie-mcp-feishu/.venv/bin/python",
      "args": ["-m", "yuppie_mcp_feishu"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

注意：将 `/path/to/yuppie-mcp-feishu` 替换为实际项目路径。

## 可用工具

所有复杂参数（对象、数组）均使用 **JSON 字符串** 格式传递，以避免 MCP 协议序列化问题。

### 多维表格数据表

#### `create_bitable_table`
创建数据表

**参数**：
- `app_token` (string): 多维表格的app_token
- `table_name` (string): 数据表名称
- `fields` (JSON string, 可选): 字段定义列表，例如: `[{"type":1,"name":"字段名"}]`

**返回**：JSON格式的数据表信息

### 多维表格应用

#### `create_bitable_app`
创建新的多维表格应用

**参数**：
- `name` (string): 多维表格名称
- `folder_token` (string, 可选): 文件夹token

**返回**：JSON格式的应用信息

#### `copy_bitable_app`
复制多维表格应用

**参数**：
- `app_token` (string): 要复制的应用token
- `name` (string): 新应用名称
- `folder_token` (string, 可选): 文件夹token

**返回**：JSON格式的应用信息

### 多维表格记录

#### `create_bitable_record`
创建单条记录

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `fields` (JSON string): 记录字段，例如: `{"字段名":"值"}`

#### `update_bitable_record`
更新单条记录

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `record_id` (string): 记录ID
- `fields` (JSON string): 要更新的字段，例如: `{"字段名":"新值"}`

#### `search_bitable_records`
查询记录（支持分页）

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `page_size` (int, 可选): 每页记录数（1-500）
- `page_token` (string, 可选): 分页token
- `filter` (JSON string, 可选): 过滤条件，例如: `{"conjunction":"and","conditions":[...]}`

#### `batch_create_bitable_records`
批量创建记录（最多1000条）

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `records` (JSON string): 记录列表，例如: `[{"fields":{"字段名":"值"}}]`

#### `batch_update_bitable_records`
批量更新记录（最多1000条）

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `records` (JSON string): 记录列表，例如: `[{"record_id":"xxx","fields":{"字段名":"新值"}}]`

#### `batch_get_bitable_records`
批量获取记录（最多100条）

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `record_ids` (JSON string): 记录ID列表，例如: `["id1","id2","id3"]`

#### `batch_delete_bitable_records`
批量删除记录

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `record_ids` (JSON string): 要删除的记录ID列表，例如: `["id1","id2","id3"]`

## 项目结构

```
src/yuppie_mcp_feishu/
├── __init__.py              # 主入口点
├── server.py                # MCP 服务器和工具路由
├── impl.py                  # 所有 API 实现
├── config.py                # 配置管理
└── client.py                # 飞书客户端管理
```

## 技术栈

- **Python**: >= 3.10
- **飞书SDK**: lark-oapi >= 1.5.2
- **MCP框架**: mcp >= 1.2.0（官方 MCP SDK）
- **包管理**: UV

## 开发

### 运行测试

本项目使用 **MCP 官方 SDK 测试方法**，通过 MCP 协议测试所有工具。

#### 快速开始

```bash
# 1. 配置测试环境变量
cp .env.example .env

# 编辑 .env 文件，添加测试用多维表格的 app_token
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
FEISHU_DEFAULT_APP_TOKEN=your_app_token_here  # 必需：用于测试的多维表格

# 2. 运行所有测试
PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/ -v

# 3. 运行单个测试文件
PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/test_create_bitable_record.py -v
```

#### 测试结构

```
tests/
├── conftest.py                    # MCP fixtures + 共享配置
└── yuppie_mcp_feishu/
    └── tools_mcp/                 # MCP 协议测试
        ├── test_create_bitable_record.py
        ├── test_update_bitable_record.py
        ├── test_search_bitable_records.py
        ├── test_batch_create_bitable_records.py
        ├── test_batch_update_bitable_records.py
        ├── test_batch_get_bitable_records.py
        └── test_batch_delete_bitable_records.py
```

#### 测试特点

- ✅ **使用 MCP 官方 SDK**：通过 `create_connected_server_and_client_session()` 创建测试会话
- ✅ **真实 API 调用**：直接连接飞书 API，无 mock
- ✅ **每个工具独立测试**：7个工具，7个测试文件，15个测试用例
- ✅ **参数验证**：每个工具都包含成功场景和参数验证测试

#### 测试命令

```bash
# 运行所有 MCP 测试
PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/ -v

# 运行特定工具的测试
PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/test_create_bitable_record.py -v

# 运行单个测试用例
PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/test_create_bitable_record.py::TestCreateBitableRecord::test_create_record_empty_fields -v

# 显示详细输出
PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/ -vv

# 列出所有测试（不执行）
PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/ --co -q
```

#### Pytest Fixtures

测试使用 pytest fixtures 自动管理测试数据：

```python
# 共享 fixtures（conftest.py）
test_config           → 测试配置（从 .env 读取）
default_app_token     → 默认测试应用 app_token
test_table_id         → 测试数据表 ID（session 级别）
test_record_id        → 单条测试记录 ID（function 级别）
test_record_ids       → 批量测试记录 ID（function 级别）

# MCP fixtures
mcp_server            → MCP server 实例
client_session        → MCP 客户端会话（已连接）
```

### 安装依赖

```bash
uv sync
```

### 添加新依赖

```bash
uv add <package-name>
```

## 文档

- [更新日志](CHANGELOG.md) - 版本变更历史
- [PyPI 发布指南](PUBLISH_TO_PYPI.md) - 如何发布到 PyPI
- [开发指南](CLAUDE.md) - Claude Code 开发指南

## 参考资料

- [飞书开放平台文档](https://open.feishu.cn/document)
- [飞书Python SDK](https://github.com/larksuite/oapi-sdk-python)
- [MCP协议文档](https://modelcontextprotocol.io/)
- [官方 MCP SDK](https://github.com/modelcontextprotocol/python-sdk)

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！