MCP Analytics with GitHub OAuth

Um servidor MCP remoto com autenticação GitHub OAuth e rastreamento de análises integrado.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Servidor Model Context Protocol (MCP) + GitHub OAuth + Analytics

Este é um servidor Model Context Protocol (MCP) que suporta conexões MCP remotas, com autenticação GitHub OAuth e rastreamento de analytics integrado, alimentado por MCP Analytics.

Você pode implantá-lo na sua própria conta Cloudflare e, após criar seu próprio aplicativo de cliente OAuth do GitHub, terá um servidor MCP remoto totalmente funcional com analytics abrangentes. Os usuários poderão se conectar ao seu servidor MCP fazendo login com suas contas GitHub, e você obterá insights detalhados sobre uso de ferramentas, desempenho e comportamento do usuário.

Recursos

  • ✅ Autenticação GitHub OAuth - Autenticação segura de usuários via GitHub
  • ✅ Protocolo MCP Remoto - Implementação completa do servidor MCP
  • ✅ Rastreamento de Analytics - Rastreamento automático de uso de ferramentas, desempenho e métricas de usuários
  • ✅ Controle de Acesso - Acesso a ferramentas baseado em funções, conforme nomes de usuário do GitHub
  • ✅ Geração de Imagens - Geração de imagens com IA para usuários autorizados
  • ✅ Pronto para Produção - Implantado no Cloudflare Workers com Durable Objects

Painel de Analytics

Este servidor rastreia automaticamente:

  • 📊 Uso de Ferramentas - Quais ferramentas são usadas com mais frequência
  • ⏱️ Métricas de Desempenho - Tempos de execução e taxas de sucesso
  • 👥 Analytics de Usuários - Usuários ativos e dados de sessão
  • 🔧 Rastreamento de Erros - Requisições com falha e detalhes de erros
  • 💰 Rastreamento de Receita - Eventos de pagamento (se usar ferramentas pagas)

Veja seus analytics em: https://mcpanalytics.dev

Primeiros Passos

Clone o repositório diretamente e instale as dependências:

git clone <your-repo-url>
cd mcp-github-oauth-analytics
npm install

Instruções de Configuração

1. Configuração do MCP Analytics

  1. Cadastre-se em https://mcpanalytics.dev
  2. Crie um novo projeto e obtenha sua chave de API
  3. Adicione a chave de API ao seu ambiente:
# For production
wrangler secret put MCP_ANALYTICS_API_KEY

# For local development (.dev.vars file)
MCP_ANALYTICS_API_KEY=your_api_key_here

2. Configuração do GitHub OAuth

Para Produção

Crie um novo Aplicativo OAuth do GitHub:

  • URL da página inicial: https://your-worker-name.your-subdomain.workers.dev
  • URL de callback de autorização: https://your-worker-name.your-subdomain.workers.dev/callback
  • Anote seu Client ID e gere um Client secret

Defina os segredos via Wrangler:

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY # Use: openssl rand -hex 32

Para Desenvolvimento Local

Crie outro Aplicativo OAuth do GitHub para desenvolvimento:

  • URL da página inicial: http://localhost:8788
  • URL de callback de autorização: http://localhost:8788/callback

Crie um arquivo .dev.vars:

GITHUB_CLIENT_ID=your_development_github_client_id
GITHUB_CLIENT_SECRET=your_development_github_client_secret
COOKIE_ENCRYPTION_KEY=your_random_encryption_key
MCP_ANALYTICS_API_KEY=your_analytics_api_key

3. Configuração do Namespace KV

# Create the KV namespace
wrangler kv:namespace create "OAUTH_KV"

# Update wrangler.toml with the returned KV ID

4. Configure o Controle de Acesso

Edite o ALLOWED_USERNAMES no seu arquivo principal para controlar quem pode acessar a ferramenta de geração de imagens:

const ALLOWED_USERNAMES = new Set<string>([
	'yourusername',
	'teammate1',
	'teammate2'
]);

Implantação

Implante no Cloudflare Workers:

wrangler deploy

Seu servidor MCP estará disponível em: https://your-worker-name.your-subdomain.workers.dev/sse

Testando Seu Servidor

Usando o MCP Inspector

npx @modelcontextprotocol/inspector@latest

Digite a URL do seu servidor e teste o fluxo de autenticação.

Usando o Claude Desktop

  1. Abra Claude Desktop → Configurações → Desenvolvedor → Editar Config
  2. Adicione esta configuração:
{
  "mcpServers": {
    "github-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker-name.your-subdomain.workers.dev/sse"
      ]
    }
  }
}
  1. Reinicie o Claude Desktop e complete o fluxo OAuth
  2. Teste com: "Você poderia usar a ferramenta de matemática para somar 23 e 19?"

Usando Outros Clientes MCP

Cursor: Use o formato de comando: npx mcp-remote https://your-worker-url/sse

Windsurf: Adicione a mesma configuração JSON do Claude Desktop

Ferramentas Disponíveis

add (Todos os Usuários)

Ferramenta simples de adição matemática para testar a conectividade.

Uso: "Some 5 e 3"

generateImage (Somente Usuários Autorizados)

Geração de imagens com IA usando o modelo Flux da Cloudflare.

Uso: "Gere uma imagem de um pôr do sol sobre montanhas"

Parâmetros:

  • prompt: Descrição da imagem a ser gerada
  • steps: Etapas de qualidade (4-8, maior = melhor qualidade)

Integração de Analytics

Este servidor usa o AnalyticsMcpAgent, que rastreia automaticamente:

  • ✅ Tempos de Execução de Ferramentas - Quanto tempo cada ferramenta leva para executar
  • ✅ Taxas de Sucesso/Falha - Quais ferramentas funcionam de forma confiável
  • ✅ Sessões de Usuários - Quem está usando seu servidor e quando
  • ✅ Registro de Parâmetros - Quais entradas os usuários estão fornecendo (sanitizadas com segurança)
  • ✅ Detalhes de Erros - Contexto completo de erros para depuração
  • ✅ Dados de Usuário do GitHub - E-mail e nome de usuário do OAuth (para analytics de usuários)

Visualizando Analytics

  1. Visite https://dashboard.mcpanalytics.dev
  2. Faça login com a mesma conta usada para criar sua chave de API
  3. Veja painéis em tempo real mostrando:
    • Tendências de uso de ferramentas
    • Métricas de desempenho
    • Atividade de usuários
    • Taxas de erro e detalhes

Desenvolvimento Local

Inicie o servidor de desenvolvimento:

wrangler dev

Seu servidor estará disponível em http://localhost:8788/sse

Arquitetura

Provedor OAuth

A biblioteca do Provedor OAuth serve como uma implementação completa de servidor OAuth 2.1, lidando com:

  • Autenticação de clientes MCP
  • Integração com GitHub OAuth
  • Gerenciamento e validação de tokens
  • Armazenamento seguro de estado no Cloudflare KV

Agente de Analytics

O AnalyticsMcpAgent estende a funcionalidade base do MCP com:

  • Rastreamento automático de eventos para todas as chamadas de ferramentas
  • Identificação de usuários via propriedades OAuth
  • Monitoramento de desempenho e rastreamento de erros
  • Registro seguro de parâmetros e resultados

Durable Objects

Fornece gerenciamento de estado persistente com:

  • Continuidade de sessão do usuário
  • Preservação do contexto de autenticação
  • Conexões em tempo real escaláveis

Segurança e Privacidade

  • 🔒 OAuth 2.1 - Autenticação padrão da indústria
  • 🔐 Tokens Criptografados - Todos os dados de autenticação criptografados em trânsito e armazenamento
  • 🛡️ Controle de Acesso - Permissões granulares por usuário do GitHub
  • 🧹 Sanitização de Dados - Dados sensíveis automaticamente removidos dos logs
  • ⏰ Expiração de Tokens - Atualização e expiração automática de tokens

Solução de Problemas

Problemas Comuns

"Chave de API inválida" no analytics: Verifique se seu MCP_ANALYTICS_API_KEY está definido corretamente

Erros de callback OAuth: Garanta que as URLs do seu aplicativo OAuth do GitHub correspondam exatamente às URLs de implantação

Ferramentas não aparecendo: Verifique se o nome de usuário do GitHub do usuário está em ALLOWED_USERNAMES para ferramentas restritas

Tempos limite de conexão: Verifique se seu Worker está implantado e respondendo na URL correta

Suporte

  • 📖 Documentação do MCP Analytics: https://docs.mcpanalytics.dev
  • 💬 Issues do GitHub: Para bugs e solicitações de recursos
  • 📧 Suporte por E-mail: Disponível para usuários do plano Pro

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.