NPX-MCP

Um servidor MCP (Model Context Protocol) em TypeScript que fornece ferramentas úteis para automação e integração, incluindo autenticação OAuth da Microsoft, controle de navegador e utilitários básicos.

📦 Instalação

Via NPX

npx npx-mcp

Instalação global

npm install -g npx-mcp

Desenvolvimento local

git clone cd npx-mcp npm install npm run build

🚀 Uso

Este servidor MCP é projetado para ser usado com clientes compatíveis com o Model Context Protocol. Uma vez conectado, você terá acesso às seguintes ferramentas:

🛠 Ferramentas Disponíveis

1. Echo Tool

• Nome: echo
• Descrição: Ecoa de volta a mensagem fornecida
• Parâmetros:
  • message (string): A mensagem a ser ecoada

2. Addition Tool

• Nome: add
• Descrição: Soma dois números
• Parâmetros:
  • a (number): Primeiro número
  • b (number): Segundo número

3. Open Browser Tool

• Nome: openBrowser
• Descrição: Abre uma URL no navegador padrão e aguarda até que seja fechado
• Parâmetros:
  • url (string): URL válida para abrir no navegador
• Compatibilidade: Windows, macOS e Linux

4. Microsoft OAuth Authentication

• Nome: authenticateOAuth
• Descrição: Autentica com Microsoft OAuth e obtém token de acesso
• Funcionalidades:
  • Autenticação PKCE (Proof Key for Code Exchange)
  • Servidor local temporário para callback
  • Suporte a multi-tenant
  • Refresh token (quando disponível)

⚙️ Configuração

Variáveis de Ambiente (OAuth)

Para usar a ferramenta de autenticação OAuth, configure as seguintes variáveis:

export CLIENT_ID="seu-client-id-aqui" export TENANT_ID="seu-tenant-id-aqui" # Opcional, use 'common' para multi-tenant

Configuração do Azure AD

1. Registre um aplicativo no Azure AD
2. Configure a URL de redirecionamento: http://localhost:3000/callback
3. Habilite "Allow public client flows"
4. Adicione as permissões necessárias (ex: openid, profile)

🛠 Desenvolvimento

Pré-requisitos

• Node.js >= 16.0.0
• npm ou yarn

Scripts disponíveis

• npm run build: Compila o TypeScript para JavaScript
• npm run dev: Executa em modo desenvolvimento com ts-node
• npm start: Executa o servidor MCP compilado
• npm run test: Executa testes de exemplo
• npm run clean: Remove arquivos compilados
• npm run prepublishOnly: Prepara o pacote para publicação

Configuração do ambiente de desenvolvimento

Clone o repositório

git clone cd npx-mcp

Instale as dependências

npm install

Execute em modo desenvolvimento

npm run dev

Compile o projeto

npm run build

Execute a versão compilada

npm start

📁 Estrutura do projeto

npx-mcp/
├── src/
│   ├── index.ts              # Servidor MCP principal
│   └── oauth-auth.ts         # Implementação OAuth Microsoft
├── dist/                     # Arquivos compilados (gerado)
├── package.json
├── tsconfig.json
├── test-examples.sh          # Scripts de teste
└── README.md

🔧 Funcionalidades

• ✅ Servidor MCP completo com múltiplas ferramentas
• ✅ Autenticação OAuth Microsoft com PKCE
• ✅ Controle de navegador multiplataforma
• ✅ Ferramentas utilitárias (echo, soma)
• ✅ TypeScript com tipagem forte
• ✅ Compatível com Node.js >= 16
• ✅ Transporte stdio para integração com clientes MCP

🔌 Integração com Clientes MCP

Este servidor pode ser usado com qualquer cliente compatível com MCP, como:

• Claude Desktop
• Outras aplicações que suportam Model Context Protocol

Exemplo de configuração para Claude Desktop

Adicione ao seu arquivo de configuração:

{ "mcpServers": { "npx-mcp": { "command": "npx", "args": ["npx-mcp"] } } }

🔐 Segurança

• As credenciais OAuth são tratadas de forma segura
• Tokens são retornados apenas via MCP tools
• Servidor local é iniciado apenas durante autenticação
• Suporte completo a PKCE para fluxos OAuth seguros

📝 Licença

MIT

👥 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.

📚 Recursos Adicionais

• Model Context Protocol Documentation
• Microsoft Graph API
• Azure AD OAuth 2.0

⚠️ Notas Importantes

• O servidor OAuth local é temporário e só funciona durante o processo de autenticação
• Certifique-se de que a porta 3000 esteja disponível para o callback OAuth
• As credenciais OAuth devem ser configuradas adequadamente no Azure AD