Feishu MCP Server

Un servidor MCP con autenticación OAuth integrada de Feishu, desplegable en Cloudflare Workers.

GitHub
87
Prueba este MCPPatrocinado

Documentación

MCP Badge

Trust Score

Feishu MCP Server

English Documentation

Este es un servidor de Protocolo de Contexto de Modelo (MCP) que admite conexión remota, con autenticación OAuth de Feishu integrada.

Este proyecto se basa en cloudflare/ai/demos/remote-mcp-github-oauth, reemplazando el OAuth de GitHub por el OAuth de Feishu.

Puede implementarlo en su propia cuenta de Cloudflare y, después de crear su propia aplicación cliente OAuth de Feishu, tendrá un servidor MCP remoto completamente funcional. Los usuarios pueden conectarse a su servidor MCP iniciando sesión con su cuenta de Feishu.

📋 Índice

🆚 Diferencias con el servidor MCP oficial de Feishu

Aunque Feishu oficial también ha lanzado un servidor MCP, este proyecto tiene ventajas significativas en los siguientes aspectos:

🎯 Experiencia de configuración cero

  • Este proyecto: los usuarios no necesitan configurar ningún parámetro manualmente, utiliza user_access_token en todo momento, con renovación automática al expirar
  • Proyecto oficial: requiere que los usuarios configuren múltiples parámetros manualmente, configuración compleja

🚀 Optimización extrema de usabilidad

  • Este proyecto: optimiza profundamente el tamaño y la estructura de las herramientas, especialmente funciones complejas como la herramienta de creación de bloques de documentos y la herramienta de creación de bloques anidados, garantizando su correcto funcionamiento en clientes como Cursor
  • Proyecto oficial: simple conversión de API a herramientas MCP, algunas herramientas son demasiado grandes y tienen problemas de usabilidad en la práctica

🌐 Infraestructura de vanguardia

  • Admite implementación en Cloudflare Workers, disfrutando de la infraestructura de computación en el borde más avanzada de la industria

✨ Características

  • 🎯 Experiencia de configuración cero: los usuarios no necesitan configurar parámetros manualmente, gestión automática de user_access_token y renovación
  • 🔐 Autenticación OAuth de Feishu: verificación segura de identidad de usuario
  • 🌐 Servidor MCP remoto: admite conexiones de múltiples clientes
  • 🚀 Cloudflare Workers: alto rendimiento, implementación distribuida globalmente, disfrutando de la infraestructura de computación en el borde más avanzada de la industria
  • 🛠️ Conjunto de herramientas profundamente optimizado: optimiza especialmente herramientas complejas como creación de documentos y bloques anidados, garantizando su correcto funcionamiento en varios clientes
  • 🔧 Soporte de desarrollo local: entorno local para facilitar el desarrollo y las pruebas
  • ⚡ Usabilidad extrema: en comparación con el servidor MCP oficial, mejora significativamente la experiencia de uso real y la estabilidad

🚀 Inicio rápido

Requisitos previos

  • Node.js 18+ y npm
  • Cuenta de Cloudflare
  • Cuenta de la plataforma abierta de Feishu

Instalación

# 克隆仓库
git clone <repository-url>
cd open-feishu-mcp-server

# 安装依赖
npm install

🚀 Métodos de implementación

Implementación en producción

Paso 1: Crear una aplicación de Feishu

  1. Visite la plataforma abierta de Feishu e inicie sesión
  2. Haga clic en "Centro de desarrolladores" y cree una nueva aplicación
  3. Configure los permisos en la configuración de la aplicación:
    • Vaya a "Permisos y funciones" y agregue los siguientes permisos:

      • "Obtener ID de usuario" (auth:user.id:read)

      • "Obtener información de tareas del usuario" (task:task:read)

      • "Obtener credenciales de autorización del usuario" (offline_access)

      • "Obtener información básica del usuario" (user_profile)

        ...

  4. Anote su ID de aplicación y secreto de aplicación

Paso 2: Configurar el entorno de Cloudflare

# 设置必要的密钥
wrangler secret put FEISHU_APP_ID
wrangler secret put FEISHU_APP_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY  # 使用 openssl rand -hex 32 生成

# 创建 KV 命名空间
wrangler kv namespace create "OAUTH_KV"

Paso 3: Actualizar el archivo de configuración

Utilice el ID de KV obtenido en el paso 2 para actualizar la configuración del espacio de nombres KV en el archivo wrangler.toml.

Paso 4: Implementar el servidor

npm run deploy

Una vez completada la implementación, anote su subdominio real (se mostrará en los registros de implementación).

Paso 5: Configurar la URL de redirección

Vuelva a la configuración de la aplicación de Feishu:

  1. Vaya a "Configuración de seguridad"
  2. Agregue la URL de redirección: https://feishu-mcp-server.<your-actual-subdomain>.workers.dev/callback

Entorno de desarrollo local

Configurar el entorno local

  1. Configurar la aplicación de Feishu:

    • En la "Configuración de seguridad" de la aplicación de Feishu, agregue: http://localhost:8788/callback
    • Asegúrese de tener los permisos necesarios (igual que en producción)

  2. Crear el archivo de variables de entorno: Cree el archivo .dev.vars en el directorio raíz del proyecto:

    FEISHU_APP_ID=your_development_feishu_app_id
FEISHU_APP_SECRET=your_development_feishu_app_secret
COOKIE_ENCRYPTION_KEY=any_random_string_here

Iniciar el servidor local

npm run dev

El servidor se ejecutará en http://localhost:8788.

🔌 Integración de clientes

Pruebas con Inspector

Utilice el MCP Inspector oficial para probar su servidor:

npx @modelcontextprotocol/inspector@latest

Dirección de conexión:

  • Entorno de producción: https://feishu-mcp-server.<your-subdomain>.workers.dev/sse
  • Entorno local: http://localhost:8788/sse

Uso con Cursor

Configuración rápida mediante el botón de instalación con un clic:

Install MCP Server

O configuración manual:

{
  "mcpServers": {
    "feishu": {
      "url": "http://localhost:8788/sse"
    }
  }
}

Uso con ChatWise

  1. Pasos de configuración:

    • Abra la interfaz de configuración de ChatWise
    • Navegue a las opciones de herramientas
    • Agregue entrada/salida de línea de comandos (stdio)
    • Comando: npx -y mcp-remote ${URL}

  2. Dirección de conexión:

    • Local: http://localhost:8788/sse
    • Producción: https://feishu-mcp-server.<your-subdomain>.workers.dev/sse

  3. Primer uso:

    • Después de guardar la configuración, se abrirá automáticamente la página de inicio de sesión OAuth de Feishu
    • Una vez completada la autorización, podrá usar las funciones relacionadas con Feishu

🔐 Control de acceso

  • Autenticación: verificación de identidad de usuario mediante OAuth de Feishu
  • Alcance de permisos: todos los usuarios de Feishu autenticados pueden acceder a todas las herramientas

📋 Hoja de ruta de desarrollo de herramientas

🚧 En desarrollo actual (Documentos de Feishu)

  • 🔧 Herramientas auxiliares de desarrollo
    • ✅ Búsqueda y recuperación de contenido de documentos de desarrollo
  • 📄 Operaciones básicas de documentos
    • ✅ Obtención de la estructura de árbol de bloques de documentos
    • ✅ Obtención del esquema de parámetros de creación de tipos de bloques
    • ✅ Creación de bloques de documentos (admite varios tipos de bloques)
    • ✅ Actualización del contenido de bloques de documentos
    • ✅ Eliminación masiva de bloques de documentos
  • 🔧 Funciones avanzadas de documentos
    • ✅ Creación y operación de tablas
    • ✅ Carga e inserción de imágenes, videos y archivos
    • ✅ Función de importación de Markdown
    • ✅ Carga y gestión de materiales
    • ✅ Búsqueda de documentos

🎯 Planes futuros

  • 📊 Hojas de cálculo (Sheets)

    • 📋 Operaciones básicas de hojas de trabajo (crear, eliminar, renombrar)
    • 📋 Lectura y escritura de datos de celdas
    • 📋 Cálculo y aplicación de fórmulas
    • 📋 Creación y edición de gráficos
    • 📋 Filtrado y ordenación de datos
    • 📋 Colaboración y gestión de permisos

  • 🗃️ Tablas multidimensionales (Base/Bitable)

    • 📋 Operaciones básicas de tablas de datos
    • 📋 Creación, eliminación, actualización y consulta de registros
    • 📋 Gestión de tipos de campos
    • 📋 Creación y configuración de vistas
    • 📋 Configuración de reglas de automatización
    • 📋 Importación y exportación de datos

    ...

Leyenda: ✅ Completado | 🔄 En desarrollo | 📋 Planificado

🛠️ Principios técnicos

Componentes de la arquitectura

OAuth Provider

Implementación completa del servidor OAuth 2.1, que maneja:

  • Autenticación de clientes MCP
  • Gestión de conexión del servicio OAuth de Feishu
  • Gestión segura de tokens en el almacenamiento KV

Durable MCP

Extensión MCP basada en Cloudflare Durable Objects:

  • Gestión de estado persistente
  • Almacenamiento de contexto de autenticación
  • Acceso a información de usuario mediante this.props
  • Disponibilidad condicional de herramientas según la identidad del usuario

MCP Remote

Admite conexiones de clientes MCP remotos:

  • Define el protocolo de comunicación cliente-servidor
  • Proporciona una forma estructurada de definir herramientas
  • Maneja la serialización de solicitudes/respuestas
  • Mantiene conexiones SSE

👨‍💻 Guía de desarrollo

Servidor MCP (impulsado por Cloudflare Workers)

Este proyecto implementa un doble rol OAuth:

  • Actúa como servidor OAuth para clientes MCP
  • Actúa como cliente OAuth para el servicio OAuth de Feishu

Desarrollo de herramientas

Las herramientas actuales utilizan tokens de acceso de usuario para la autenticación, garantizando:

  • Acceso seguro a la API de Feishu
  • Acceso a funciones basado en permisos de usuario
  • Manejo completo de errores y registro de actividades

📝 Nota: asegúrese de configurar correctamente todas las variables de entorno y la configuración de la aplicación de Feishu antes de la implementación. Si encuentra problemas, verifique la configuración de permisos de la aplicación de Feishu y la configuración de la URL de redirección.

Star History

Star History Chart