La CLI y el servidor MCP de PromptArch: guía completa

PromptArch no es solo una aplicación web. El mismo motor que impulsa el Context Engineering Studio se distribuye en dos superficies para desarrolladores: una CLI que ejecutas en tu terminal y un servidor MCP que tu agente de IA puede invocar directamente. Esta guía cubre ambas: instalación, cada comando y herramienta, API keys y cómo integrarlas en CI.

La versión de 30 segundos

npm install -g promptarch

promptarch lint CLAUDE.md        # gratis, sin conexión, apto para CI
promptarch login                 # pega una API key pk_ una sola vez
promptarch init                  # repo → CLAUDE.md, AGENTS.md, Cursor, Copilot

Y para agentes, un solo bloque de configuración:

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

Revisar (lint) es siempre gratis: sin cuenta, sin llamadas de red desde la CLI, sin clave para la herramienta de lint del MCP. La generación consume créditos de tu cuenta de PromptArch, igual que generar en la app.

Parte 1: La CLI

Instalación

npm install -g promptarch

Eso es todo. El paquete incluye todo lo que necesita (Node 18+).

promptarch lint - gratis, sin conexión, determinista

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

El linter detecta el formato del artefacto (CLAUDE.md, AGENTS.md, .mdc de Cursor, instrucciones de Copilot), ejecuta un motor de reglas determinista y muestra una calificación más una puntuación objetiva de 0 a 100 con explicaciones por hallazgo: una tabla de comandos ausente, secciones que exceden el presupuesto de tamaño de la herramienta de destino, o instrucciones vagas que un agente no puede ejecutar.

Tres propiedades lo hacen apto para CI:

• Sin conexión. Sin llamadas de red, sin cuenta, sin clave. Las reglas corren localmente.
• Determinista. Mismo archivo, mismos hallazgos: sin variabilidad de LLM.
• Códigos de salida. Distinto de cero cuando algún archivo tiene errores, así un lint fallido rompe el build. Añade --strict para fallar también con advertencias.

Un paso mínimo de GitHub Actions:

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

Es el mismo motor de reglas del linter web gratuito en /lint. La CLI simplemente lo lleva a tu repositorio.

promptarch login - guarda tu API key

La generación (a diferencia del lint) habla con la API de PromptArch, así que necesita una API key:

1. Crea una clave en Perfil → API keys dentro de la app. Las claves empiezan con pk_ y se muestran una sola vez al crearlas.
2. Ejecuta promptarch login y pégala. La clave se guarda en ~/.config/promptarch/config.json con permisos de solo propietario.

Para CI o uso automatizado, evita el prompt:

promptarch login --key pk_tu_clave     # no interactivo
# o simplemente define una variable de entorno - tiene prioridad sobre la config guardada:
export PROMPTARCH_API_KEY=pk_tu_clave

promptarch init - del repo a los archivos de contexto

promptarch init
promptarch init --dry-run     # muestra qué se enviaría, sin llamar a la API
promptarch init --out docs/   # escribe los archivos en otra carpeta

init escanea tu repositorio (package.json, scripts, el árbol de directorios, tu README y cualquier configuración de agente existente) y envía ese contexto a la API de generación de PromptArch. El resultado vuelve como un context pack canónico, que la CLI exporta de forma determinista a los archivos que cada herramienta espera:

• CLAUDE.md para Claude Code
• AGENTS.md para agentes compatibles con AGENTS.md
• .cursor/rules/*.mdc para Cursor
• .github/copilot-instructions.md para GitHub Copilot

Cada archivo se mantiene dentro del presupuesto de tamaño que su herramienta realmente lee bien, y puedes volver a ejecutar promptarch lint sobre la salida para verificar. Usa --dry-run primero si quieres ver exactamente qué contexto del repo se enviaría antes de que algo salga de tu máquina.

Parte 2: El servidor MCP

Si usas Claude Code, Cursor, Windsurf o cualquier otro cliente del Model Context Protocol, tu agente puede revisar y generar artefactos por sí mismo, sin pasar por la terminal.

El servidor vive en https://mcp.promptarch.ai/mcp y habla Streamable HTTP, así que no hay nada que instalar ni ejecutar localmente.

Conectar un cliente

Añade esto a la configuración de servidores MCP de tu cliente. Para Claude Code es .mcp.json en la raíz del repo; para Cursor, .cursor/mcp.json:

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

Solo la generación necesita la cabecera Authorization. Quien solo use lint puede omitirla por completo.

Las herramientas

En la práctica, puedes decirle a tu agente cosas como "revisa este CLAUDE.md y corrige lo que marque" o "genera una regla de Cursor para nuestras convenciones de API" y él mismo gestiona las llamadas a las herramientas. Tu API key nunca se almacena en el servidor MCP. Se reenvía por petición a la API de PromptArch.

Ejemplos de instrucciones

Una vez conectado el servidor, lo controlas en lenguaje natural y el agente elige la herramienta:

• "¿Qué tipos de artefactos puede generar promptarch?" → ejecuta promptarch_list_artifact_types y lista Context Pack, CLAUDE.md, AGENTS.md y regla de Cursor.
• "Revisa nuestro CLAUDE.md con promptarch y corrige lo que marque." → ejecuta promptarch_lint_artifact (gratis) y luego el agente edita el archivo para resolver los hallazgos, por ejemplo quitando un "sigue las mejores prácticas", eliminando un "piensa paso a paso" y recortando un "sé conciso" que el linter señala.
• "Genera un CLAUDE.md para este repo con promptarch: Next.js 15, Drizzle sobre SQLite, pnpm." → ejecuta promptarch_generate_artifact (un crédito) y escribe un archivo estructurado con secciones de Comandos, Arquitectura, Estilo de código y Solución de problemas.
• "Dame una regla de Cursor para nuestras convenciones de validación de API." → promptarch_generate_artifact con el artefacto cursor_rule, devolviendo un .mdc con el frontmatter correcto.

El verdadero valor está en encadenar: revisar → leer la nota → regenerar o corregir a mano → revisar de nuevo para confirmar una A, todo sin salir del agente.

¿Qué superficie usar en cada caso?

• Aplicación web (/studio) - explorar tipos de artefactos, crear con el asistente guiado, gestionar tu biblioteca.
• CLI - flujos nativos del repo: arrancar los archivos de contexto de un proyecto con init, proteger PRs con lint en CI.
• MCP - flujos nativos del agente: el agente revisa y regenera sus propios archivos de contexto como parte de su trabajo.

Las tres comparten el mismo motor de generación, las mismas reglas de lint y el mismo saldo de créditos.

Empieza ahora

1. npm install -g promptarch y revisa algo. Es gratis.
2. Crea una API key en Perfil → API keys cuando quieras generar.
3. Apunta tu agente a https://mcp.promptarch.ai/mcp.

Las cuentas nuevas reciben créditos gratis, suficientes para probar init en un repo real sin tarjeta.