# MCP Server NG-ZORRO

[![Build](https://github.com/velrys/mcp-server-ngzorro/actions/workflows/build.yml/badge.svg)](https://github.com/velrys/mcp-server-ngzorro/actions/workflows/build.yml)
[![NPM Version](https://img.shields.io/npm/v/mcp-server-ngzorro.svg)](https://www.npmjs.com/package/mcp-server-ngzorro)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Servidor MCP (Model Context Protocol) que expõe ferramentas para consulta inteligente da documentação **NG-ZORRO (Ant Design for Angular)** via GitHub API com cache eficiente, operando em modo **STDIO** (JSON‑RPC 2.0) compatível com clientes MCP.

## ✨ Destaques

- Fluxo enxuto: extração de contexto → recuperação de documentação
- Ferramentas tipadas com Zod + validação
- Modo STDIO pronto para clientes MCP (Claude / VS Code / Cursor / scripts customizados)
- Facilmente extensível para novas tools de busca/listagem

## 🧰 Ferramentas Disponíveis

| Tool                     | Descrição                                                               |
| ------------------------ | ----------------------------------------------------------------------- |
| `extract_ngzorro_topic`  | Gera prompt estruturado (component, topics, intent, subtarefas)         |
| `query_ngzorro_document` | Busca documentação e exemplos oficiais do componente (simples/complexo) |

> Outras ferramentas utilitárias antigas foram removidas temporariamente para simplificar a superfície inicial.

## ⚡ Uso Rápido

### 1. Executar sem instalar

```bash
npx mcp-server-ngzorro
```

### 2. Instalar globalmente

```bash
npm install -g mcp-server-ngzorro
mcp-server-ngzorro
```

### 3. Execução STDIO direta (debug/manual)

```bash
npm run build
node build/index.js --stdio
```

O processo aguardará mensagens JSON‑RPC 2.0 via stdin e responderá via stdout.

### Configuração VS Code (exemplo)

Crie `~/.vscode/mcp.json`:

```json
{
  "servers": {
    "mcp-server-ngzorro": {
      "command": "npx",
      "args": ["-y", "mcp-server-ngzorro", "mcp"]
    }
  }
}
```

> Nota: O argumento final `"mcp"` é opcional. Ele existe para compatibilidade com clientes que enviam um subcomando explícito (padrão semelhante ao `@angular/cli`). Se seu cliente não precisar, pode remover.

### Windows (cmd) Config (Cursor / VS Code)

Se estiver no Windows e o cliente exigir uso de `cmd`:

```json
{
  "mcpServers": {
    "mcp-server-ngzorro": {
      "command": "npx",
      "args": ["-y", "mcp-server-ngzorro"]
    }
  }
}
```

> Também aqui o `mcp` final é opcional.

## 👩‍💻 Desenvolvimento

```bash
git clone https://github.com/velrys/mcp-server-ngzorro.git
cd mcp-server-ngzorro
npm install
npm run build        # compila para ./build
node build/index.js --stdio  # inicia em modo stdio
npm start            # build + inspector interativo
```

## 🧪 Exemplo (Agente)

```yaml
mode: agent
tools: ['extract_ngzorro_topic', 'query_ngzorro_document']
description: 'Trazer docs e exemplo básico'
---
Preciso exibir uma tabela paginada com filtros server-side. Traga a doc relevante e um trecho mínimo.
```

## 🤝 Contribuição

**🔒 Repositório Público com Fluxo Rigoroso**

Todas as mudanças devem ser feitas via **Pull Request com aprovação obrigatória**. Leia o [Guia de Contribuição](.github/CONTRIBUTING.md) completo.

### 🚀 Fluxo Rápido:

```bash
# 1. Fork o repositório
# 2. Clone e prepare
git clone https://github.com/SEU_USUARIO/mcp-server-ngzorro.git
cd mcp-server-ngzorro && npm install

# 3. Crie branch para sua mudança
git checkout -b feature/minha-contribuicao

# 4. Desenvolva, teste e commit
npm run build && npm run lint
git commit -m "feat: minha contribuição"

# 5. Push e abra PR
git push origin feature/minha-contribuicao
```

### 📋 Requisitos:

- ✅ Build e lint passando
- ✅ PR template preenchido
- ✅ Code review e aprovação
- ✅ Commits seguindo [Conventional Commits](https://conventionalcommits.org/)

**Ver [CONTRIBUTING.md](.github/CONTRIBUTING.md) para detalhes completos.**

## 🔒 Segurança

**Sem coleta ou armazenamento de dados do usuário.**

### 🚨 Vulnerabilidades:

- **Não** abra issue pública
- **Reporte** via [Security Policy](.github/SECURITY.md)
- **Email**: erivelton.silva106@gmail.com

### ✅ Boas Práticas:

- Não commitar tokens
- Usar `GITHUB_TOKEN` apenas para rate limits
- Manter dependências atualizadas (`npm audit`)

**Ver [SECURITY.md](.github/SECURITY.md) para processo completo.**

## 📄 Licença

MIT © Erivelton

---

> Nota: Arquivos internos históricos foram simplificados; este README é a fonte principal.

## 🙏 Créditos

- NG-ZORRO Team
- Comunidade Model Context Protocol

---

Pronto para explorar? `npx mcp-server-ngzorro`