https://github.com/mcp-tool-shop-org/forkctl
Adoption control plane for GitHub repos. MCP server + CLI: assess, choose path, fork or template, bootstrap, sync.
https://github.com/mcp-tool-shop-org/forkctl
cli fork github mcp model-context-protocol template typescript
Last synced: 17 days ago
JSON representation
Adoption control plane for GitHub repos. MCP server + CLI: assess, choose path, fork or template, bootstrap, sync.
- Host: GitHub
- URL: https://github.com/mcp-tool-shop-org/forkctl
- Owner: mcp-tool-shop-org
- License: mit
- Created: 2026-04-19T22:29:44.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-21T03:58:29.000Z (2 months ago)
- Last Synced: 2026-04-21T05:34:21.762Z (2 months ago)
- Topics: cli, fork, github, mcp, model-context-protocol, template, typescript
- Language: TypeScript
- Homepage: https://mcp-tool-shop-org.github.io/forkctl/
- Size: 581 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.es.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
日本語 | 中文 | English | Français | हिन्दी | Italiano | Português (BR)
Control de adopción para repositorios de GitHub. No es un envoltorio para bifurcaciones, sino una capa integral que evalúa la preparación para la adopción, elige la ruta de duplicación adecuada, la ejecuta como una operación asíncrona supervisada, mantiene el resultado ejecutable, lo mantiene sincronizado con el tiempo y, novedad en la versión 1.1.0, lo renombra de manera coherente cuando esté listo para considerarlo suyo.
## Novedades en la versión 1.1.0
Capa 7: **Renombramiento políglota con conocimiento de la estructura del árbol sintáctico (AST).** El comando `forkctl rename plan` genera una diferencia (diff) que se puede revisar, que abarca archivos de identidad, símbolos de código (26 lenguajes a través de ast-grep) y superficies textuales no relacionadas con el código. El comando `forkctl rename apply` crea una instantánea del árbol, ejecuta todas las fases, regenera los archivos de bloqueo y deja un manifiesto de regeneración de activos para cualquier elemento binario. El comando `forkctl rename rollback` restaura la última instantánea. No utiliza cadenas de comandos `sed`. Corrige los límites de las palabras. Considera las mayúsculas y minúsculas.
## ¿Qué hace Forkctl?
Bifurcar un repositorio de GitHub es un solo clic. Adoptarlo, es decir, elegir entre bifurcar o usar una plantilla, gestionar las políticas de la organización, esperar a que se complete la creación asíncrona, configurar la sincronización con el repositorio original y hacer que el resultado sea realmente utilizable, eso es todo lo demás.
Forkctl se encarga de "todo lo demás".
| Capa | ¿Qué hace? |
|--------------|-----------------------------------------------------------------------------------------------|
| Evaluación | Evalúa la preparación de un repositorio para la adopción, recomienda bifurcar, usar una plantilla o importar, y sugiere correcciones en el repositorio original. |
| Ejecución | Crea la copia como una operación asíncrona supervisada. Identifica de antemano posibles bloqueos relacionados con las políticas de bifurcación de la organización o la empresa. |
| Configuración inicial | Configuración posterior basada en perfiles: sincronización con el repositorio original, actualizaciones del archivo README, análisis de desviaciones y entrega del resultado listo para usar. |
| Sincronización | Utiliza la API de GitHub para fusionar los cambios con el repositorio original. Informa de forma transparente sobre cualquier divergencia. Si es necesario, recurre a la creación de una solicitud de extracción (PR). |
| Gestión | Lista, verifica el estado y sincroniza por lotes tus bifurcaciones. |
| Registros | Registro legible por máquina de cada operación. Registro de auditoría en SQLite local. |
| Renombrar | Renombramiento políglota con conocimiento de la estructura del árbol sintáctico: archivos de identidad, símbolos de código, superficies textuales, regeneración de archivos de bloqueo. |
## Formas de uso
Forkctl se ofrece tanto como un **servidor MCP** (transporte a través de stdio, para clientes MCP como Claude Code) como una **interfaz de línea de comandos (CLI)** con la misma funcionalidad.
### MCP
Añade lo siguiente a la configuración de tu cliente MCP:
```json
{
"mcpServers": {
"forkctl": {
"command": "npx",
"args": ["-y", "@mcptoolshop/forkctl", "mcp"],
"env": { "GITHUB_TOKEN": "ghp_..." }
}
}
}
```
### CLI
```bash
npx @mcptoolshop/forkctl assess owner/repo
npx @mcptoolshop/forkctl choose-path owner/repo --goal contribute_upstream
npx @mcptoolshop/forkctl create-fork owner/repo --destination-org my-org
npx @mcptoolshop/forkctl sync my-fork
npx @mcptoolshop/forkctl fleet-health
```
Todos los comandos aceptan la opción `--json` para obtener una salida legible por máquina.
## Las veintidós herramientas
### Evaluación
- `forkctl_assess`: puntuación de preparación para la adopción, bloqueos, fortalezas.
- `forkctl_choose_path`: bifurcar | plantilla | importar | clonar (sin seguimiento).
- `forkctl_make_forkable`: corrige el repositorio original (por defecto: plan; opcional: PR).
### Ejecución
- `forkctl_preflight_policy`: detecta bloqueos relacionados con las políticas de bifurcación de la empresa/organización/repositorio.
- `forkctl_create_fork`: crea una bifurcación de forma asíncrona, devuelve un ID de operación.
- `forkctl_create_from_template`: utiliza la función `/generate` de GitHub.
- `forkctl_check_operation`: verifica el estado de cualquier operación en curso.
### Configuración inicial
- `forkctl_bootstrap`: configuración inicial basada en perfiles (contribuidor / kit de inicio / repositorio semilla interno / entrega al cliente / experimento).
- `forkctl_configure_upstream`: configura el repositorio remoto y, opcionalmente, el flujo de sincronización.
- `forkctl_scan_drift`: busca rutas codificadas, secretos filtrados y referencias obsoletas del sistema de integración continua (CI) en la copia.
- `forkctl_emit_handoff`: genera un único artefacto con información precisa: URLs, comandos, advertencias y la siguiente acción a realizar.
### Sincronización
- `forkctl_sync`: API de GitHub para fusionar los cambios con el repositorio original.
- `forkctl_diagnose_divergence`: muestra los commits pendientes, los archivos en riesgo y los posibles conflictos.
- `forkctl_propose_sync_pr`: propone una solicitud de extracción (PR) para la sincronización cuando la fusión rápida falla.
### Gestión
- `forkctl_list_forks`: lista tus bifurcaciones y las que estás siguiendo, con una columna de estado.
- `forkctl_fleet_health`: verifica el estado de las bifurcaciones (obsoletas, con conflictos o abandonadas).
- `forkctl_batch_sync`: sincroniza por lotes, teniendo en cuenta los límites de velocidad.
### Registros
- `forkctl_receipt`: registro legible por máquina de cualquier operación.
- `forkctl_audit_log`: historial de solo escritura.
### Renombrar (Capa 7: novedad en la versión 1.1.0)
- `forkctl_rename_plan`: planificador de renombramiento con conocimiento de la estructura del árbol sintáctico; genera una diferencia que se puede revisar.
- `forkctl_rename_apply`: crea instantáneas y aplica cambios a archivos de identidad, símbolos, texto y fases posteriores.
- `forkctl_rename_rollback`: restaura a partir de la última instantánea.
## Perfiles de configuración inicial
| Perfil | Para | Configuración posterior |
|---------------------|--------------------------------------------------------------------|---------------------------------------------------------------------------------|
| `contributor` | Bifurcar para enviar solicitudes de extracción al repositorio original | Repositorio remoto, flujo de sincronización, bloque de información para colaboradores en el archivo README, plantilla de solicitud de extracción (si no existe). |
| `starter-kit` | Generado a partir de una plantilla para iniciar tu propio producto. | Elimina las referencias a la plantilla, crea un nuevo archivo README, muestra una nueva solicitud para el archivo LICENSE y crea un archivo .env.example. |
| `internal-seed` | Copia interna de un repositorio semilla compartido para un equipo. | Reemplaza los marcadores de posición, configura los propietarios del código internos y restringe la visibilidad. |
| `client-delivery` | Bifurcación específica para cada cliente de un producto. | Ramas con el nombre del cliente, verificación de historial limpio y rama predeterminada bloqueada. |
| `experiment` | Copia desechable / sin seguimiento. | Desconectar del repositorio principal, marcar como experimento en el archivo README, sin flujo de trabajo de sincronización. |
## Configuración
| Variable | Requerida | Valor predeterminado | Notas |
|----------------------|----------|----------------------------------------------|-------------------------------------------------|
| `GITHUB_TOKEN` | sí | — | `repo`, `workflow`, `read:org` (alcances) |
| `GITHUB_API_URL` | no | `https://api.github.com` | Para GHES / ghe.com |
| `FORKCTL_STATE_DIR` | no | Directorio de estado del usuario del sistema operativo (a través de `env-paths`). | Ubicación de las operaciones de SQLite y la base de datos de auditoría. |
## Seguridad
Consulte [SECURITY.md](SECURITY.md) para obtener información sobre el modelo de amenazas y la política de informes. Puntos clave:
- El token `GITHUB_TOKEN` nunca se registra.
- Cada entrada de herramienta se valida mediante Zod.
- `make_forkable` tiene como valor predeterminado el modo "plan". El modo "pr" es opcional.
- Forkctl nunca realiza "push" forzados, elimina repositorios ni elimina ramas.
- No hay telemetría. No hay llamadas salientes excepto las llamadas a la API de GitHub configurada.
## Estado
Versión 1.1.0: añade la Capa 7 (Renombrar). Construido según la puerta [shipcheck](https://github.com/mcp-tool-shop-org/shipcheck).
Consulte [SHIP_GATE.md](SHIP_GATE.md) para obtener la puntuación de la puerta.
## Licencia
MIT — consulte [LICENSE](LICENSE).
---
Built by MCP Tool Shop