A CLI e o servidor MCP do PromptArch: guia completo

O PromptArch não é só um aplicativo web. O mesmo motor que alimenta o Context Engineering Studio é distribuído em duas superfícies para desenvolvedores: uma CLI que você executa no terminal e um servidor MCP que seu agente de IA pode chamar diretamente. Este guia cobre as duas: instalação, cada comando e ferramenta, API keys e como integrá-las ao CI.

A versão de 30 segundos

npm install -g promptarch

promptarch lint CLAUDE.md        # grátis, offline, pronto para CI
promptarch login                 # cole uma API key pk_ uma única vez
promptarch init                  # repo → CLAUDE.md, AGENTS.md, Cursor, Copilot

E para agentes, um único bloco de configuração:

{
  "mcpServers": {
    "promptarch": {
      "url": "https://mcp.promptarch.ai/mcp",
      "headers": { "Authorization": "Bearer pk_sua_chave" }
    }
  }
}

Revisar (lint) é sempre grátis: sem conta, sem chamadas de rede pela CLI, sem chave para a ferramenta de lint do MCP. A geração consome créditos da sua conta PromptArch, igual a gerar no app.

Parte 1: A CLI

Instalação

npm install -g promptarch

Só isso. O pacote inclui tudo o que precisa (Node 18+).

promptarch lint - grátis, offline, determinístico

promptarch lint CLAUDE.md
promptarch lint AGENTS.md .cursor/rules/*.mdc
promptarch lint CLAUDE.md --strict

O linter detecta o formato do artefato (CLAUDE.md, AGENTS.md, .mdc do Cursor, instruções do Copilot), executa um motor de regras determinístico e mostra uma nota mais uma pontuação objetiva de 0 a 100 com explicações por achado: uma tabela de comandos ausente, seções que estouram o orçamento de tamanho da ferramenta de destino, ou instruções vagas que um agente não consegue executar.

Três propriedades o tornam pronto para CI:

• Offline. Sem chamadas de rede, sem conta, sem chave. As regras rodam localmente.
• Determinístico. Mesmo arquivo, mesmos achados: sem variação de LLM.
• Códigos de saída. Diferente de zero quando algum arquivo tem erros, então um lint reprovado quebra o build. Adicione --strict para reprovar também com avisos.

Um passo mínimo de GitHub Actions:

- run: npx promptarch lint CLAUDE.md AGENTS.md --strict

É o mesmo motor de regras do linter web gratuito em /lint. A CLI apenas o leva para o seu repositório.

promptarch login - guarde sua API key

A geração (diferente do lint) fala com a API do PromptArch, então precisa de uma API key:

1. Crie uma chave em Perfil → API keys dentro do app. As chaves começam com pk_ e são exibidas uma única vez na criação.
2. Execute promptarch login e cole-a. A chave é salva em ~/.config/promptarch/config.json com permissões restritas ao dono.

Para CI ou uso automatizado, pule o prompt:

promptarch login --key pk_sua_chave     # não interativo
# ou simplesmente defina uma variável de ambiente - ela tem prioridade sobre a config salva:
export PROMPTARCH_API_KEY=pk_sua_chave

promptarch init - do repo aos arquivos de contexto

promptarch init
promptarch init --dry-run     # mostra o que seria enviado, sem chamar a API
promptarch init --out docs/   # escreve os arquivos em outra pasta

O init escaneia seu repositório (package.json, scripts, a árvore de diretórios, seu README e qualquer configuração de agente existente) e envia esse contexto para a API de geração do PromptArch. O resultado volta como um context pack canônico, que a CLI exporta de forma determinística para os arquivos que cada ferramenta espera:

• CLAUDE.md para o Claude Code
• AGENTS.md para agentes compatíveis com AGENTS.md
• .cursor/rules/*.mdc para o Cursor
• .github/copilot-instructions.md para o GitHub Copilot

Cada arquivo é mantido dentro do orçamento de tamanho que sua ferramenta realmente lê bem, e você pode rodar promptarch lint de novo na saída para verificar. Use --dry-run primeiro se quiser ver exatamente qual contexto do repo seria enviado antes de qualquer coisa sair da sua máquina.

Parte 2: O servidor MCP

Se você usa Claude Code, Cursor, Windsurf ou qualquer outro cliente do Model Context Protocol, seu agente pode revisar e gerar artefatos sozinho, sem passar pelo terminal.

O servidor fica em https://mcp.promptarch.ai/mcp e fala Streamable HTTP, então não há nada para instalar ou executar localmente.

Conectando um cliente

Adicione isto à configuração de servidores MCP do seu cliente. Para o Claude Code é o .mcp.json na raiz do repo; para o Cursor, .cursor/mcp.json:

{
  "mcpServers": {
    "promptarch": {
      "url": "https://mcp.promptarch.ai/mcp",
      "headers": { "Authorization": "Bearer pk_sua_chave" }
    }
  }
}

Só a geração precisa do cabeçalho Authorization. Quem usa apenas lint pode omiti-lo por completo.

As ferramentas

Na prática, você pode dizer ao seu agente coisas como "revise este CLAUDE.md e corrija o que ele apontar" ou "gere uma regra do Cursor para nossas convenções de API" e ele mesmo cuida das chamadas às ferramentas. Sua API key nunca fica armazenada no servidor MCP. Ela é repassada por requisição à API do PromptArch.

Exemplos de instruções

Com o servidor conectado, você o controla em linguagem natural e o agente escolhe a ferramenta:

• "Quais tipos de artefato o promptarch pode gerar?" → executa promptarch_list_artifact_types e lista Context Pack, CLAUDE.md, AGENTS.md e regra do Cursor.
• "Revise nosso CLAUDE.md com o promptarch e corrija o que ele apontar." → executa promptarch_lint_artifact (grátis) e então o agente edita o arquivo para resolver os apontamentos, por exemplo removendo um "siga as boas práticas", tirando um "pense passo a passo" e cortando um "seja conciso" que o linter sinaliza.
• "Gere um CLAUDE.md para este repositório com o promptarch: Next.js 15, Drizzle sobre SQLite, pnpm." → executa promptarch_generate_artifact (um crédito) e escreve um arquivo estruturado com seções de Comandos, Arquitetura, Estilo de código e Solução de problemas.
• "Me dê uma regra do Cursor para nossas convenções de validação de API." → promptarch_generate_artifact com o artefato cursor_rule, retornando um .mdc com o frontmatter correto.

O ganho real está em encadear: revisar → ler a nota → regenerar ou corrigir à mão → revisar de novo para confirmar um A, tudo sem sair do agente.

Qual superfície usar em cada caso?

• Aplicativo web (/studio) - explorar tipos de artefatos, criar com o assistente guiado, gerenciar sua biblioteca.
• CLI - fluxos nativos do repo: iniciar os arquivos de contexto de um projeto com init, proteger PRs com lint no CI.
• MCP - fluxos nativos do agente: o agente revisa e regenera seus próprios arquivos de contexto como parte do trabalho.

As três compartilham o mesmo motor de geração, as mesmas regras de lint e o mesmo saldo de créditos.

Comece agora

1. npm install -g promptarch e revise algo. É grátis.
2. Crie uma API key em Perfil → API keys quando quiser gerar.
3. Aponte seu agente para https://mcp.promptarch.ai/mcp.

Contas novas recebem créditos grátis, o suficiente para testar o init em um repo real sem cartão.