skilled-feishu-mcp/CHERRY_STUDIO_INTEGRATION.md

A Model Context Protocol (MCP) server that integrates with Feishu's Open Platform APIs

# Cherry Studio 集成指南

本文档提供了将Skilled Feishu MCP服务器与Cherry Studio集成的详细指南。

## 最新版本 v1.0.5 更新

在最新的v1.0.5版本中，我们增强了对环境变量的支持，现在支持以下形式的环境变量：

- 所有大小写变体：`FEISHU_APP_ID`、`feishu_app_id`等
- 不同的分隔符格式：下划线(`_`)、连字符(`-`)、驼峰命名
- Lark别名支持：`LARK_APP_ID`、`lark_app_secret`等同于飞书凭证

这大大提高了与Cherry Studio集成的兼容性。

## Cherry Studio 配置选项

以下是几种推荐的配置方案，请从简单到复杂依次尝试：

### 方案1: 环境变量方式（推荐）

```json
{
  "skilled-feishu-mcp": {
    "isActive": true,
    "command": "npx",
    "args": [
      "skilled-feishu-mcp",
      "--stdio"
    ],
    "env": {
      "FEISHU_APP_ID": "您的飞书应用ID", 
      "FEISHU_APP_SECRET": "您的飞书应用密钥",
      "NODE_OPTIONS": "--no-warnings"
    },
    "name": "skilled-feishu-mcp",
    "description": "MCP server for Feishu document operations"
  }
}
```

### 方案2: 命令行参数方式

```json
{
  "skilled-feishu-mcp": {
    "name": "skilled-feishu-mcp",
    "description": "MCP server for Feishu document operations",
    "isActive": true,
    "command": "npx",
    "args": [
      "skilled-feishu-mcp",
      "--stdio",
      "--feishu-app-id",
      "您的飞书应用ID",
      "--feishu-app-secret",
      "您的飞书应用密钥"
    ]
  }
}
```

### 方案3: 使用node直接执行

```json
{
  "skilled-feishu-mcp": {
    "name": "skilled-feishu-mcp",
    "description": "MCP server for Feishu document operations",
    "isActive": true,
    "command": "node",
    "args": [
      "/usr/local/lib/node_modules/skilled-feishu-mcp/bin/cli.js",
      "--stdio"
    ],
    "env": {
      "FEISHU_APP_ID": "您的飞书应用ID", 
      "FEISHU_APP_SECRET": "您的飞书应用密钥"
    }
  }
}
```

## 故障排除

如果在集成过程中遇到问题，请按照以下步骤进行故障排除：

### 1. 错误消息：`settings.mcp.toolsLoadErrorMCP 服务器启动失败，请根据教程检查参数是否填写完整`

这个错误通常表示服务器启动失败。可能的原因包括：

1. 凭据问题：确保提供了正确的`FEISHU_APP_ID`和`FEISHU_APP_SECRET`
2. 包安装问题：尝试在命令行运行`npx -y skilled-feishu-mcp --stdio`测试包是否可用
3. 环境变量格式：尝试使用完全大写的`FEISHU_APP_ID`和`FEISHU_APP_SECRET`
4. 节点版本：确保Node.js版本 >= 18.0.0

#### 一些深度排除操作：

1. 检查skilled-feishu-mcp是否全局安装:
   ```bash
   npm list -g | grep skilled-feishu-mcp
   ```

2. 尝试命令行运行测试:
   ```bash
   FEISHU_APP_ID=您的应用ID FEISHU_APP_SECRET=您的密钥 npx skilled-feishu-mcp --stdio --verbose
   ```

3. 检查全局包的位置:
   ```bash
   which skilled-feishu-mcp
   ```

### 2. 错误消息：`McpError: MCP error -32000: Connection closed`

这个错误表示MCP服务器启动后连接关闭。可能的原因包括：

1. 服务器启动后崩溃：检查是否有使用不兼容的Node API
2. 凭据验证问题：双重检查飞书凭据是否正确
3. 参数解析错误：使用环境变量而不是命令行参数

## 版本变更

- v1.0.5：增强了环境变量处理，支持多种变体和格式
- v1.0.4：修复了与Cherry Studio兼容性问题，改进了参数处理
- v1.0.3：增强了错误处理和进程管理
- v1.0.2：转换为ES模块格式，增强命令行参数处理

## 联系与支持

如有问题，请联系项目维护者，或提交GitHub issue。

## 测试与验证

成功配置后，您应该能在Cherry Studio中看到skilled-feishu-mcp服务正常运行，且模型功能可以成功调用飞书API功能。