@shardev/cli

Servidor MCP (stdio) y CLI (shardev) para crear y operar proyectos Laravel + React + AWS ECS, pensado para reemplazar scripts de shell. Solo ESM, Node >= 22.

Estado: núcleo del generador. Dos herramientas de lectura y cinco de generación local (T2, sin AWS). Pendientes (no existen todavía): mobile_add, las herramientas ui_* y cualquier operación que cambie AWS.

templates/ contiene las capas base (laravel, workspace, packages, app-model, app-auth, tests-auth, app-react, app-workspace, env, docker, claude-kit, verify, y las opcionales app-otp, app-social, app-mfa, mfa-deps, app-invitations, tests-otp, tests-social, tests-mfa, tests-invitations, app-react-otp, app-react-social, app-react-mfa, app-react-invitations); ver docs/decisions/0003-plantillas.md. project_create solo corre pasos ligeros; project_verify corre además composer, migraciones, tests, pnpm, build y docker compose config. app_plan/app_create añaden una app a un proyecto ya generado sin re-renderizar nada de proyecto (los feature layers otp, social, mfa e invitations existen, ver docs/decisions/0005-otp-social.md y docs/decisions/0006-mfa-invitations.md).

Instalación

Requiere Node >= 22.

npm install -g @shardev/cli      # instala el binario `shardev`
# o, sin instalar: npx @shardev/cli --version

Registrar el servidor en Claude Code (lo ejecutas tú; el paquete no toca tu configuración):

claude mcp add --scope user shardev -- shardev mcp serve
# sin instalación global: claude mcp add --scope user shardev -- npx -y @shardev/cli mcp serve

Para evitar prompts en las herramientas de solo lectura, permite mcp__shardev__ops_status y mcp__shardev__log_read en tus permisos. Las herramientas futuras de producción (T3) llevarán _meta["anthropic/requiresUserInteraction"] = true y pedirán confirmación en cada llamada (ver docs/decisions/0001-spikes.md).

Prueba rápida: shardev --version. La CLI es un solo binario: shardev mcp serve inicia el servidor y shardev project plan|create|verify [--json] y shardev app plan|create [--json] ejecutan las mismas funciones que las herramientas project_* y app_*. Ejemplo: shardev app plan --project-path ~/projects/acme --key supp --user-type new --json y luego shardev app create --plan-id plan_....

Para contribuir

git clone https://github.com/shardevcom/shardev-mcp.git
cd shardev-mcp
npm install && npm run build
npm link   # opcional: expone el binario `shardev` desde tu copia local

Related MCP server: Laravel Cloud MCP Server

Configuración inicial del dueño

Solo se documentan los pasos; nada de esto lo ejecuta el paquete por ti.

1. Crear la configuración en ~/.config/shardev-mcp/ (ninguna herramienta la escribe):

   • config.yaml: allowed_roots: [/home/yo/projects]. Sin esto project_create no crea nada. Opcionalmente leftover_terms (ver más abajo).

   • policy.yaml: modo por perfil AWS (default_mode, aws_profiles con account_id, production_mode, environments). Sin archivo todo es command-only; producción con un perfil no listado queda disabled. Ver examples/policy.yaml.

   • projects.yaml: proyectos registrados (path absoluto y production_envs opcional). Ver examples/projects.yaml.

2. ops.yaml en la raíz de cada proyecto (nombre, service_prefix, capabilities, y por entorno is_production, aws_profile, account_id, region, cluster). Ver examples/ops.yaml.

3. Inicia sesión AWS tú mismo (aws sso login --profile X); el servidor nunca lo hace.

Archivos de configuración

Todo vive en ~/.config/shardev-mcp/ (config del dueño) y ~/.local/state/shardev-mcp/ (estado). Las rutas no se pueden cambiar por variables de entorno, a propósito: un .mcp.json de proyecto no debe poder apuntar a otra política.

~/.config/shardev-mcp/policy.yaml

Política del dueño, fuera de cualquier proyecto; ninguna herramienta puede escribirla. Ejemplo comentado en examples/policy.yaml:

default_mode: command-only        # entornos no productivos
aws_profiles:
  mi-perfil-prod:
    account_id: "222222222222"
    production_mode: command-only
    environments: [prod]          # opcional

• Modos (de menos a más permisivo): disabled < command-only < gated-apply. Sin archivo: command-only.

• Modo efectivo = el más restrictivo entre la regla del usuario y policy.max_mode del ops.yaml (el proyecto solo restringe).

• Producción con un perfil que no está en aws_profiles => disabled (fail closed). policy.yaml inválido => todo disabled.

• Sin sesión AWS => "operaciones AWS no disponibles" con el comando exacto (aws sso login --profile X); el servidor nunca intenta iniciar sesión.

• Cuenta autenticada distinta de la de ops.yaml (o de la del perfil en la policy) => rechazo.

• command-only: devuelve el comando exacto para que lo ejecutes tú; no ejecuta nada.

• gated-apply: se lee, pero no está implementado; actúa como command-only y lo indica en el resultado.

<proyecto>/ops.yaml

Ejemplo en examples/ops.yaml:

project: { name: demo }
stack: laravel
service_prefix: demo-
capabilities: [ecs, logs]
policy: { max_mode: command-only }   # opcional
environments:
  - name: staging
    is_production: false
    aws_profile: demo-stg
    account_id: "111111111111"
    region: us-east-1
    cluster: shared

env nunca tiene valor por defecto. is_production es obligatorio. Los servicios ECS deben empezar por service_prefix (el cluster es compartido entre proyectos).

~/.config/shardev-mcp/projects.yaml

projects:
  demo:
    path: /ruta/absoluta/al/proyecto/demo
    production_envs: [prod]   # opcional

Producción (la política no confía en el ops.yaml del proyecto, que un agente puede editar): un entorno es producción si el manifest dice is_production: true, o su nombre es prod/production (sin distinguir mayúsculas), o está en production_envs de este archivo. Gana producción ante cualquier conflicto y el resultado lo indica (production_conflict). El account_id no sirve para distinguir: staging y producción comparten cuenta.

Las herramientas reciben el nombre registrado, nunca una ruta libre.

~/.config/shardev-mcp/config.yaml

allowed_roots:            # sin esto, project_create no crea nada
  - /home/yo/projects
leftover_terms:           # opcional: restos que no deben llegar a un proyecto generado
  - acme-legacy

leftover_terms es una lista de términos (mínimo 2 caracteres) que el escaneo de restos busca en lo que se genera: coincidencia literal (los caracteres especiales de regex no se interpretan) y sin distinguir mayúsculas. Sirve para nombres de proyectos o dominios de origen que no deben quedar en un proyecto nuevo. Un término contenido en el nombre o dominio del propio proyecto no cuenta. Aplica a project_create, project_verify y app_plan/app_create; no forma parte del plan, que sigue siendo determinista. Independientemente de esta lista, el escaneo siempre rechaza ARN y registros ECR con un id de cuenta AWS de 12 dígitos. Ver examples/config.yaml.

El destino de project_plan/project_create y el project_path de app_plan deben quedar estrictamente dentro de una raíz (se resuelven symlinks y ..).

Generador

• Spec (src/gen/spec.ts, zod): ProjectSpec { name, domain, apps[], features[], mobile? }; cada app deriva guards, tabla, provider, modelo y build_dir de key (todo sobrescribible). Nombres estrictos (sin separadores de ruta); se rechazan duplicados de key, guard, tabla, puerto y build_dir.

• Capas (templates/<capa>/layer.yaml): scope (project|app|mobile), order, when, requires (variables que deben usarse), files (src o tree; render lista lo que se renderiza en un tree), edits (json-merge, yaml-append, insert anclado) y verify (full: true = solo project_verify). {{ secret.app_key }} etc. se rellenan con valores aleatorios al crear (archivo 0600, fuera del lock). Renderer propio: {{ var }} y {{#if x}}; estricto (variable desconocida, requerida sin usar o bloque sin cerrar = error); $VAR, ${VAR}, ${{ }} y variables de nginx pasan intactos; \{{ emite un {{ literal.

• Cableado: ancla ausente o ambigua = error; reaplicar un edit ya presente es no-op.

• Plan puro; se guarda en ~/.local/state/shardev-mcp/plans (0600) con spec, hash de plantillas y hash del destino, firmado con HMAC (clave en plan.key, 0600). Un plan expirado, alterado, con plantillas distintas o con destino cambiado se rechaza. Un plan con conflictos no recibe plan_id.

• Aplicar a repo existente: árbol limpio, rama base distinta de master/main, rama nueva derivada del plan (shardev/<label>-<proyecto>-<id8>); sin commit, sin push, sin migraciones; si la verificación falla se revierte y se borra la rama.

• Lock .ops/lock.yaml: hash de plantillas, capas, spec y hash de cada archivo generado. Verify: pasos por exec (array, stdin cerrado, env explícito, timeout) y escaneo de secretos con los patrones del Redactor (una línea con shardev-allow-secret se omite). Decisiones en docs/decisions/0002-generador.md.

Seguridad del motor

• exec: solo arrays de argumentos (sin shell), timeout, entorno explícito (PATH, HOME, AWS_PROFILE, AWS_REGION, AWS_DEFAULT_REGION, AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE + adiciones por llamada) y stdin cerrado.

• redact: enmascara formas conocidas de secretos (sk-ant-, AIza, GOCSPX-, AKIA, tokens de GitHub, JWT, Bearer, claves privadas), NOMBRE=valor con nombre de apariencia secreta (incluidas comillas: export X_TOKEN="a b") nombre: valor (YAML y logs, con o sin comillas) con nombre de apariencia secreta, credenciales en URLs (mysql://user:[REDACTED]@host, se conservan usuario y host) y literales registrados. Limitaciones: es heurístico y prefiere enmascarar de más; no detecta secretos sin forma conocida ni nombre sospechoso (p. ej. un valor suelto en una línea sola), valores multilínea de YAML (|, >) ni secretos codificados/partidos.

• Logs completos (ya redactados) en ~/.local/state/shardev-mcp/logs (dir 0700, archivos 0600); los resultados solo llevan resumen, exit code y log_ref. log_read rechaza cualquier referencia que no sea un nombre de archivo generado (sin /, .., ni symlinks).

• Auditoría append-only en ~/.local/state/shardev-mcp/audit.jsonl (tool, proyecto, env, tier, decisión, exit code, duración; argumentos redactados).

• stdout es el canal del protocolo; los logs del servidor van a stderr.

Desarrollo

npm run typecheck
npm test            # rápido: sin red
npm run test:slow   # genera un proyecto real y corre composer/pnpm/build (red, ~70 s)
npm run build

Los tests usan directorios temporales y un runner falso de aws; nunca tocan el HOME real ni AWS. Las decisiones de diseño están en el repositorio (docs/decisions/; no se publican en el paquete npm).