使用说明

项目简介

Lark AgentX 是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在将飞书账号转变为一个智能AI助手。它允许您通过简单的函数注册机制，让大模型能够理解和执行飞书中的指令，实现函数调用和消息处理等功能。无需配置传统的飞书机器人，您的个人飞书账号即可作为AI助手使用。

主要功能点

MCP函数调用框架: 基于 MCP 协议实现了函数调用框架，支持大模型通过飞书调用注册的函数。
简易函数注册: 通过装饰器 '@register_tool' 即可轻松注册自定义函数，只需定义函数和描述，无需手动处理函数匹配逻辑。
飞书消息监听与记录: 连接飞书 API，监听并记录所有接收到的消息（私聊和群聊），为上下文理解提供数据基础。
异步消息处理: 采用 'async/await' 模式进行异步通信，保证消息处理的效率。
数据持久化: 使用 SQLAlchemy 将飞书消息存储到 MySQL 数据库，方便后续分析和使用。
智能函数调用: AI 会根据用户输入的指令自动分析并调用最匹配的函数，实现智能化的功能扩展。
内置常用工具: 预置了多种实用工具函数，如讲笑话、获取时间、掷骰子、翻译等，开箱即用。

安装步骤

环境准备:
- 确保已安装 Python 3.10+ 和 Node.js 20+ 环境。
- 确保已安装 MySQL数据库 并运行。

克隆仓库:

git clone https://github.com/cv-cat/LarkAgentX.git
cd LarkAgentX

安装依赖:
- 使用本地环境：
```
pip install -r requirements.txt
```
  （Windows 用户可能需要额外安装 'pip install win-inet-pton==1.1.0'）
- 使用 Docker (可选，具体步骤请参考仓库 README)
配置环境变量:
- 复制 '.env.example' 文件并重命名为 '.env'。
- 修改 '.env' 文件，填入以下配置信息：
  - 'LARK_COOKIE': 必须配置，您的飞书账号 Cookie，用于连接飞书API (无需配置飞书机器人)。
  - 'DB_HOST', 'DB_PORT', 'DB_NAME', 'DB_USER', 'DB_PASSWORD': MySQL 数据库连接信息。
  - 'OPENAI_API_KEY', 'OPENAI_API_BASE_URL', 'OPENAI_MODEL': OpenAI API 配置信息，用于大模型交互和函数调用。
  - 'FUNCTION_TRIGGER_FLAG': 触发函数调用的指令前缀，默认为 '/run'，可自定义。

服务器配置 (MCP客户端配置)

MCP客户端需要配置以下信息以连接 Lark AgentX MCP 服务器：

{
  "serverName": "LARK_MCP_SERVER",  // MCP服务器名称，与代码中定义的一致
  "transport": "stdio",         // 使用标准输入输出流进行通信
  "command": "python",          // 启动服务器的命令，使用 Python 解释器
  "args": ["main.py"]           // 启动命令的参数，执行 main.py 入口文件
}

配置说明:

serverName: 必须设置为 'LARK_MCP_SERVER'，与 'app/core/mcp_server.py' 中 'FastMCP("LARK_MCP_SERVER")' 定义的名称一致。
transport: 设置为 'stdio'，表示 MCP 服务器通过标准输入输出流与客户端通信，这是 Lark AgentX MCP 服务器默认的传输方式。
command: 设置为 'python'，指定使用 Python 解释器来运行服务器。
args: 设置为 '["main.py"]'，指定执行 'main.py' 文件来启动 Lark AgentX MCP 服务器。

基本使用方法

启动服务器: 在项目根目录下运行命令：
```
python main.py
```
服务器将连接飞书并开始监听消息。
在飞书中使用: 在飞书中，您可以直接与您的飞书账号对话，使用指令前缀（默认为 '/run'）加上要执行的操作来调用函数。例如：
- '/run 讲个笑话' - 调用 'tell_joke' 函数，让AI助手讲一个笑话。
- '/run 今天几点了' - 调用 'get_time' 函数，获取当前时间。
- '/run 给张三发消息内容是你好' - 调用 'send_message' 函数，给名为“张三”的用户发送私信。
自定义函数: 您可以在 'app/core/mcp_server.py' 文件中，使用 '@register_tool' 装饰器添加自定义函数，并根据需要修改函数描述和参数。

注意事项

LARK_COOKIE 配置: 'LARK_COOKIE' 是连接飞书 API 的关键，请务必正确配置您的飞书账号 Cookie。
OpenAI API Key: 如果需要使用 AI 能力进行函数调用和智能回复，请配置 'OPENAI_API_KEY' 和相关的 API 地址及模型。
MySQL 数据库: 确保 MySQL 数据库服务正常运行，并且配置信息正确。

关键词