Skip to main content
Glama
Wulnut

lark-agent

by Wulnut
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Lark Agent (MCP Server)

CI

这是一个基于 Model Context Protocol (MCP) 构建的飞书 (Lark/Feishu) 智能代理服务。它采用 双模运行 (Dual-Mode) 架构，既是一个标准 MCP Server，也通过 FastAPI 暴露 HTTP API，完美支持 AI 助手 (Cursor/Claude) 调用和自动化工作流 (n8n) 集成。

✨ 核心特性

  • 双模运行:

    • MCP Mode: 运行在主进程，通过 Stdio 协议与 Cursor、Claude Desktop 等 IDE/客户端无缝集成。

    • HTTP Mode: 运行在后台子进程，通过 FastAPI 暴露标准的 RESTful 接口，适配 n8n、Zapier 等 Webhook 触发器。

  • 飞书项目全集成: 支持跨项目的任务 CRUD、高级过滤查询、字段元数据解析。

  • 企业级架构:

    • Async First: 全异步架构，基于 asyncio 和 httpx 实现极高性能。

    • Metadata Manager: 具备 5 层缓存机制，自动解析飞书项目中的复杂字段 Key/Value，实现零硬编码。

    • Provider 模式: 业务逻辑与底层飞书 SDK/API 彻底解耦，易于扩展。

    • 自动重试 & 脱敏: 完善的错误重试机制（指数退避）及敏感信息脱敏保护。

  • 多重认证支持: 支持 Static Token（快速上手）和 Plugin Authentication（企业生产推荐）。

Related MCP server: TickTick MCP Server

🏗️ 系统架构

flowchart TD
    subgraph Clients ["客户端层"]
        CURSOR["Cursor / Claude (IDE)"]
        N8N["n8n / Workflows (HTTP)"]
    end

    subgraph Agent ["Lark Agent (Dual-Mode)"]
        direction TB
        MAIN["main.py (Process Manager)"]
        
        subgraph MCP_PROC ["MCP 进程 (Main)"]
            MCP_STDIO["FastMCP (Stdio Transport)"]
            TOOLS["MCP Tools (Python Functions)"]
        end
        
        subgraph HTTP_PROC ["HTTP 进程 (Child)"]
            FASTAPI["FastAPI (Port 8002)"]
            WRAPPER["Call Tool Wrapper"]
        end
        
        MAIN --> MCP_PROC
        MAIN --> HTTP_PROC
        MCP_STDIO --> TOOLS
        FASTAPI --> WRAPPER
        WRAPPER --> TOOLS
    end

    subgraph Core ["能力核心层"]
        PROVIDER["WorkItemProvider"]
        META["MetadataManager (L1-L5 Cache)"]
        AUTH["AuthManager (Token Cache)"]
    end

    TOOLS --> PROVIDER
    PROVIDER --> META
    PROVIDER --> AUTH
    AUTH --> FEISHU_API["Feishu / Lark API"]

🛠️ 可用工具 (MCP Tools)

工具名

功能描述

核心业务场景

list_projects

列出所有可用项目及 Key

初始探索、查找项目 ID

create_task

创建单条工作项

快速记录 Bug、新增需求

get_tasks

全方位过滤查询工作项

查看我的任务、列出 P0 Bug

get_task_detail

获取工作项完整详情

查看任务描述、属性详情

update_task

更新单个工作项字段

修改状态、指派负责人

batch_update_tasks

[NEW] 批量更新多个工作项

批量结单、批量改优先级

get_task_options

查询字段可用选项

确认状态流转、查看优先级列表

🚀 快速开始

方式一：通过 uv tool install（推荐，最简单）

# 1. 安装
uv tool install --from git+https://github.com/Wulnut/lark_agent lark-agent

# 2. 配置环境变量 (见下方配置说明)
# 3. 直接运行
lark-agent

方式二：从源码运行（开发模式）

# 1. 克隆与进入目录
git clone https://github.com/Wulnut/lark_agent.git && cd lark_agent

# 2. 安装依赖并同步环境
uv sync

# 3. 运行服务
uv run main.py

⚙️ 环境配置

在项目根目录创建 .env 文件：

# --- 飞书项目配置 (必须) ---
FEISHU_PROJECT_USER_KEY=your_user_key

# 方案 A: 插件认证 (企业推荐，支持自动续期)
FEISHU_PROJECT_PLUGIN_ID=your_plugin_id
FEISHU_PROJECT_PLUGIN_SECRET=your_plugin_secret

# 方案 B: 静态 Token (个人测试，有效期 24h)
# FEISHU_PROJECT_USER_TOKEN=your_token

# --- 飞书机器人配置 (可选，用于 IM 通讯) ---
LARK_APP_ID=your_app_id
LARK_APP_SECRET=your_app_secret

# --- 系统配置 ---
LOG_LEVEL=INFO
FEISHU_PROJECT_KEY=默认项目KEY (可选)

🔌 客户端集成

1. Cursor IDE 配置

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "lark-agent": {
      "command": "lark-agent"
    }
  }
}

2. n8n / HTTP 调用指南

服务启动后，HTTP 端口默认为 8002。通过 POST /call_tool 端点可以调用所有 MCP 工具。

基础信息:

  • URL: http://localhost:8002/call_tool

  • Method: POST

  • Headers: Content-Type: application/json

常用请求示例:

1. 列出项目 (list_projects)

{
  "tool_name": "list_projects",
  "parameters": {}
}

2. 创建任务 (create_task)

{
  "tool_name": "create_task",
  "parameters": {
    "project": "SR6D2VA-7552-Lark",
    "work_item_type": "Issue管理",
    "name": "修复登录页面 Bug",
    "priority": "P0",
    "assignee": "张三"
  }
}

3. 查询任务 (get_tasks)

{
  "tool_name": "get_tasks",
  "parameters": {
    "project": "项目名称或Key",
    "name_keyword": "登录",
    "status": "进行中",
    "page_size": 20
  }
}

4. 获取详情 (get_task_detail)

{
  "tool_name": "get_task_detail",
  "parameters": {
    "issue_id": 123456789
  }
}

5. 更新任务 (update_task)

{
  "tool_name": "update_task",
  "parameters": {
    "issue_id": 123456789,
    "status": "已完成",
    "priority": "P1",
    "fields_json": "{\"SoC Vendor\": \"Amlogic\", \"DDR Size\": \"4GB\"}"
  }
}

6. 批量更新 (batch_update_tasks)

{
  "tool_name": "batch_update_tasks",
  "parameters": {
    "issue_ids": [10001, 10002], 
    "status": "已完成",
    "priority": "P1"
  }
}

7. 查询字段选项 (get_task_options)

{
  "tool_name": "get_task_options",
  "parameters": {
    "field_name": "status",
    "project": "项目名称"
  }
}

🧪 测试与质量

本项目严格遵循 TDD (测试驱动开发)。

  • 单元测试: 覆盖核心 Provider、Metadata 及授权逻辑。

  • 模拟环境: 使用 respx 拦截 HTTP 请求，无需真实 Token 即可运行。

  • 运行测试: uv run pytest (当前 135+ 测试用例全部通过)。

📏 开发规范

  • 异步规范: 所有 I/O 必须 await。

  • 零硬编码: 必须通过 MetadataManager 解析字段别名。

  • 错误过滤: 确保敏感堆栈信息不透传给 LLM。

📂 项目结构

src/
├── core/           # 核心逻辑 (Auth, Config, Cache, Client)
├── providers/      # 业务 Provider (Project, Meta Managers)
├── schemas/        # Pydantic 数据模型 (API 交互标准)
├── http_server.py  # HTTP 包装层 (FastAPI)
├── mcp_server.py   # MCP 接口定义与工具注册
main.py             # 双模启动入口 & 进程管理

📄 许可

MIT License. 版权所有 © 2026 Wulnut.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
1dRelease cycle
2Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Wulnut/lark_agent'

If you have feedback or need assistance with the MCP directory API, please join our Discord server