Feishu MCP Server

Um servidor MCP com autenticação OAuth do Feishu integrada, implantável no Cloudflare Workers.

GitHub
87

Documentação

MCP Badge

Trust Score

Feishu MCP Server

Documentação em Inglês

Este é um servidor de Model Context Protocol (MCP) que suporta conexão remota, com autenticação OAuth do Feishu integrada.

Este projeto é uma modificação de cloudflare/ai/demos/remote-mcp-github-oauth, substituindo o OAuth do GitHub pelo OAuth do Feishu.

Você pode implantá-lo em sua própria conta Cloudflare e, após criar seu próprio aplicativo cliente OAuth do Feishu, ter um servidor MCP remoto totalmente funcional. Os usuários podem se conectar ao seu servidor MCP fazendo login com suas contas Feishu.

📋 Índice

🆚 Diferenças em relação ao MCP Server oficial do Feishu

Embora o Feishu oficial também tenha lançado um MCP Server, este projeto tem vantagens significativas nos seguintes aspectos:

🎯 Experiência de configuração zero

  • Este projeto: os usuários não precisam configurar nenhum parâmetro manualmente, usando user_access_token durante todo o processo, com renovação automática quando expira
  • Projeto oficial: exige que os usuários configurem vários parâmetros manualmente, com configuração complexa

🚀 Otimização extrema de usabilidade

  • Este projeto: otimiza profundamente o tamanho e a estrutura das ferramentas, especialmente funções complexas como criação de blocos de documentos e criação de blocos aninhados, garantindo uso normal em clientes como o Cursor
  • Projeto oficial: simples conversão de API para ferramentas MCP, algumas ferramentas são excessivamente grandes, com problemas de usabilidade no uso real

🌐 Infraestrutura de ponta

  • Suporta implantação em Cloudflare Workers, aproveitando a infraestrutura de computação de borda mais avançada do setor

✨ Recursos

  • 🎯 Experiência de configuração zero: os usuários não precisam configurar parâmetros manualmente, gerenciamento automático de user_access_token e renovação
  • 🔐 Autenticação OAuth do Feishu: verificação segura de identidade do usuário
  • 🌐 Servidor MCP remoto: suporta conexões de múltiplos clientes
  • 🚀 Cloudflare Workers: alto desempenho, implantação distribuída globalmente, aproveitando a infraestrutura de computação de borda mais avançada do setor
  • 🛠️ Conjunto de ferramentas profundamente otimizado: otimização especial de ferramentas complexas como criação de documentos e blocos aninhados, garantindo uso normal em vários clientes
  • 🔧 Suporte a desenvolvimento local: ambiente local para facilitar desenvolvimento e testes
  • ⚡ Usabilidade extrema: em comparação com o MCP Server oficial, melhora significativamente a experiência de uso real e a estabilidade

🚀 Início rápido

Pré-requisitos

  • Node.js 18+ e npm
  • Conta Cloudflare
  • Conta na plataforma aberta do Feishu

Instalação

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

# 安装依赖
npm install

🚀 Métodos de implantação

Implantação em produção

Etapa 1: Criar o aplicativo Feishu

  1. Acesse a plataforma aberta do Feishu e faça login
  2. Clique em "Painel do desenvolvedor" e crie um novo aplicativo
  3. Configure as permissões nas configurações do aplicativo:
    • Acesse "Permissões e funções" e adicione as seguintes permissões:

      • "Obter ID do usuário" (auth:user.id:read)

      • "Obter informações de tarefas do usuário" (task:task:read)

      • "Obter credenciais de autorização do usuário" (offline_access)

      • "Obter informações básicas do usuário" (user_profile)

        ...

  4. Anote seu ID do aplicativo e Segredo do aplicativo

Etapa 2: Configurar o ambiente 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"

Etapa 3: Atualizar o arquivo de configuração

Atualize a configuração do namespace KV no arquivo wrangler.toml usando o ID do KV obtido na etapa 2.

Etapa 4: Implantar o servidor

npm run deploy

Após a implantação, anote seu subdomínio real (será exibido nos logs de implantação).

Etapa 5: Configurar a URL de redirecionamento

Volte às configurações do aplicativo Feishu:

  1. Acesse "Configurações de segurança"
  2. Adicione a URL de redirecionamento: https://feishu-mcp-server.<your-actual-subdomain>.workers.dev/callback

Ambiente de desenvolvimento local

Configurar o ambiente local

  1. Configurar o aplicativo Feishu:

    • Adicione nas "Configurações de segurança" do aplicativo Feishu: http://localhost:8788/callback
    • Certifique-se de ter as permissões necessárias (iguais às do ambiente de produção)

  2. Criar arquivo de variáveis de ambiente: Crie o arquivo .dev.vars na raiz do projeto:

    FEISHU_APP_ID=your_development_feishu_app_id
FEISHU_APP_SECRET=your_development_feishu_app_secret
COOKIE_ENCRYPTION_KEY=any_random_string_here

Iniciar o servidor local

npm run dev

O servidor será executado em http://localhost:8788.

🔌 Integração com clientes

Testando com o Inspector

Teste seu servidor com o MCP Inspector oficial:

npx @modelcontextprotocol/inspector@latest

Endereços de conexão:

  • Ambiente de produção: https://feishu-mcp-server.<your-subdomain>.workers.dev/sse
  • Ambiente local: http://localhost:8788/sse

Usando o Cursor

Configure rapidamente com o botão de instalação com um clique:

Install MCP Server

Ou configure manualmente:

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

Usando o ChatWise

  1. Etapas de configuração:

    • Abra a interface de configurações do ChatWise
    • Navegue até as opções de ferramentas
    • Adicione entrada/saída de linha de comando (stdio)
    • Comando: npx -y mcp-remote ${URL}

  2. Endereços de conexão:

    • Local: http://localhost:8788/sse
    • Produção: https://feishu-mcp-server.<your-subdomain>.workers.dev/sse

  3. Primeiro uso:

    • Após salvar a configuração, a página de login OAuth do Feishu será aberta automaticamente
    • Após concluir a autorização, você poderá usar os recursos relacionados ao Feishu

🔐 Controle de acesso

  • Autenticação: usa OAuth do Feishu para autenticação de usuários
  • Escopo de permissões: todos os usuários Feishu autenticados podem acessar todas as ferramentas

📋 Roteiro de desenvolvimento de ferramentas

🚧 Em desenvolvimento atual (Documentos Feishu)

  • 🔧 Ferramentas auxiliares de desenvolvimento
    • ✅ Pesquisa e recuperação de conteúdo de documentos de desenvolvimento
  • 📄 Operações básicas de documentos
    • ✅ Obtenção da estrutura de árvore de blocos do documento
    • ✅ Obtenção do schema de parâmetros de criação de tipos de bloco
    • ✅ Criação de blocos de documento (suporta vários tipos de bloco)
    • ✅ Atualização do conteúdo de blocos de documento
    • ✅ Exclusão em lote de blocos de documento
  • 🔧 Recursos avançados de documentos
    • ✅ Criação e operação de tabelas
    • ✅ Upload e inserção de imagens, vídeos e arquivos
    • ✅ Recurso de importação Markdown
    • ✅ Upload e gerenciamento de materiais
    • ✅ Pesquisa de documentos

🎯 Planos futuros

  • 📊 Planilhas (Sheets)

    • 📋 Operações básicas de planilhas (criar, excluir, renomear)
    • 📋 Leitura e escrita de dados de células
    • 📋 Cálculo e aplicação de fórmulas
    • 📋 Criação e edição de gráficos
    • 📋 Filtragem e classificação de dados
    • 📋 Colaboração e gerenciamento de permissões

  • 🗃️ Tabelas multidimensionais (Base/Bitable)

    • 📋 Operações básicas de tabelas de dados
    • 📋 CRUD de registros (criar, ler, atualizar, excluir)
    • 📋 Gerenciamento de tipos de campos
    • 📋 Criação e configuração de visualizações
    • 📋 Configuração de regras de automação
    • 📋 Importação e exportação de dados

    ...

Legenda: ✅ Concluído | 🔄 Em desenvolvimento | 📋 Planejado

🛠️ Princípios técnicos

Componentes da arquitetura

OAuth Provider

Implementação completa de servidor OAuth 2.1, que lida com:

  • Autenticação de clientes MCP
  • Gerenciamento de conexão com o serviço OAuth do Feishu
  • Gerenciamento seguro de tokens no armazenamento KV

Durable MCP

Extensão MCP baseada em Cloudflare Durable Objects:

  • Gerenciamento de estado persistente
  • Armazenamento de contexto de autenticação
  • Acesso a informações do usuário via this.props
  • Disponibilidade condicional de ferramentas com base na identidade do usuário

MCP Remote

Suporta conexões remotas de clientes MCP:

  • Define o protocolo de comunicação cliente-servidor
  • Fornece uma forma estruturada de definição de ferramentas
  • Lida com serialização de requisições/respostas
  • Mantém conexões SSE

👨‍💻 Guia de desenvolvimento

Servidor MCP (alimentado por Cloudflare Workers)

Este projeto implementa papéis duplos de OAuth:

  • Atua como servidor OAuth para clientes MCP
  • Atua como cliente OAuth para o serviço OAuth do Feishu

Desenvolvimento de ferramentas

As ferramentas atuais usam tokens de acesso do usuário para autenticação, garantindo:

  • Acesso seguro à API do Feishu
  • Acesso a recursos com base nas permissões do usuário
  • Tratamento completo de erros e registro de logs

📝 Nota: certifique-se de configurar corretamente todas as variáveis de ambiente e as configurações do aplicativo Feishu antes da implantação. Se encontrar problemas, verifique as configurações de permissão do aplicativo Feishu e as configurações de URL de redirecionamento.

Star History

Star History Chart