# Desenvolvimento Local MCP

import Code from '~/components/Code/Code.astro'

Este guia cobre como configurar um ambiente de desenvolvimento local para o servidor MCP da Azion, útil para testes, customização ou contribuição ao projeto.

---

## Pré-requisitos

Antes de começar, certifique-se de ter:

- **Node.js 20+** instalado
- **Yarn** gerenciador de pacotes
- **Azion CLI** instalado: [como baixar](https://www.azion.com/pt-br/documentacao/produtos/azion-cli/visao-geral/)
- **Git** para clonar o repositório
- **Chave de API OpenAI** (necessária para recursos de IA no desenvolvimento local)

---

## Configuração

### 1. Clonar o repositório

<Code lang="bash" code={`git clone https://github.com/aziontech/mcp-server.git
cd mcp-server`} />

### 2. Instalar dependências

<Code lang="bash" code={`yarn install`} />

### 3. Configurar variáveis de ambiente

<Code lang="bash" code={`# Necessário para recursos de IA
export OPENAI_API_KEY="sua_chave_openai"

# Opcional: Autenticação Fast Pass para integração com Azion Copilot
export MCP_COPILOT_SERVER_TOKEN="seu_token"`} />

### 4. Build do servidor

<Code lang="bash" code={`azion build`} />

---

## Executando localmente

Inicie o servidor de desenvolvimento:

<Code lang="bash" code={`azion dev
# O servidor estará disponível em http://localhost:3333`} />

### Conectar seu assistente de código

Uma vez que o servidor esteja rodando, configure seu assistente de código para usar o endpoint local:

<Code lang="bash" code={`# Exemplo com Claude Code
claude mcp add "azion-mcp-local" "http://localhost:3333" -t http -H "Authorization: Bearer SEU_PERSONAL_TOKEN"`} />

---

## Deploy pessoal

Faça deploy de sua própria instância do servidor MCP na Plataforma Azion.

### 1. Criar configuração pessoal

<Code lang="bash" code={`# Criar diretório de configuração pessoal
mkdir -p azion/personal

# Vincular seu projeto
azion link

# Build com configuração pessoal
azion build --config-dir azion/personal`} />

### 2. Deploy

<Code lang="bash" code={`azion deploy --config-dir azion/personal`} />

### 3. Configurar variáveis de ambiente

Após o deploy, adicione as variáveis de ambiente necessárias no Console Azion:

1. Navegue até sua aplicação no [Console Azion](https://console.azion.com)
2. Vá para **Variáveis de Ambiente**
3. Adicione `OPENAI_API_KEY` com sua chave de API OpenAI

### 4. Usar sua URL pessoal

Atualize sua configuração MCP para usar a URL do seu deploy pessoal em vez do endpoint de produção.

---

## Testes

### Usando o MCP Inspector

Teste seu deploy local ou pessoal com o MCP Inspector:

<Code lang="bash" code={`# Instalar MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Executar o inspector
npx @modelcontextprotocol/inspector`} />

Na interface do Inspector:

1. Selecione **streamable-http** como tipo de transporte
2. Digite sua URL: `http://localhost:3333` (local) ou sua URL de deploy pessoal
3. Adicione o header de autenticação: `Authorization: Bearer SEU_PERSONAL_TOKEN`
4. Clique em **Connect** e teste as ferramentas disponíveis

### Testar diretamente com Node.js

<Code lang="bash" code={`npx @modelcontextprotocol/inspector node build/index.js`} />

---

## Estrutura do projeto

O projeto do servidor MCP está organizado da seguinte forma:

| Diretório/Arquivo | Descrição |
|-------------------|-----------|
| `src/index.ts` | Ponto de entrada principal |
| `src/core/` | Funcionalidade central |
| `src/core/tools.ts` | Definições de ferramentas |
| `src/core/resources.ts` | Definições de recursos |
| `src/core/prompts.ts` | Definições de prompts |
| `src/middlewares/auth.ts` | Middleware de autenticação |
| `src/helpers/utils.ts` | Funções auxiliares |
| `azion/production` | Configuração do ambiente de produção |
| `azion/stage` | Configuração do ambiente de stage |

---

## Diretórios de configuração

O projeto inclui diretórios de configuração predefinidos:

- **`azion/production`**: Configuração do ambiente de produção
- **`azion/stage`**: Configuração do ambiente de stage
- **`azion/personal`**: Sua configuração pessoal (crie este)

:::note
Nunca modifique os diretórios `production` ou `stage`. Sempre use uma configuração pessoal para desenvolvimento.
:::

---

## Métodos de autenticação

O servidor MCP suporta múltiplos métodos de autenticação:

| Método | Descrição | Formato |
|--------|-----------|--------|
| **Fast Pass Token** | Token interno para Azion Copilot | Definido via variável de ambiente `MCP_COPILOT_SERVER_TOKEN` |
| **Personal Tokens** | Personal Tokens Azion | Formato: `azion[a-zA-Z0-9]{35}` (40 caracteres) |
| **OAuth Tokens** | Bearer tokens do fluxo OAuth SSO | Validado contra `/oauth/userinfo` |
| **JWT Tokens** | Bearer tokens para autenticação API v4 | Validado contra `/v4/account/auth/token` |

Ordem de detecção de token: JWT primeiro para Bearer tokens, depois OAuth se JWT falhar.

---

## Solução de problemas no desenvolvimento local

### Servidor não inicia

1. Verifique a versão do Node.js: `node --version` (deve ser 20+)
2. Verifique se a porta 3333 está disponível
3. Certifique-se de que todas as dependências estão instaladas: `yarn install`

### Erros de autenticação

1. Verifique se seu Personal Token é válido
2. Verifique se `OPENAI_API_KEY` está definido corretamente
3. Certifique-se de que o formato do header de autorização está correto

### Falhas no build

<Code lang="bash" code={`# Limpar e reconstruir
rm -rf build/
azion build`} />

---

## Próximos passos

- [Guia de Configuração MCP](/pt-br/documentacao/devtools/mcp/configuracao/)
- [Exemplos MCP](/pt-br/documentacao/devtools/mcp/exemplos/)
- [Solução de Problemas MCP](/pt-br/documentacao/devtools/mcp/solucao-de-problemas/)