Feishu OAuth 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

Servidor MCP da Feishu

Documentação em Inglês

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

Este projeto foi modificado a partir de cloudflare/ai/demos/remote-mcp-github-oauth, substituindo o OAuth do GitHub pelo OAuth da Feishu.

Você pode implantá-lo na sua própria conta Cloudflare e, após criar seu próprio aplicativo cliente OAuth da 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 servidor MCP oficial da Feishu

Embora a Feishu também tenha lançado um servidor MCP oficial, este projeto apresenta 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 ao expirar
  • 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 adequado em clientes como Cursor
  • Projeto oficial: simples conversão de API para ferramentas MCP, algumas ferramentas são grandes demais e apresentam problemas de usabilidade na prática

🌐 Infraestrutura de ponta

  • Suporte para 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 da Feishu: verificação segura de identidade do usuário
  • 🌐 Servidor MCP remoto: suporte a múltiplas conexões de clientes
  • 🚀 Cloudflare Workers: implantação de alto desempenho e distribuída globalmente, aproveitando a infraestrutura de computação de borda mais avançada do setor
  • 🛠️ Conjunto de ferramentas profundamente otimizado: otimização especial para ferramentas complexas como criação de documentos e blocos aninhados, garantindo uso adequado em vários clientes
  • 🔧 Suporte a desenvolvimento local: ambiente local para facilitar o desenvolvimento e os testes
  • ⚡ Usabilidade extrema: experiência de uso e estabilidade significativamente melhores em comparação ao servidor MCP oficial

🚀 Início rápido

Pré-requisitos

  • Node.js 18+ e npm
  • Conta Cloudflare
  • Conta na plataforma aberta da 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 aplicativo Feishu

  1. Acesse a plataforma aberta da Feishu e faça login
  2. Clique em "Console 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 credencial 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

Use o ID do KV obtido na etapa 2 para atualizar a configuração do namespace KV no arquivo wrangler.toml.

Etapa 4: Implantar o servidor

npm run deploy

Após a implantação, anote seu subdomínio real (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:

    • Nas "Configurações de segurança" do aplicativo Feishu, adicione: http://localhost:8788/callback
    • Garanta que as permissões necessárias estejam disponíveis (mesmas da produção)

  2. Criar o arquivo de variáveis de ambiente: Na raiz do projeto, crie o arquivo .dev.vars:

    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

Teste com o Inspector

Use o MCP Inspector oficial para testar seu servidor:

npx @modelcontextprotocol/inspector@latest

Endereço de conexão:

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

Uso com Cursor

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

Install MCP Server

Ou configure manualmente:

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

Uso com ChatWise

  1. Etapas de configuração:

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

  2. Endereço 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 da Feishu será aberta automaticamente
    • Após concluir a autorização, você poderá usar os recursos relacionados à Feishu

🔐 Controle de acesso

  • Autenticação: usa OAuth da Feishu para verificar a identidade do usuário
  • 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 da árvore de blocos do documento
    • ✅ Obtenção do schema de parâmetros de criação por tipo de bloco
    • ✅ Criação de blocos de documento (suporta vários tipos de blocos)
    • ✅ 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
    • 📋 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 gerencia:

  • Autenticação de clientes MCP
  • Gerenciamento de conexão com o serviço OAuth da 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

Suporte a conexões remotas de clientes MCP:

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

👨‍💻 Guia de desenvolvimento

Servidor MCP (com suporte a Cloudflare Workers)

Este projeto implementa um duplo papel OAuth:

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

Desenvolvimento de ferramentas

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

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

📝 Nota: garanta que todas as variáveis de ambiente e configurações do aplicativo Feishu estejam corretamente definidas antes da implantação. Em caso de problemas, verifique as configurações de permissões do aplicativo Feishu e a URL de redirecionamento.

Histórico de estrelas

Star History Chart