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": {
      "type": "http",
      "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, arquivos de memória), executa um motor determinístico de ~30 famílias de regras respaldadas por pesquisa e mostra uma nota mais uma pontuação objetiva de 0 a 100 com explicações citadas e ancoradas na linha. Além do básico (orçamentos de tamanho por ferramenta, linguagem vaga, segredos), ele sinaliza o que os próprios fornecedores dos modelos atuais agora mandam remover: linguagem impositiva como "CRITICAL: You MUST use…" (causa sobre-ativação no Claude 4.5+/GPT-5), andaimes "think step by step" (modelos de raciocínio fazem isso internamente; pedir que transcrevam o raciocínio pode provocar recusas no Claude Fable 5), gatilhos de bajulação ("match the user's vibe"), árvores de diretórios coladas (agentes as ignoram mas pagam ~+20% de tokens de raciocínio por elas, segundo um benchmark da ETH Zurich), contradições never/always, e contrabando de instruções com Unicode invisível (a classe de ataque "Rules File Backdoor") com diretivas de ocultação e domínios de exfiltração.

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 (manifesto do stack, comandos de build, 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. A detecção do stack abrange vários ecossistemas, não só Node: lê package.json, Package.swift/.xcodeproj (Swift), pyproject.toml/requirements.txt (Python, incl. FastAPI/Django/Flask), go.mod, Cargo.toml e Gemfile; os comandos vêm dos scripts do npm, dos alvos do Makefile e das receitas do justfile. 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.

Uma execução real

Em um serviço FastAPI, a partir de um checkout limpo:

$ promptarch lint CLAUDE.md
CLAUDE.md - grade C (72/100, claude_md)
  ⚠ warn  line 3  vague/low-signal: "follow best practices" ...
  ⚠ warn  line 8  antipattern/verbosity-instruction: "be concise" ...

$ promptarch init --dry-run        # grátis; sem key, sem chamada de rede
# → detecta tech_stack: "Python, FastAPI, SQLAlchemy", comandos a partir do Makefile

$ promptarch init                  # confirma sobrescritas primeiro, depois gera
init writes agent config files into /srv/app, overwriting:
  CLAUDE.md
Continue? Generating uses one credit. [y/N] y
wrote AGENTS.md
wrote CLAUDE.md
wrote .cursor/rules/overview.mdc
wrote .cursor/rules/structure.mdc
wrote .cursor/rules/style.mdc
wrote .cursor/rules/boundaries.mdc
wrote .github/copilot-instructions.md
wrote .github/instructions/style.instructions.md

✓ Generated 8 file(s) in /srv/app

$ promptarch lint CLAUDE.md
CLAUDE.md - grade A (100/100, claude_md)
  ✓ no findings

Esse é o ciclo: revise para ver onde você está, gere uma base limpa, revise de novo para confirmar. O init nunca sobrescreve um arquivo feito à mão silenciosamente: ele pergunta primeiro (passe --force para pular a confirmação, ou --out <dir> para escrever em outro lugar). Em CI, proteja apenas com o lint:

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

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": {
      "type": "http",
      "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.