shardev
OfficialGenerates Docker configuration for generated projects and validates it with docker compose config during project verification.
Generates and verifies Laravel backend projects, including base Laravel layers, app model and auth layers, migrations, tests, and project templates.
Generates React frontend app layers for projects, including auth, OTP, social, MFA, and invitations feature layers, plus build verification.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
@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 y lecturas AWS. Siete herramientas de lectura (T0/T1: ops_status, ops_services, ops_tasks, ops_logs, ops_env_check, ops_ci_check, log_read) y seis de escritura local (T2, sin AWS: project_*, app_*, ops_ci_generate). Pendientes (no existen todavía): mobile_add, las herramientas ui_* y el resto de operaciones que cambian AWS. Hoy son ops_redeploy y ops_scale (T3): el MCP solo devuelve el comando y lo ejecuta una persona con shardev ops redeploy o shardev ops scale.
Herramienta | Tier | Qué hace |
| T1 | Lista proyectos registrados; con |
| T1 | Estado de los servicios ECS declarados del entorno ( |
| T1 | Hasta 20 tareas |
| T3 | Redespliegue forzado de servicios ECS declarados. No ejecuta nada: valida proyecto, entorno y servicios, aplica la política y devuelve el comando exacto |
| T3 | Cambia el |
| T1 | Busca en el grupo |
| T0 | Valida sin conexión (sin AWS, sin cambios) la configuración local de un entorno. |
| T0 | Renderiza en memoria el workflow de despliegue de un entorno desde la plantilla del proyecto ( |
| T2 | Escribe ese workflow de forma atómica (solo esa ruta; rechaza enlaces simbólicos y rutas fuera de la raíz). En un entorno de producción el MCP nunca escribe: devuelve |
| T0 | Lee/filtra (grep literal) un log guardado, solo por referencia. El contenido se devuelve marcado como dato no confiable. |
| T2 | Planifica un proyecto nuevo a partir de un spec: archivos (por defecto un resumen por capa: archivos y bytes; |
| T2 | Aplica un |
| T2 | Re-verifica un proyecto generado y registrado (pasos de las plantillas + escaneo de secretos). |
| T2 | Planifica añadir una app frontend a un proyecto ya generado ( |
| T2 | Aplica un |
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 --versionRegistrar 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 servePara evitar prompts en las herramientas de solo lectura, permite mcp__shardev__ops_status, mcp__shardev__ops_services, mcp__shardev__ops_tasks, mcp__shardev__ops_logs, mcp__shardev__ops_env_check, mcp__shardev__ops_ci_check 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] shardev app plan|create [--json] ejecutan las mismas funciones que las herramientas project_* y app_*, y shardev ops status|services|tasks|logs|env-check|log-read las de ops_* y log_read (solo lectura; --project, --env, --service, --status, --since-minutes, --filter, --limit, --ref, --grep, --context, --offset, --json; --env es obligatorio en services/tasks/logs; sale con código 1 si falla). Ejemplo: shardev ops logs --project demo --env staging --service demo-staging-app --since-minutes 30 --filter ERROR. Para validar la configuración local de un entorno sin AWS: shardev ops env-check --project demo --env staging [--json] (sale con 1 si algún check falla). Para leer lo que guardó ops logs: shardev ops log-read --ref <log_ref> [--grep ERROR] [--context 2] [--offset 1] [--limit 100] (límites de log_read: limit 1-500, context 0-5; solo acepta referencias generadas, y marca el contenido como no confiable). 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 localRelated 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.
Crear la configuración en
~/.config/shardev-mcp/(ninguna herramienta la escribe):config.yaml:allowed_roots: [/home/yo/projects]. Sin estoproject_createno crea nada. Opcionalmenteleftover_terms(ver más abajo).policy.yaml: modo por perfil AWS (default_mode,aws_profilesconaccount_id,production_mode,environments). Sin archivo todo escommand-only; producción con un perfil no listado quedadisabled. Verexamples/policy.yaml.projects.yaml: proyectos registrados (pathabsoluto yproduction_envsopcional). Verexamples/projects.yaml.
ops.yamlen la raíz de cada proyecto (nombre,service_prefix,capabilities, y por entornois_production,aws_profile,account_id,region,cluster). Verexamples/ops.yaml.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] # opcionalModos (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_modedelops.yaml(el proyecto solo restringe).Producción con un perfil que no está en
aws_profiles=>disabled(fail closed).policy.yamlinválido => tododisabled.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: los cambios no se ejecutan (se devuelve el comando exacto para que lo ejecutes tú). No bloquea las lecturas fijas de solo lecturaops_services,ops_tasksyops_logs, que corren también en producción.disabled, sin sesión y cuenta distinta siguen bloqueando todo antes de llamar a ECS/CloudWatch.gated-apply: se lee, pero no está implementado; actúa comocommand-onlyy lo indica en el resultado.
shardev ops redeploy y shardev ops scale (las órdenes de la CLI que cambian AWS)
shardev ops redeploy --project P --env E (--service S | --all) [--json] fuerza un despliegue nuevo (ecs update-service --force-new-deployment) de los servicios declarados, de uno en uno y en orden. Pasa por la misma validación, política e identidad que la herramienta MCP (disabled, sin sesión, cuenta distinta o servicio ajeno no preguntan nada ni llaman a ECS). Exige una terminal interactiva (stdin y stderr TTY) y escribir la frase <proyecto>/<entorno>; no existe --yes, --force ni variable que lo eluda, y cualquier flag desconocido es un error. Escribe en audit.jsonl una entrada de intención (phase: "intent") antes de cambiar (si falla, no cambia nada) y otra de resultado (phase: "result"). Se detiene en el primer fallo, no revierte, informa done/failed/unknown/not_attempted por servicio y sale con 1 si no todos terminaron bien. Un timeout se informa como unknown (puede haberse aplicado). "Iniciado" no es "completado": comprueba el avance con shardev ops services. Decisiones en docs/decisions/0010-operaciones-t3.md.
shardev ops scale --project P --env E (--service S | --all) --desired-count N [--json] (N entero 0-20) cambia el desired-count con ecs update-service --desired-count N (sin --force-new-deployment) y sigue las mismas reglas: confirmación por TTY, sin --yes, auditoría de intención antes de cambiar, un servicio tras otro y parada en el primer fallo. Además: antes de preguntar lee el estado actual (ecs describe-services) y lo muestra (deseadas/en ejecución -> N); si la lectura falla o falta un servicio, no pregunta ni cambia nada; los servicios que ya están en N se informan unchanged y no se tocan, y si todos lo están sale con 0 sin preguntar ni escribir intención. La frase es <proyecto>/<entorno>, salvo para N=0 (servicios fuera de línea), que exige <proyecto>/<entorno>/apagar. No detecta autoscaling programado, que podría volver a cambiar el número de tareas. Que AWS acepte el valor no significa que las tareas ya estén en marcha o detenidas.
<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
services: [demo-staging-app, demo-staging-worker] # opcional, requerido por las lecturas ECS/logsenv nunca tiene valor por defecto. is_production es obligatorio. Los servicios ECS deben empezar por service_prefix (el cluster es compartido entre proyectos). Con cluster y cuenta compartidos un prefijo no separa entornos (el demo- de producción también cubre demo-staging-app), así que ops_services, ops_tasks y ops_logs solo operan sobre servicios que empiecen por el prefijo y estén listados exactamente en services de ese entorno; sin services fallan cerrado (no hay descubrimiento con list-services). capabilities se aplica: ecs para ops_services/ops_tasks, logs para ops_logs. Los logs de un servicio se leen del grupo <log_group_prefix><servicio>; log_group_prefix es opcional por entorno y vale /ecs/ por defecto (solo letras, dígitos y _ . / # -, hasta 200 caracteres, sin ..; un valor inválido hace fallar la lectura del ops.yaml). El servicio sigue teniendo que estar declarado en services, así que el prefijo no permite salir de los servicios declarados. Ver docs/decisions/0007-ops-lectura-aws.md.
Compatibilidad al actualizar: el esquema de entornos es estricto, así que una versión anterior de shardev rechaza un ops.yaml con services (Unrecognized key). Actualiza el CLI antes de añadir services. Lo mismo vale para log_group_prefix: mismo orden de actualización (CLI primero, después el ops.yaml).
~/.config/shardev-mcp/projects.yaml
projects:
demo:
path: /ruta/absoluta/al/proyecto/demo
production_envs: [prod] # opcional
root: /ruta/absoluta/al/codigo/demo # opcional; por defecto, pathpath es donde vive ops.yaml. Si el árbol de código (con .aws/env/ y env.schema) está en otro sitio, root (ruta absoluta) lo indica; ops_env_check es la única herramienta que lo usa y, sin root, usa path. Compatibilidad al actualizar: el esquema de projects.yaml es estricto, así que una versión anterior de shardev rechaza una entrada con root (Unrecognized key). Mismo orden de actualización que services: primero el CLI, después projects.yaml.
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-legacyleftover_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? };mobilese acepta en el esquema (y los locks antiguos que lo traen siguen resolviendo), peroproject_planlo rechaza coninvalid_spec("mobile todavía no está disponible") mientras no exista ninguna capa descope: mobile: antes se anotaba en el lock sin generar nada. La comprobación se desactiva sola cuando exista esa capa, y no afecta aapp_planniproject_verify; cada app deriva guards, tabla, provider, modelo ybuild_dirdekey(todo sobrescribible). Nombres estrictos (sin separadores de ruta); se rechazan duplicados de key, guard, tabla, puerto ybuild_dir.Capas (
templates/<capa>/layer.yaml):scope(project|app|mobile),order,when,requires(variables que deben usarse),files(srcotree;renderlista lo que se renderiza en untree),edits(json-merge,yaml-append,insertanclado) yverify(full: true= soloproject_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 enplan.key, 0600). Un plan expirado, alterado, con plantillas distintas o con destino cambiado se rechaza. Un plan con conflictos no recibeplan_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 porexec(array, stdin cerrado, env explícito, timeout) y escaneo de secretos con los patrones del Redactor (una línea conshardev-allow-secretse omite). Decisiones endocs/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=valorcon 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 ylog_ref.log_readrechaza cualquier referencia que no sea un nombre de archivo generado (sin/,.., ni symlinks).Lecturas AWS: solo
ecs describe-services,ecs list-tasks,ecs describe-tasksylogs filter-log-events(mássts get-caller-identity), siempre como array de argumentos con--profile,--region,--output jsony--no-cli-pager; el contenido de logs nunca vuelve en el resultado.Auditoría append-only en
~/.local/state/shardev-mcp/audit.jsonl, tanto del servidor MCP como de la CLI (shardev project|app|ops):source(mcpocli; las líneas antiguas no lo traen y eran del MCP), tool (el mismo nombre del catálogo, p. ej.ops_services), proyecto, env, tier, decisión, exit code, duración y argumentos redactados. Una entrada inválida en la CLI queda comorejected; un fallo al escribir la auditoría solo avisa por stderr y no cambia la salida ni el código de salida, salvo la entradaintentdeops redeployyops scale: si no se puede escribir, no se cambia nada en AWS. Unaintentsin suresultsignifica que el cambio pudo aplicarse.mcp serve,--helpy--versionno escriben nada.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 buildLos 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).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Related MCP Connectors
Build, deploy and manage MaShop e-commerce projects from Claude, Cursor or any MCP client.
Manage Pipefork API projects, drafts, connections, secrets, and deployments through MCP.
Build, deploy, and host full-stack web apps from any MCP client. DB, auth, storage, cron included.
Create, deploy, and operate MCP servers directly from your GitHub repositories.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceIntegrates with the Laravel Forge API to provide comprehensive management of servers and sites. It enables users to perform health checks, monitor logs, create resources, and execute deployment tasks through MCP-compliant tools.52 npm2MIT
- AlicenseBqualityDmaintenanceMCP server for Laravel Cloud to manage projects, environments, deployments, and other resources.98ISC
- AlicenseNot gradedqualityBmaintenanceBootstraps dev environments by installing, wiring, and verifying CLI tools and MCP servers from curated recipes, and provides scope-aware audit of MCP configurations.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables managing local repositories, CLIs, MCP servers, and skills via MCP tools, with inventory tracking, guarded updates, and Docker-sandboxed trials.MIT