@po-ui/mcp 21.30.0 → 21.30.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +242 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
# @po-ui/mcp
|
|
2
|
+
|
|
3
|
+
Servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io) que disponibiliza a documentação oficial do [PO UI](https://po-ui.io) para assistentes de IA.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@po-ui/mcp)
|
|
6
|
+
[](https://github.com/po-ui/po-angular/blob/master/LICENSE)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
|
|
9
|
+
## Visão geral
|
|
10
|
+
|
|
11
|
+
O `@po-ui/mcp` conecta clientes compatíveis com MCP à documentação pública do PO UI. Com ele, um agente pode listar APIs e guias, obter a documentação completa de um recurso e pesquisar termos em toda a documentação consolidada.
|
|
12
|
+
|
|
13
|
+
O conteúdo é consultado nas fontes oficiais do PO UI durante a execução. Assim, o cliente não depende de uma cópia da documentação incluída no pacote.
|
|
14
|
+
|
|
15
|
+
## Requisitos
|
|
16
|
+
|
|
17
|
+
- Node.js 18 ou superior;
|
|
18
|
+
- acesso a `po-ui.io` e `raw.githubusercontent.com`.
|
|
19
|
+
|
|
20
|
+
## Uso com `npx`
|
|
21
|
+
|
|
22
|
+
Não é necessário instalar o pacote globalmente. Configure o cliente MCP para executar:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npx -y @po-ui/mcp
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
O servidor utiliza o transporte `stdio`; normalmente, o próprio cliente MCP inicia e encerra o processo.
|
|
29
|
+
|
|
30
|
+
## Configuração
|
|
31
|
+
|
|
32
|
+
### Claude Desktop
|
|
33
|
+
|
|
34
|
+
Adicione o servidor ao arquivo `claude_desktop_config.json`:
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"mcpServers": {
|
|
39
|
+
"po-ui": {
|
|
40
|
+
"command": "npx",
|
|
41
|
+
"args": ["-y", "@po-ui/mcp"]
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Depois de salvar o arquivo, reinicie o Claude Desktop.
|
|
48
|
+
|
|
49
|
+
### Cursor
|
|
50
|
+
|
|
51
|
+
Adicione o servidor em **Settings > MCP** ou crie o arquivo `.cursor/mcp.json` no projeto:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"mcpServers": {
|
|
56
|
+
"po-ui": {
|
|
57
|
+
"command": "npx",
|
|
58
|
+
"args": ["-y", "@po-ui/mcp"]
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Kiro
|
|
65
|
+
|
|
66
|
+
Abra a paleta de comandos e execute **Kiro: Open workspace MCP config (JSON)** ou crie o arquivo `.kiro/settings/mcp.json` no projeto:
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{
|
|
70
|
+
"mcpServers": {
|
|
71
|
+
"po-ui": {
|
|
72
|
+
"command": "npx",
|
|
73
|
+
"args": ["-y", "@po-ui/mcp"],
|
|
74
|
+
"disabled": false
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Depois de salvar o arquivo, o Kiro reconecta o servidor automaticamente. Confirme a conexão na seção **MCP Servers** do painel do Kiro.
|
|
81
|
+
|
|
82
|
+
### VS Code com GitHub Copilot
|
|
83
|
+
|
|
84
|
+
Execute **MCP: Add Server** na paleta de comandos ou adicione o servidor ao arquivo `.vscode/mcp.json`:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"servers": {
|
|
89
|
+
"po-ui": {
|
|
90
|
+
"type": "stdio",
|
|
91
|
+
"command": "npx",
|
|
92
|
+
"args": ["-y", "@po-ui/mcp"]
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Continue
|
|
99
|
+
|
|
100
|
+
Crie o arquivo `.continue/mcpServers/po-ui.yaml` no projeto:
|
|
101
|
+
|
|
102
|
+
```yaml
|
|
103
|
+
name: PO UI MCP
|
|
104
|
+
version: 0.0.1
|
|
105
|
+
schema: v1
|
|
106
|
+
mcpServers:
|
|
107
|
+
- name: PO UI
|
|
108
|
+
type: stdio
|
|
109
|
+
command: npx
|
|
110
|
+
args:
|
|
111
|
+
- -y
|
|
112
|
+
- "@po-ui/mcp"
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
As ferramentas MCP ficam disponíveis no modo Agent do Continue.
|
|
116
|
+
|
|
117
|
+
### Outros clientes
|
|
118
|
+
|
|
119
|
+
Em clientes compatíveis com servidores MCP locais, configure um servidor `stdio` com o comando `npx` e os argumentos `-y` e `@po-ui/mcp`. Consulte a documentação do cliente para confirmar o formato e o local do arquivo de configuração.
|
|
120
|
+
|
|
121
|
+
## Ferramentas disponíveis
|
|
122
|
+
|
|
123
|
+
O servidor expõe quatro ferramentas somente de leitura.
|
|
124
|
+
|
|
125
|
+
### `list_components`
|
|
126
|
+
|
|
127
|
+
Lista componentes, diretivas, serviços, interfaces, enums e guias disponíveis no índice do PO UI.
|
|
128
|
+
|
|
129
|
+
| Parâmetro | Tipo | Obrigatório | Descrição |
|
|
130
|
+
| --- | --- | --- | --- |
|
|
131
|
+
| `section` | `"components" \| "services" \| "interfaces" \| "enums" \| "guides" \| "all"` | não | Seção consultada. O padrão é `all`. |
|
|
132
|
+
| `filter` | `string` | não | Texto procurado no nome ou na descrição, sem diferenciar maiúsculas e minúsculas. |
|
|
133
|
+
|
|
134
|
+
Exemplo:
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{ "section": "components", "filter": "table" }
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### `get_component_docs`
|
|
141
|
+
|
|
142
|
+
Retorna, em Markdown, a documentação de um componente, uma diretiva, um serviço, uma interface ou um enum.
|
|
143
|
+
|
|
144
|
+
| Parâmetro | Tipo | Obrigatório | Descrição |
|
|
145
|
+
| --- | --- | --- | --- |
|
|
146
|
+
| `slug` | `string` | sim | Identificador do recurso. Aceita um slug, como `po-button`; um seletor, como `<po-button>`; ou um nome de classe, como `PoButtonComponent`. |
|
|
147
|
+
|
|
148
|
+
O valor informado é normalizado antes da consulta. Seletores perdem os sinais de maior e menor, nomes em `CamelCase` são convertidos para `kebab-case` e o sufixo `Component` é removido.
|
|
149
|
+
|
|
150
|
+
Exemplo:
|
|
151
|
+
|
|
152
|
+
```json
|
|
153
|
+
{ "slug": "PoButtonComponent" }
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### `search_docs`
|
|
157
|
+
|
|
158
|
+
Realiza uma busca textual, sem diferenciar maiúsculas e minúsculas, no arquivo `llms-full.txt`.
|
|
159
|
+
|
|
160
|
+
| Parâmetro | Tipo | Obrigatório | Descrição |
|
|
161
|
+
| --- | --- | --- | --- |
|
|
162
|
+
| `query` | `string` com pelo menos 2 caracteres | sim | Texto procurado na documentação. |
|
|
163
|
+
| `max_results` | número inteiro de 1 a 50 | não | Quantidade máxima de resultados. O padrão é `10`. |
|
|
164
|
+
|
|
165
|
+
Cada resultado contém o título da seção encontrada e trechos de contexto ao redor das ocorrências.
|
|
166
|
+
|
|
167
|
+
Exemplo:
|
|
168
|
+
|
|
169
|
+
```json
|
|
170
|
+
{ "query": "lazy load", "max_results": 5 }
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### `get_guide`
|
|
174
|
+
|
|
175
|
+
Retorna o conteúdo completo de um guia da documentação.
|
|
176
|
+
|
|
177
|
+
| Parâmetro | Tipo | Obrigatório | Descrição |
|
|
178
|
+
| --- | --- | --- | --- |
|
|
179
|
+
| `guide` | `string` | sim | Nome do guia, com ou sem a extensão `.md`. |
|
|
180
|
+
|
|
181
|
+
Para conhecer os guias disponíveis, use `list_components` com `section` igual a `guides`.
|
|
182
|
+
|
|
183
|
+
Exemplo:
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
{ "guide": "getting-started" }
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
## Exemplos de prompts
|
|
190
|
+
|
|
191
|
+
- “Quais componentes do PO UI permitem upload de arquivos?”
|
|
192
|
+
- “Mostre a documentação do `po-table`.”
|
|
193
|
+
- “Como usar o `PoThemeService`?”
|
|
194
|
+
- “Pesquise por `p-loading` na documentação do PO UI.”
|
|
195
|
+
- “Liste os guias disponíveis e traga o guia de schematics.”
|
|
196
|
+
|
|
197
|
+
## Fontes de dados
|
|
198
|
+
|
|
199
|
+
| Conteúdo | Fonte principal | Fallback |
|
|
200
|
+
| --- | --- | --- |
|
|
201
|
+
| Índice de APIs e guias | `https://po-ui.io/llms.txt` | — |
|
|
202
|
+
| Documentação consolidada | `https://po-ui.io/llms-full.txt` | — |
|
|
203
|
+
| Documentação por recurso | `https://po-ui.io/llms-generated/{slug}.md` | `https://raw.githubusercontent.com/po-ui/po-angular/master/projects/portal/src/llms-generated/{slug}.md` |
|
|
204
|
+
| Guias | `https://raw.githubusercontent.com/po-ui/po-angular/master/docs/guides/{name}.md` | — |
|
|
205
|
+
|
|
206
|
+
O índice `llms.txt` é mantido em memória durante a execução do servidor. Para forçar uma nova leitura, reinicie o servidor no cliente MCP.
|
|
207
|
+
|
|
208
|
+
## Solução de problemas
|
|
209
|
+
|
|
210
|
+
### O cliente não inicia o servidor
|
|
211
|
+
|
|
212
|
+
Confirme que o Node.js 18 ou superior está instalado e que `npx` está disponível no `PATH` do processo que executa o cliente. No Windows, alguns clientes podem exigir o caminho completo para `npx.cmd`.
|
|
213
|
+
|
|
214
|
+
### Erro ao carregar o índice ou a documentação
|
|
215
|
+
|
|
216
|
+
Verifique se o ambiente permite acesso HTTPS a `po-ui.io` e `raw.githubusercontent.com`. Cada requisição possui timeout de 10 segundos.
|
|
217
|
+
|
|
218
|
+
### Recurso não encontrado
|
|
219
|
+
|
|
220
|
+
Use `list_components` para localizar o slug aceito pelo servidor e, em seguida, informe esse valor a `get_component_docs`.
|
|
221
|
+
|
|
222
|
+
### As ferramentas não aparecem no cliente
|
|
223
|
+
|
|
224
|
+
Reinicie o servidor após alterar a configuração e verifique o painel ou o log de servidores MCP do cliente. Algumas aplicações também solicitam autorização antes de disponibilizar as ferramentas.
|
|
225
|
+
|
|
226
|
+
## Desenvolvimento
|
|
227
|
+
|
|
228
|
+
O código-fonte está no monorepo [`po-ui/po-angular`](https://github.com/po-ui/po-angular), em [`projects/mcp`](https://github.com/po-ui/po-angular/tree/master/projects/mcp).
|
|
229
|
+
|
|
230
|
+
Na raiz do repositório, execute:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
npm install
|
|
234
|
+
npm run build:mcp
|
|
235
|
+
npm run test:mcp
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Antes de contribuir, consulte o [guia de contribuição](https://github.com/po-ui/po-angular/blob/master/CONTRIBUTING.md).
|
|
239
|
+
|
|
240
|
+
## Licença
|
|
241
|
+
|
|
242
|
+
[MIT](https://github.com/po-ui/po-angular/blob/master/LICENSE) © PO UI
|