Feishu MCP Server

Acesse e gerencie documentos do Feishu para ferramentas de codificação de IA, permitindo recuperação, edição e busca de conteúdo estruturado.

GitHub

739

Documentação

Servidor MCP do Feishu

Fornece acesso, edição e processamento estruturado de documentos do Feishu para Cursor, Windsurf, Cline e outras ferramentas de codificação orientadas por IA, além de suporte ao gerenciamento de tarefas do Feishu e consulta de informações de usuários, implementado com base no servidor Model Context Protocol.

Agora com suporte à ferramenta CLI independente feishu-tool, que permite chamar todas as ferramentas do Feishu diretamente no terminal ou em scripts, sem a necessidade de iniciar o servidor MCP. Combinado com o Feishu-Skill, permite que agentes de IA como o Claude Code selecionem automaticamente a forma mais adequada de operar o Feishu.

Este projeto permite que ferramentas de codificação com IA possam:

Processamento de documentos: obter, compreender, criar e editar documentos do Feishu diretamente, aumentando significativamente a inteligência e a eficiência do processamento de documentos
Gerenciamento de tarefas: listar, criar, atualizar e excluir tarefas do Feishu, com suporte a subtarefas e gerenciamento de membros (requer autenticação de usuário)
Informações de usuários: pesquisar por nome ou obter usuários do Feishu em lote por ID, facilitando a atribuição de tarefas e a colaboração em documentos (requer autenticação de usuário)

Cobertura completa do fluxo de uso real dos documentos do Feishu, ajudando você a utilizar eficientemente os recursos documentais:

Obtenção de diretórios de pastas: obtenha e navegue rapidamente por todos os documentos nas pastas do Feishu, facilitando o gerenciamento e a busca geral.
Obtenção e compreensão de conteúdo: suporte à leitura de conteúdo em múltiplas dimensões, como estruturada, em blocos e rich text, permitindo que a IA compreenda com precisão o contexto do documento.
Criação e edição inteligentes: crie automaticamente novos documentos, gere e edite conteúdo em lote, atendendo a diversas necessidades de escrita.
Busca e pesquisa eficientes: busca integrada por palavras-chave, ajudando você a encontrar rapidamente as informações desejadas em grandes volumes de documentos.
Gerenciamento de tarefas e consulta de usuários: suporte a operações CRUD de tarefas do Feishu e busca de informações de usuários, facilitando a associação de tarefas e pessoas nos documentos.

Este projeto permite que você realize obtenção, edição e busca inteligentes no fluxo de uso diário dos documentos do Feishu, além de expandir os recursos de gerenciamento de tarefas e usuários, melhorando a eficiência e a experiência no processamento de conteúdo.

💡Recomendação de projeto:

Ao usar o Claude Code, é recomendado combiná-lo com o claude-ip-guard — que detecta automaticamente a localização geográfica do IP e bloqueia acessos de regiões restritas, prevenindo o banimento do Claude devido a mudanças de rede.

🎬 Vídeo de demonstração de uso

Você pode entender o efeito prático e o fluxo de operação do MCP através dos seguintes vídeos:

⭐ Dê um Star neste projeto para receber em primeira mão os novos recursos e atualizações importantes! Acompanhar o projeto garante que você não perca nenhum novo recurso, correção ou otimização, ajudando você a usá-lo de forma contínua e eficiente. Seu apoio também nos ajuda a melhorar e desenvolver o projeto. ⭐

🛠️ Detalhes das funcionalidades das ferramentas

Categoria de função	Nome da ferramenta	Descrição	Cenário de uso	Status
Gerenciamento de documentos	`create_feishu_document`	Criar um novo documento do Feishu	Criar um documento do zero	✅ Concluído
	`get_feishu_document_info`	Obter informações básicas do documento	Verificar a existência do documento e as permissões	✅ Concluído
	`get_feishu_document_blocks`	Obter a estrutura de blocos do documento	Entender a estrutura hierárquica do documento	✅ Concluído
Edição de conteúdo	`batch_create_feishu_blocks`	Criar vários blocos em lote	Criar conteúdo contínuo com eficiência	✅ Concluído
	`update_feishu_block_text`	Atualizar o conteúdo de texto dos blocos	Modificar conteúdo existente	✅ Concluído
	`delete_feishu_document_blocks`	Excluir blocos do documento	Limpar e reestruturar o conteúdo do documento	✅ Concluído
Gerenciamento de pastas	`get_feishu_folder_files`	Obter a lista de arquivos da pasta	Navegar pelo conteúdo da pasta	✅ Concluído
	`create_feishu_folder`	Criar nova pasta	Organizar a estrutura de documentos	✅ Concluído
Função de busca	`search_feishu_documents`	Buscar documentos	Encontrar conteúdo específico	✅ Concluído
Funções de ferramentas	`get_feishu_document_info`	Obter informações de documentos wiki	Converter links Wiki em IDs de documentos, criar subnós de wiki	✅ Concluído
	`get_feishu_image_resource`	Obter recursos de imagem	Baixar imagens de documentos	✅ Concluído
	`get_feishu_whiteboard_content`	Obter conteúdo do quadro	Obter elementos gráficos e estrutura do quadro (fluxogramas, mapas mentais, etc.)	✅ Concluído
Recursos avançados	`create_feishu_table`	Criar e editar tabelas	Exibição de dados estruturados	✅ Concluído
	Inserção de fluxogramas	Suporte a fluxogramas e mapas mentais	Organização e visualização de fluxos	✅ Concluído
	Inserção de fluxogramas (formato de quadro)	Suporte a fluxogramas e mapas mentais	Organização e visualização de fluxos	✅ Concluído
Inserção de imagens	`upload_and_bind_image_to_block`	Suporte à inserção de imagens locais e remotas	Modificar o conteúdo do documento	✅ Concluído
	Suporte a fórmulas	Suporte a fórmulas matemáticas	Documentos acadêmicos e técnicos	✅ Concluído

Gerenciamento de tarefas	`list_feishu_tasks`	Listar tarefas pelas quais sou responsável	Visualizar tarefas pendentes/concluídas	✅ Concluído
	`create_feishu_task`	Criar tarefas em lote (incluindo subtarefas)	Criar novas tarefas, dividir subtarefas	✅ Concluído
	`update_feishu_task`	Atualizar tarefas	Modificar conteúdo, membros, lembretes	✅ Concluído
	`delete_feishu_task`	Excluir tarefas em lote	Limpar tarefas	✅ Concluído
Informações de usuários	`get_feishu_users`	Pesquisar por nome ou obter usuários em lote por ID	Encontrar membros, atribuir tarefas	✅ Concluído

🎨 Recursos de estilo suportados (suporta basicamente todos os formatos de markdown)

Estilos de texto: negrito, itálico, sublinhado, tachado, código inline
Cores de texto: cinza, marrom, laranja, amarelo, verde, azul, roxo
Alinhamento: alinhado à esquerda, centralizado, alinhado à direita
Níveis de título: suporte a títulos de nível 1 a 9
Blocos de código: suporte a realce de sintaxe para várias linguagens de programação
Listas: listas ordenadas (numeradas), listas não ordenadas (com marcadores)
Imagens: suporte a imagens locais e imagens da web
Fórmulas: inserir fórmulas matemáticas em blocos de texto, com suporte à sintaxe LaTeX
Gráficos mermaid: suporte a fluxogramas, diagramas de sequência, mapas mentais, diagramas de classes, gráficos de pizza, etc.
Tabelas: suporte à criação de tabelas com múltiplas linhas, onde as células podem conter vários tipos de conteúdo, como texto, títulos, listas, blocos de código, etc.
Quadro de documentos do Feishu: suporte à criação de quadros nos documentos do Feishu, oferecendo conteúdo mais rico e diversificado.

📈 Plano semanal: melhorando a eficiência das ferramentas

Conjunto de ferramentas simplificado: 21 ferramentas → 13 ferramentas, removendo redundâncias e focando nas funcionalidades principais 0.0.15 ✅
Descrições otimizadas: 7000+ tokens → 3000+ tokens, simplificando prompts e economizando tokens de requisição 0.0.15 ✅
Aprimoramento em lote: novas atualizações em lote e upload de imagens em lote, aumentando a eficiência de operações únicas em 50% 0.0.15 ✅
Otimização de fluxo: reduzir chamadas em múltiplas etapas, permitindo concluir tarefas complexas com um clique
Suporte a vários tipos de credenciais: incluindo tenant_access_token e user_access_token, atendendo às necessidades de autenticação em diferentes cenários (Configuração do aplicativo Feishu alterada) 0.0.16 ✅.
Suporte ao login de usuários do cursor: facilitando a autenticação de usuários na plataforma cursor. Não será feito, desnecessário ❌
Suporte a gráficos mermaid: fluxogramas, diagramas de sequência, etc., enriquecendo o conteúdo dos documentos 0.1.11 ✅
Suporte à criação de tabelas: criação de tabelas complexas contendo vários tipos de blocos, com suporte a controle de estilos 0.1.2 ✅
Suporte à autenticação de múltiplos usuários do Feishu: uma pessoa implanta, várias pessoas podem usar 0.1.3 ✅
Suporte à atualização automática do user_access_token: sem necessidade de autorizações frequentes, melhorando a experiência de uso 0.1.6 ✅
Suporte à validação do escopo de autorização: validação da autorização do aplicativo para garantir que atenda aos requisitos das ferramentas atuais. Se não atender, serão fornecidas orientações amigáveis para que os usuários possam usar sem problemas 0.1.7 ✅
Suporte à criação de conteúdo em quadro: comparado aos gráficos Mermaid, o quadro pode exibir conteúdo mais rico e diversificado, proporcionando uma experiência visual mais amigável e agradável (Configuração do aplicativo Feishu alterada) 0.1.7 ✅
Extrair feishuAppId e feishuAppSecret das variáveis de ambiente: separar a configuração do Feishu das variáveis de ambiente, para que possa ser definida em clientes como o cursor, permitindo que um serviço seja compartilhado por vários times.
Suporte à base de conhecimento e à biblioteca de documentos pessoais: implementação de travessia de nós, criação de nós, criação de arquivos, busca, etc., na base de conhecimento e na biblioteca de documentos pessoais (Configuração do aplicativo Feishu alterada) 0.1.8 ✅
Notificação de atualização de versão: fornecer avisos e explicações relevantes aos usuários quando novas versões forem lançadas.
Correção do problema de autenticação de usuário no modo stdio: correção da falha de autenticação de usuário do Feishu no modo stdio 0.1.9 ✅
Verificação de permissões configurável: tornar a verificação de permissões uma opção configurável, controlada pela variável de ambiente FEISHU_SCOPE_VALIDATION ou pelo parâmetro de linha de comando --feishu-scope-validation, habilitada por padrão, atendendo a diferentes cenários de uso 0.2.0 ✅
**Otimização do diretório de cache: salvar tokens e outros caches no diretório de configuração do sistema 0.2.2 ✅ Agradecemos as sugestões e contribuições de código dos amigos Molunerfinn, leeeezx e Master-cai
Otimização do código relacionado ao mcpTool: reconstrução da estrutura do código para estabelecer a base para a adição de mais funcionalidades no futuro 0.2.3 ✅
Suporte ao gerenciamento de tarefas: listar, criar, atualizar e excluir tarefas do Feishu, com suporte a subtarefas e gerenciamento de membros 0.2.4 ✅
Suporte à consulta de informações de usuários: pesquisar por nome ou obter usuários em lote por ID, facilitando a atribuição de tarefas e a colaboração em documentos 0.2.4 ✅
Extração da camada de API de ferramentas: criação de uma nova camada de API de ferramentas, correspondendo individualmente à camada de ferramentas, unificando validação de parâmetros, conversão de dados, mapeamento de erros, etc. ✅
Compatibilidade com o modo CLI: suporte à chamada via linha de comando feishu-tool <tool-name> '<json>', facilitando cenários de scripts e automação 0.2.6 ✅
Skill concluído: fornecimento do Feishu-Skill, orientando agentes de IA como o Claude Code a usar o CLI feishu-mcp em cenários apropriados 0.2.6 ✅

🔧 Tutorial de configuração do Feishu

⚠️ Aviso importante: antes de começar a usar, é obrigatório concluir a configuração do aplicativo Feishu; caso contrário, a ferramenta não funcionará corretamente.

Instruções sobre como criar um aplicativo Feishu e obter as credenciais do aplicativo podem ser encontradas no tutorial oficial.

Etapas detalhadas de configuração do aplicativo Feishu: para obter um guia detalhado sobre como registrar um aplicativo Feishu, configurar permissões e adicionar permissões de acesso a documentos, consulte o tutorial passo a passo FEISHU_CONFIG.md.

🏃‍♂️ Início rápido

Método 1: Execução rápida com NPM

npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥> --feishu-auth-type=<tenant/user> --enabled-modules=<document,task>

Método 2: Execução local

Clonar o repositório

git clone https://github.com/cso1z/Feishu-MCP.git
cd Feishu-MCP

Configurar as variáveis de ambiente (copie uma cópia de .env.example e salve como arquivo .env)
Editar o arquivo .env Encontre o arquivo .env no diretório raiz do projeto e abra-o com qualquer editor de texto, preenchendo as credenciais do seu aplicativo Feishu:
```
FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx
PORT=3333
FEISHU_AUTH_TYPE=tenant/user
FEISHU_ENABLED_MODULES=document,task
```
Executar o servidor

Método 1: Execução local
- Instalar dependências
```
pnpm install
```
- Iniciar o serviço
```
pnpm run dev
```
Método 2: Usando Docker Compose
- Iniciar o serviço
```
docker-compose up -d
```
- Visualizar logs
```
docker-compose logs -f
```

🖥️ Ferramenta CLI feishu-tool

A partir da versão 0.2.5, o pacote npm feishu-mcp inclui o CLI independente feishu-tool, que permite chamar todas as ferramentas do Feishu diretamente no terminal, em scripts Shell ou em agentes de IA, sem a necessidade de iniciar o servidor MCP.

Instalação

# 全局安装（推荐）
npm install -g feishu-mcp@latest

Configuração

# 1. 查看 CLI 概览（子命令 + 可用工具集）
feishu-tool --help

# 2. 查看初始化指南（获取 App ID / Secret 的步骤说明）
feishu-tool guide

# 3. 写入凭证
feishu-tool config set FEISHU_APP_ID cli_xxxxx
feishu-tool config set FEISHU_USER_KEY "$(node -e 'console.log(crypto.randomUUID())')"
# FEISHU_USER_KEY 建议每个本地用户或客户端保持唯一

# 4. 查看当前配置（确认写入正确）
feishu-tool config

# 5. 查看某个工具的详细参数
feishu-tool help create_feishu_document

# 6. 调用工具
feishu-tool create_feishu_document '{"title": "测试文档"}'

Para a descrição completa dos parâmetros, consulte a documentação do Feishu-Skill.

⚙️ Configuração do projeto

Configuração de variáveis de ambiente

Nome da variável	Obrigatório	Descrição	Valor padrão
`FEISHU_APP_ID`	✅	ID do aplicativo Feishu	-
`FEISHU_APP_SECRET`	✅	Segredo do aplicativo Feishu	-
`PORT`	❌	Porta do servidor	`3333`
`FEISHU_BASE_URL`	❌	URL base da API do Feishu; para a versão internacional do Lark, pode ser configurada como `https://open.larksuite.com/open-apis`	`https://open.feishu.cn/open-apis`
`FEISHU_AUTH_BASE_URL`	❌	Domínio da página de autorização do Feishu; para a versão internacional do Lark, defina como `https://accounts.larksuite.com`	`https://accounts.feishu.cn`
`FEISHU_PUBLIC_BASE_URL`	❌	URL base acessível externamente do serviço. Na autenticação `user`, se o MCP for acessado por endereço de rede interna, mas o callback OAuth precisar usar um domínio público, pode ser definido como, por exemplo, `https://mcp.example.com`	-
`FEISHU_AUTH_TYPE`	❌	Tipo de credencial de autenticação; use `user` (nível de usuário; ao usar, as operações nos documentos do Feishu são feitas com a identidade do usuário, exigindo autorização OAuth), use `tenant` (nível de aplicativo, padrão)	`tenant`
`FEISHU_SCOPE_VALIDATION`	❌	Se a verificação de permissões está habilitada; defina como `false` para desativar a verificação de permissões (adequado para cenários que usam apenas algumas funcionalidades)	`true`
`FEISHU_ENABLED_MODULES`	❌	Módulos habilitados: `document`, `task`, `calendar`, `member`, `all`. Os módulos task/calendar/member exigem autenticação de usuário	`document`
`FEISHU_USER_KEY`	❌	Identificador de usuário no modo `stdio/CLI`, pode ser definido via `feishu-tool config set FEISHU_USER_KEY <value>` ou pelo parâmetro de linha de comando `--user-key`	`stdio`
`FEISHU_REQUIRE_USER_KEY`	❌	Se é obrigatório exigir uma user-key explícita no modo de autenticação `user`. Por padrão, mantém a compatibilidade; em cenários multiusuário HTTP/proxy, é recomendado definir como `true`	`false`
`FEISHU_ENCRYPTION_KEY`	❌	Chave de criptografia para campos sensíveis do cache de tokens. Qualquer string; o sistema deriva automaticamente a chave de criptografia via SHA-256. Após a definição, campos sensíveis como `access_token`, `refresh_token` e `client_secret` serão armazenados criptografados. Em implantações Docker, é recomendado definir uma chave fixa	-
`MCP_BEARER_TOKEN`	❌	Token de autenticação Bearer do MCP. Após a definição, todos os endpoints HTTP/SSE/StreamableHTTP exigirão o cabeçalho `Authorization: Bearer <token>` nas requisições; se não for definido, a autenticação não é habilitada. Recomenda-se usar strings aleatórias como UUID	-

Descrição dos módulos de funcionalidade

Módulo	Descrição	Requisito de autenticação
`document`	Documentos, pastas, busca, etc.	tenant / user
`task`	Operações CRUD de tarefas	Somente user
`calendar`	Calendário (em desenvolvimento)	Somente user
`member`	Consulta de informações de usuários	Somente user
`all`	Habilitar todos os módulos	Todos carregados quando user

Método de arquivo de configuração (adequado para Cursor, Cline, etc.)

Modo stdio (recomendado)

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["-y", "feishu-mcp@latest", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "<你的飞书应用ID>",
        "FEISHU_APP_SECRET": "<你的飞书应用密钥>",
        "FEISHU_AUTH_TYPE": "<tenant/user>",
        "FEISHU_ENABLED_MODULES": "document,task",
        "FEISHU_USER_KEY": "<你的用户标识>"
      }
    }
  }
}

Modo SSE

{
  "mcpServers": {
    "feishu_local": {
      "url": "http://localhost:3333/sse?userKey=123456"
    }
  }
}

Modo HTTP Streamable

{
  "mcpServers": {
    "feishu_streamable": {
      "url": "http://localhost:3333/mcp?userKey=123456"
    }
  }
}

Autenticação Bearer Token (opcional)

Quando a variável de ambiente MCP_BEARER_TOKEN é configurada, todos os endpoints HTTP/SSE/StreamableHTTP exigirão que as requisições incluam o cabeçalho Authorization: Bearer <token>. Adequado para cenários de implantação em rede pública, prevenindo acessos não autorizados.

Exemplo de configuração:

# .env 文件
MCP_BEARER_TOKEN=your-secret-token-here

Exemplo de configuração do cliente (modo SSE + autenticação Bearer):

⚠️ Atualmente, a maioria dos clientes MCP (como Cursor, Cline) não suporta cabeçalhos personalizados em conexões SSE/StreamableHTTP. Se precisar usar a autenticação Bearer, confirme se o seu cliente suporta o envio do cabeçalho Authorization, ou use um proxy reverso (como Nginx) para autenticação no lado do servidor.

Para clientes que suportam cabeçalhos personalizados ou chamadas de API:

# SSE 连接示例
curl -H "Authorization: Bearer your-secret-token-here" http://localhost:3333/sse?userKey=123456

# StreamableHTTP 请求示例
curl -X POST -H "Authorization: Bearer your-secret-token-here" -H "Content-Type: application/json" http://localhost:3333/mcp?userKey=123456

⚠️ Aviso importante: o userKey na URL representa o identificador do usuário conectado e é uma configuração muito importante. Preencha-o e torne-o o mais aleatório possível.

Formas de envio do userKey: há duas formas de enviar o identificador do usuário

Parâmetro de consulta na URL: ?userKey=123456 (recomendado, configuração simples)
Cabeçalho de requisição: user-key: 123456 (adequado para cenários que precisam ocultar parâmetros)

📝 Dicas de uso (importante)

Recomenda-se especificar uma pasta:

Ao criar novos documentos, é recomendado fornecer ativamente o token da pasta do Feishu (pode ser uma pasta específica ou a pasta raiz), o que permite localizar e gerenciar documentos com mais eficiência. Se não tiver certeza sobre a subpasta específica, você pode deixar o LLM encontrar automaticamente o subdiretório mais adequado na pasta especificada para criar o novo documento.

Como obter o token da pasta? Abra a página da pasta no Feishu e copie o link (por exemplo, https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx); o token é a última sequência de caracteres do link (por exemplo, xxxxxxxxxxxxxxxxxxxxxx; não compartilhe o token real).
Explicação sobre o caminho de upload de imagens:

Ao executar o MCP localmente, o caminho da imagem suporta tanto caminhos absolutos locais quanto imagens da web http/https; em ambientes de servidor, apenas links de imagens da web são suportados (devido à limitação de comprimento dos parâmetros ao chamar o MCP pelo cursor, o upload direto do arquivo de imagem não é suportado no momento; use o caminho da imagem ou link para upload).
Instruções de uso de fórmulas:

Em blocos de texto, é possível misturar texto comum e elementos de fórmula. As fórmulas usam a sintaxe LaTeX, como: 1+2=3, \frac{a}{b}, \sqrt{x}, etc. É suportado incluir múltiplas fórmulas e texto comum no mesmo bloco de texto.
Usando a autenticação de usuário do Feishu:

A autenticação de usuário e a autenticação de tenant diferem na adição de permissões; portanto, ao alternar pela primeira vez de tenant para user, é necessário prestar atenção às permissões configuradas; para distinguir diferentes usuários, é necessário enviar o identificador de usuário userKey, com suporte a duas formas:
- Parâmetro de consulta na URL: adicione ?userKey=123456 na URL do servidor MCP
- Cabeçalho de requisição: envie o cabeçalho user-key: 123456
Esse valor é o identificador único do usuário, portanto, quanto mais aleatório for na configuração, melhor
É fortemente recomendado usar a autenticação de usuário:

A autenticação de tenant possui várias limitações, como permissões de acesso a arquivos, compatibilidade com a OpenAPI do Feishu (não suporta busca de documentos wiki), registros de criação e edição de documentos, entre outros, que são inferiores à autenticação de usuário.
Funcionalidades de tarefas e informações de usuários:

Quer usar a IA para ajudar a gerenciar tarefas do Feishu (listar pendências, criar tarefas, atribuir responsáveis) ou encontrar informações de colegas? São necessários dois passos: ① usar a autenticação de usuário (essas funcionalidades não estão disponíveis no modo tenant); ② definir FEISHU_ENABLED_MODULES=document,task na configuração. Após habilitar o módulo task, a funcionalidade de consulta de usuários fica automaticamente disponível, sem necessidade de configuração adicional.
Usando a versão internacional do Lark:

A versão nacional do Feishu não requer configuração adicional. Se sua equipe usa a versão internacional do Lark ou um serviço Feishu próprio, é necessário configurar adicionalmente:
```
FEISHU_BASE_URL=https://open.larksuite.com/open-apis
FEISHU_AUTH_BASE_URL=https://accounts.larksuite.com
```
Separação entre acesso por rede interna e callback externo:

Se o cliente MCP acessa o serviço por endereço de rede interna (por exemplo, http://feishu-mcp:3333/mcp), mas o callback OAuth do Feishu precisa usar um domínio público, é possível configurar adicionalmente:
```
FEISHU_PUBLIC_BASE_URL=https://somo-feishu-mcp.yfgao.net
```
Assim, o cliente pode continuar conectando ao endereço de rede interna, enquanto o link de autorização retornado ao usuário usará https://somo-feishu-mcp.yfgao.net/callback como endereço de callback.
Alternância dinâmica de userKey em arquitetura de proxy multiusuário:

Em uma arquitetura de proxy multiusuário, o sistema usa ferramentas de gerenciamento integrado para fazer proxy unificado do serviço MCP do Feishu. Como as instâncias do serviço MCP subjacente são reutilizadas na camada de sessão, as requisições de diferentes usuários são executadas em um contexto de Sessão compartilhado. Portanto, o sistema precisa suportar a alternância dinâmica baseada no user-key transmitido pelo cabeçalho da requisição, para alcançar o isolamento da identidade do locatário e a injeção de contexto, atendendo às necessidades de acesso concorrente de múltiplos usuários.

Como alternar o userKey:
- No modo HTTP Streamable, as requisições subsequentes podem atualizar dinamicamente o identificador do usuário da sessão atual enviando o cabeçalho user-key
- Forma de envio: adicione user-key: <新的用户标识> no cabeçalho da requisição
- Exemplo de cenário: quando o usuário A conclui uma operação, a requisição do usuário B carrega user-key: userB, e o sistema alterna automaticamente a sessão para o contexto do usuário B
Observação: esta funcionalidade só é válida no modo HTTP Streamable; os modos SSE e stdio não suportam alternância dinâmica.

🚨 Solução de problemas

Verificação de problemas de permissão

Primeiro, consulte os problemas de configuração: tutorial passo a passo FEISHU_CONFIG.md.

Confirmação do problema

Verificar as permissões do aplicativo: garanta que o aplicativo tenha as permissões necessárias de acesso a documentos
Validar a autorização do documento: confirme se o documento de destino foi autorizado ao aplicativo ou ao grupo em que o aplicativo está
Verificar o escopo de disponibilidade: garanta que o escopo de disponibilidade da versão publicada do aplicativo inclua o proprietário do documento

Validação e verificação de permissões

Obter token: obter app_access_token para aplicativos autoconstruídos
Usar o token obtido no passo 1 para verificar se há permissão de acesso ao documento: obter informações básicas do documento

Problemas comuns

Aplicativo não encontrado: verifique se o aplicativo foi publicado e se o escopo de disponibilidade está configurado corretamente
Permissões insuficientes: consulte as Perguntas frequentes sobre documentos em nuvem
Problemas de acesso à base de conhecimento: consulte as Perguntas frequentes sobre a base de conhecimento

📚 Wiki para desenvolvedores

Documentação detalhada de desenvolvimento e guias técnicos, fornecendo orientação abrangente para aprendizes e contribuidores:

Página inicial do Wiki - Índice completo de documentos e navegação rápida
Design de arquitetura - Explicação da arquitetura geral e da pilha tecnológica
Detalhes dos módulos principais - Detalhes de implementação e exemplos de código de cada módulo
Autenticação e autorização - Gerenciamento de tokens e mecanismo de suporte a múltiplos usuários
Guia do desenvolvedor - Configuração do ambiente, fluxo de desenvolvimento, dicas de depuração
Referência da API - Documentação detalhada de todas as funções de ferramentas
Melhores práticas - Padrões de código, otimização de desempenho, práticas de segurança
Implementação do protocolo MCP - Explicação detalhada do protocolo MCP e implementação da camada de transporte

💖 Apoie o projeto

Se este projeto ajudou você, considere:

⭐ Dar um Star ao projeto
🐛 Reportar bugs e problemas
💡 Sugerir novos recursos
📖 Melhorar a documentação
🔀 Enviar um Pull Request

Seu apoio é a nossa motivação para avançar!