SharePoint MCP Server

Navegue e interaja com sites e documentos do Microsoft SharePoint.

GitHub
10
Experimente este MCPPatrocinado

Documentação

SharePoint MCP Server

Um servidor Model Context Protocol para navegar e interagir com sites e documentos do Microsoft SharePoint.

Este servidor MCP baseado em TypeScript fornece integração abrangente com o SharePoint por meio da API Microsoft Graph, permitindo:

  • Recursos: Acesse sites do SharePoint como recursos MCP com metadados estruturados
  • Ferramentas: Pesquise arquivos, liste sites, navegue em bibliotecas de documentos e recupere conteúdo de arquivos
  • Autenticação: Fluxo seguro de credenciais de cliente OAuth2 com gerenciamento automático de tokens

Recursos

Recursos

  • Liste os sites do SharePoint acessíveis ao aplicativo
  • Acesse informações de site individual via URIs sharepoint://site/{siteId}
  • Metadados de site formatados em JSON com nomes de exibição e URLs da web

Ferramentas

search_files

Pesquise arquivos e documentos no SharePoint usando a API de Pesquisa do Microsoft Graph

  • Parâmetros:
    • query (obrigatório): String de consulta de pesquisa
    • limit (opcional): Número máximo de resultados a retornar (padrão: 10)

list_sites

Liste os sites do SharePoint acessíveis ao aplicativo

  • Parâmetros:
    • search (opcional): Filtrar sites por nome de exibição

get_site_info

Obtenha informações detalhadas sobre um site específico do SharePoint

list_site_drives

Liste bibliotecas de documentos (unidades) em um site do SharePoint

  • Parâmetros:
    • siteUrl (obrigatório): URL do site do SharePoint

list_drive_items

Liste arquivos e pastas em uma biblioteca de documentos do SharePoint

  • Parâmetros:
    • siteUrl (obrigatório): URL do site do SharePoint
    • driveId (opcional): ID da unidade específica (usa a unidade padrão se não for especificado)
    • folderPath (opcional): Caminho da pasta para listar itens (padrão: raiz)

get_file_content

Obtenha o conteúdo de um arquivo específico do SharePoint (somente arquivos de texto)

  • Parâmetros:
    • siteUrl (obrigatório): URL do site do SharePoint
    • filePath (obrigatório): Caminho para o arquivo
    • driveId (opcional): ID da unidade específica (usa a unidade padrão se não for especificado)

Pré-requisitos

Registro do Aplicativo no Azure

  1. Registre um aplicativo no Azure Active Directory
  2. Configure as permissões da API:
    • Microsoft Graph: Sites.Read.All (permissão de aplicativo)
    • Microsoft Graph: Files.Read.All (permissão de aplicativo)
  3. Conceda consentimento do administrador para as permissões
  4. Crie um segredo do cliente

Variáveis de Ambiente

Defina as seguintes variáveis de ambiente:

SHAREPOINT_URL=https://yourtenant.sharepoint.com
TENANT_ID=your-azure-tenant-id
CLIENT_ID=your-azure-app-client-id
CLIENT_SECRET=your-azure-app-client-secret

Desenvolvimento

Instale as dependências:

npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

Testes

Teste o servidor usando o Inspetor MCP:

npm run inspector

O Inspetor fornece uma interface web para testar todas as ferramentas e recursos disponíveis.

Instalação

Configuração do Claude Desktop

Adicione o servidor à configuração do seu Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sharepoint-mcp-server": {
      "command": "node",
      "args": ["/path/to/sharepoint-mcp-server/build/index.js"],
      "env": {
        "SHAREPOINT_URL": "https://yourtenant.sharepoint.com",
        "TENANT_ID": "your-azure-tenant-id",
        "CLIENT_ID": "your-azure-app-client-id",
        "CLIENT_SECRET": "your-azure-app-client-secret"
      }
    }
  }
}

Instalação Global

Você também pode instalar o servidor globalmente:

npm install -g .

Depois use-o diretamente:

sharepoint-mcp-server

Arquitetura

O servidor implementa uma arquitetura orientada a serviços com clara separação de responsabilidades:

  • Camada de Autenticação: Lida com a aquisição e renovação de tokens OAuth2
  • Cliente da API Graph: Gerencia solicitações HTTP para a API Microsoft Graph
  • Manipuladores de Ferramentas: Processam solicitações de ferramentas MCP e formatam respostas
  • Manipuladores de Recursos: Gerenciam recursos e metadados de sites do SharePoint
  • Tratamento de Erros: Gerenciamento abrangente de erros com códigos de erro MCP apropriados

Considerações de Segurança

  • Usa fluxo de credenciais de cliente OAuth2 para autenticação segura
  • Tokens são renovados automaticamente antes da expiração
  • Todas as solicitações de API usam HTTPS
  • Segredos do cliente devem ser armazenados com segurança e nunca enviados para o controle de versão
  • Permissões de aplicativo exigem consentimento do administrador no Azure AD

Solução de Problemas

Problemas Comuns

  1. Erros de Autenticação: Verifique o registro do aplicativo e as permissões no Azure
  2. Acesso ao Site: Garanta que o aplicativo tenha permissões apropriadas no SharePoint
  3. Problemas de Rede: Verifique as configurações do firewall para acesso à API Microsoft Graph

Modo de Depuração

Defina a variável de ambiente para registro detalhado:

DEBUG=sharepoint-mcp-server

Contribuindo

  1. Siga as melhores práticas do TypeScript
  2. Mantenha um tratamento de erros abrangente
  3. Adicione testes para novas funcionalidades
  4. Atualize a documentação para alterações de API

Licença

Este projeto está licenciado sob a Licença Pública Mozilla 2.0. Consulte o arquivo LICENSE para obter detalhes.

Contribuindo

Agradecemos contribuições! Siga estas diretrizes:

Introdução

  1. Crie um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça suas alterações
  4. Adicione testes para novas funcionalidades
  5. Certifique-se de que todos os testes passem (npm test)
  6. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  7. Envie para o branch (git push origin feature/amazing-feature)
  8. Abra uma Pull Request

Diretrizes de Desenvolvimento

  • Siga as melhores práticas do TypeScript e mantenha a segurança de tipos
  • Implemente tratamento de erros abrangente com códigos de erro MCP apropriados
  • Adicione comentários JSDoc para todos os métodos e classes públicas
  • Mantenha a arquitetura orientada a serviços com clara separação de responsabilidades
  • Siga os princípios SOLID e mantenha funções focadas e testáveis
  • Atualize a documentação para qualquer alteração de API

Estilo de Código

  • Use o modo estrito do TypeScript
  • Siga a formatação de código e as convenções de nomenclatura existentes
  • Remova imports e variáveis não utilizados
  • Use nomes descritivos para variáveis e funções
  • Prefira composição em vez de herança

Testes

  • Adicione testes unitários para novas funcionalidades
  • Teste condições de erro e casos de borda
  • Certifique-se de que o conjunto de testes básico passe
  • Teste com ambientes reais do SharePoint quando possível

Documentação

  • Atualize o README.md para novos recursos ou alterações de configuração
  • Adicione comentários JSDoc para novas APIs públicas
  • Inclua exemplos para funcionalidades complexas
  • Atualize o changelog para alterações significativas

Changelog

[0.1.0] - Lançamento Inicial

  • Integração básica com SharePoint via API Microsoft Graph
  • Suporte para pesquisa de arquivos no SharePoint
  • Recursos de listagem e navegação de sites
  • Acesso a bibliotecas de documentos e recuperação de conteúdo de arquivos
  • Autenticação OAuth2 com credenciais de cliente
  • Suporte a recursos MCP para sites do SharePoint
  • Tratamento abrangente de erros e registro

Suporte

Se você encontrar problemas ou tiver dúvidas:

  1. Consulte a seção de solução de problemas neste README
  2. Pesquise problemas existentes no GitHub
  3. Crie um novo problema com informações detalhadas sobre o seu caso
  4. Inclua logs e configurações relevantes (sem informações confidenciais)

Agradecimentos

  • Construído com o Model Context Protocol SDK
  • Usa a API Microsoft Graph para integração com SharePoint
  • Inspirado pela comunidade e ecossistema MCP