GitPrism

GitPrism es un pipeline rápido, eficiente en tokens y sin estado que convierte repositorios públicos de GitHub en Markdown listo para LLM.

GitHub

Prueba este MCPPatrocinado

Documentación

GitPrism

Dashboard

Un pipeline rápido, eficiente en tokens y sin estado que convierte repositorios públicos de GitHub en Markdown listo para LLM. Desplegado como un único Cloudflare Worker que sirve a humanos, agentes de IA y clientes MCP desde un mismo motor central compartido.

                    ┌─────────────────────────────────────────────┐
                    │          Single Cloudflare Worker            │
                    │               (gitprism)                    │
                    │                                             │
   Humans ────────► │  /              → Astro Static UI           │
                    │                   (Workers Static Assets)   │
                    │                                             │
   AI Agents ─────► │  /ingest?...    → REST API                  │
                    │  /<github-url>  → URL Proxy (shorthand)     │
                    │                                             │
   MCP Clients ───► │  /mcp           → Stateless MCP Server      │
                    │                   (createMcpHandler)        │
                    │                                             │
                    │         ┌───────────────────┐               │
                    │         │   Core Engine      │               │
                    │         │  URL Parser        │               │
                    │         │  Zipball Fetch     │               │
                    │         │  fflate Decomp     │               │
                    │         │  Filter/Ignore     │               │
                    │         │  MD Formatter      │               │
                    │         └───────────────────┘               │
                    └─────────────────────────────────────────────┘
                                       │
                                       ▼
                              GitHub Zipball API
                          (authenticated via secret)

Autenticación

GitPrism admite tokens de acceso personal de GitHub opcionales para evitar los límites de tasa compartidos y usar tu cuota personal de la API de GitHub.

Límites de tasa predeterminados

Sin autenticación: 30 solicitudes por minuto por dirección IP
Con token del servidor: Compartido entre todos los usuarios (5,000 req/h para la IP del Worker)
Con token de usuario: Tu cuota personal de GitHub (5,000 solicitudes por hora)

Usar tu propio token

API REST:

curl -H "X-GitHub-Token: ghp_xxxx" https://gitprism.cloudemo.org/ingest?repo=owner/repo

Interfaz web: Haz clic en el ícono de configuración ⚙️ en la barra de búsqueda para abrir el panel de configuración del token. Tu token se almacena en localStorage y nunca se envía a ningún servidor que no sea GitHub a través de este Worker.

Herramienta MCP:

{
  "url": "https://github.com/owner/repo",
  "detail": "full",
  "github_token": "ghp_xxxx"
}

Requisitos del token

Alcance: Contenido: Solo lectura
Acceso al repositorio: Solo repositorios públicos
Crear token: https://github.com/settings/tokens?type=beta

Encabezados de respuesta

El encabezado X-Token-Source indica qué token se usó:

user — Tu token personal (a través del encabezado X-GitHub-Token)
server — El token compartido del Worker
none — No hay token disponible

Uso

Interfaz web

Visita https://gitprism.cloudemo.org/ y pega cualquier URL de GitHub. Usa el panel de configuración (⚙️) para configurar tu token de GitHub.

API REST

Forma canónica (recomendada para uso programático):

GET /ingest?repo=owner/repo&ref=main&path=src&detail=full

Forma abreviada con URL adjunta (amigable para humanos):

GET /https://github.com/owner/repo/tree/main/src

La rama, la referencia y el subdirectorio se extraen automáticamente de la URL de GitHub. Agrega una abreviatura de detalle para controlar la salida:

GET /https://github.com/owner/repo?summary
GET /https://github.com/owner/repo/tree/main/src?file-list

Parámetros (forma canónica):

Parámetro	Obligatorio	Predeterminado	Descripción
`repo`	Sí (canónico)	—	`owner/repo`, p. ej. `cloudflare/workers-sdk`
`ref`	No	rama predeterminada	Rama, etiqueta o SHA de confirmación
`path`	No	—	Subdirectorio para limitar los resultados
`detail`	No	`full`	Nivel de salida: `summary`, `structure`, `file-list` o `full`
`no-cache`	No	`false`	Establécelo en `true` para omitir la caché de respuesta

Abreviatura de nivel de detalle — en lugar de ?detail=<level>, agrega el nivel como una clave simple. Funciona tanto en la forma canónica como en la de proxy de URL:

/ingest?repo=owner/repo&summary
/https://github.com/owner/repo?structure

Niveles de detalle:

Nivel	Abreviatura	Devuelve
`summary`	`?summary`	Front-matter YAML con nombre del repositorio, referencia, recuento de archivos, tamaño total
`structure`	`?structure`	Resumen + árbol de directorios ASCII
`file-list`	`?file-list`	Estructura + tabla de cada archivo incluido con tamaño en bytes y recuento de líneas
`full`	`?full`	Resumen + estructura + contenido completo de los archivos en bloques de código delimitados. Transmitido.

Encabezados de respuesta:

Encabezado	Descripción
`Content-Type`	`text/markdown; charset=utf-8`
`X-Repo`	`owner/repo`
`X-Ref`	Referencia original solicitada (rama, etiqueta o SHA)
`X-Commit-Sha`	SHA de confirmación resuelto usado para la clave de caché
`X-File-Count`	Número de archivos incluidos
`X-Total-Size`	Tamaño total de los archivos incluidos en bytes
`X-Truncated`	`true` si la salida se truncó
`X-RateLimit-Remaining`	Límite de tasa restante de la API de GitHub
`X-RateLimit-Reset`	Marca de tiempo de restablecimiento del límite de tasa de la API de GitHub
`X-Cache`	`HIT` o `MISS`

Respuestas de error (JSON):

Estado	Condición
400	Entrada malformada
404	Repositorio no encontrado o privado
413	El archivo supera el límite de 50 MB
429	Límite de tasa alcanzado (30 req/min por IP, omitido con `X-GitHub-Token`)
502	Error de la API de GitHub

Herramienta MCP

Conecta cualquier cliente compatible con MCP a https://gitprism.cloudemo.org/mcp.

Herramienta disponible: ingest_repo

Argumento	Obligatorio	Predeterminado	Descripción
`url`	Sí	—	URL de GitHub o abreviatura `owner/repo`
`detail`	No	`full`	`summary`, `structure`, `file-list` o `full`
`github_token`	No	—	Tu PAT de GitHub para omitir los límites de tasa

{
  "url": "https://github.com/owner/repo",
  "detail": "summary",
  "github_token": "ghp_xxxx"
}

La herramienta es totalmente compatible con los agentes de Code Mode: el esquema de entrada Zod fuertemente tipado y las anotaciones descriptivas permiten que createCodeTool() del lado del cliente lo envuelva automáticamente.

Despliegue

Opción A — Workers Builds (recomendada)

Workers Builds conecta tu repositorio de GitHub a Cloudflare y se despliega automáticamente en cada push a main. La interfaz de usuario de Astro se compila durante el paso de compilación; ui/dist/ no se confirma intencionalmente en git.

Pasos:

Ve al panel de Cloudflare → Workers & Pages → Crear → Importar un repositorio de Git
Conecta tu cuenta de GitHub y selecciona este repositorio
Configura Configuración de compilación:

Configuración Valor
Rama main
Comando de compilación npm install && npm run build
Comando de despliegue npx wrangler deploy (predeterminado)
Haz clic en Guardar y desplegar — la primera compilación se ejecutará de inmediato
Una vez desplegado, ve a tu Worker → Configuración → Variables y secretos → Agregar un secreto:

Nombre Valor
GITHUB_TOKEN PAT de grano fino con alcance solo lectura de repositorios públicos

Sin este secreto, el Worker sigue funcionando, pero los límites de tasa de la API de GitHub bajan de 5,000 a 60 solicitudes/hora (compartidas entre todas las solicitudes desde la IP saliente del Worker).
Opcional — Dominio personalizado: Worker → Configuración → Dominios personalizados → agrega tu dominio. Esto habilita la API de caché de Workers. Sin un dominio personalizado, el Worker se despliega en <name>.<subdomain>.workers.dev y el almacenamiento en caché no hace nada silenciosamente (el código maneja esto con elegancia). Para habilitar el enrutamiento una vez que tengas un dominio, descomenta y actualiza el bloque routes en wrangler.jsonc:
```
"routes": [
  { "pattern": "yourdomain.com/*", "custom_domain": true }
],
```

Configuración	Valor
Rama	`main`
Comando de compilación	`npm install && npm run build`
Comando de despliegue	`npx wrangler deploy` (predeterminado)

Nombre	Valor
`GITHUB_TOKEN`	PAT de grano fino con alcance solo lectura de repositorios públicos

Opción B — Despliegue manual (CLI de Wrangler)

git clone https://github.com/cougz/gitprism.git
cd gitprism
npm install
npm run build          # builds ui/dist/
npx wrangler secret put GITHUB_TOKEN
npx wrangler deploy

Variables de entorno

Configuradas en wrangler.jsonc bajo vars. Anúlalas en el panel de Cloudflare en Worker → Configuración → Variables y secretos si es necesario:

Variable	Predeterminado	Descripción
`MAX_ZIP_BYTES`	`52428800` (50 MB)	Tamaño máximo del archivo zip antes de rechazar con 413
`MAX_OUTPUT_BYTES`	`10485760` (10 MB)	Tamaño máximo de salida antes del truncamiento
`MAX_FILE_COUNT`	`5000`	Recuento máximo de archivos antes del truncamiento
`CACHE_TTL_SECONDS`	`86400` (24 horas)	TTL de caché para claves de caché basadas en SHA

Secretos

Secreto	Cómo configurarlo	Propósito
`GITHUB_TOKEN`	Panel → Secretos, o `npx wrangler secret put GITHUB_TOKEN`	PAT de grano fino, solo lectura de repositorios públicos. Aumenta el límite de tasa de GitHub de 60 a 5,000 req/h.

Por qué se requiere un paso de compilación

ui/dist/ (el frontend de Astro compilado) está excluido de git. Wrangler lee assets.directory = "./ui/dist" desde wrangler.jsonc y sube esos archivos como activos estáticos durante el despliegue. Si ese directorio no existe en el momento del despliegue, el Worker se despliega sin interfaz de usuario. El paso npm run build compila el código fuente de Astro en ui/src/ hacia ui/dist/ antes de que Wrangler se ejecute.

Desarrollo

# Build the Astro UI (required before deploying or running wrangler dev)
npm run build

# Run tests (169 tests)
npm test

# Watch mode
npm run test:watch

# Type-check
npm run typecheck

# Local dev server (requires ui/dist/ to exist — run npm run build first)
npm run dev

Arquitectura

Estructura del proyecto

gitprism/
├── src/
│   ├── index.ts              # Worker entry point, routing
│   ├── types.ts              # Shared interfaces and error classes
│   ├── engine/
│   │   ├── parser.ts         # URL parsing and validation
│   │   ├── fetcher.ts        # GitHub zipball download + size check
│   │   ├── decompressor.ts   # fflate decompression + processing
│   │   ├── filter.ts         # Ignore lists, .gitignore, binary detection
│   │   ├── formatter.ts      # Markdown output generators (4 levels)
│   │   └── ingest.ts         # Shared pipeline (used by API + MCP)
│   ├── mcp/
│   │   └── server.ts         # createMcpHandler setup
│   ├── api/
│   │   ├── handler.ts        # REST API handler, streaming, caching
│   │   └── llmstxt.ts        # /llms.txt endpoint
│   └── utils/
│       ├── cache.ts          # Workers Cache API helpers
│       ├── ratelimit.ts      # Rate limiting helper
│       └── headers.ts        # Response header builder
├── test/                     # Vitest test files (169 tests)
├── ui/
│   ├── src/                  # Astro source
│   ├── dist/                 # Build output (gitignored)
│   └── astro.config.mjs
├── PLAN.md                   # Detailed implementation plan
└── wrangler.jsonc

Decisiones clave

Decisión	Justificación
Worker único (sin Pages)	Workers Static Assets es el enfoque recomendado. Sin CORS, despliegue más simple.
`createMcpHandler()` (sin Durable Objects)	La herramienta no tiene estado. No se necesita estado por sesión.
`fflate` sobre `jszip`	Descompresión en streaming, paquete más pequeño, menor memoria máxima en aislamientos V8.
`GITHUB_TOKEN` del lado del servidor	Aumenta el límite de tasa de 60 a 5,000 req/h sin autenticación de usuario.
Verificación de tamaño previa	Evita fallos por falta de memoria con repositorios grandes.
API de caché desde el primer día	Repositorio+referencia+detalle idénticos producen salida idéntica. El almacenamiento en caché reduce la latencia y el uso de la API de GitHub.
`TransformStream` en streaming para `full`	Reduce la memoria máxima, mejora el tiempo hasta el primer byte.

Filtrado de archivos

Lista de ignorados codificada

Lo siguiente siempre se excluye independientemente de .gitignore:

Directorios: node_modules/, vendor/, .git/, __pycache__/, .venv/, venv/, dist/, build/, .next/, .nuxt/, .svelte-kit/, .output/, .cache/, .parcel-cache/, coverage/, .tox/, .mypy_cache/

Archivos: package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, Cargo.lock, composer.lock, Gemfile.lock, go.sum, poetry.lock, *.min.js, *.min.css, *.map, *.wasm, *.pb.go, *.pyc, *.pyo

Extensiones binarias: .png, .jpg, .jpeg, .gif, .ico, .webp, .bmp, .tiff, .svg, .woff, .woff2, .ttf, .eot, .otf, .pdf, .zip, .tar, .gz, .bz2, .7z, .rar, .exe, .dll, .so, .dylib, .bin, .o, .a, .mp3, .mp4, .avi, .mov, .mkv, .flac, .wav, .ogg, .sqlite, .db, .DS_Store

Detección de contenido binario: Los archivos que contienen bytes nulos en sus primeros 8 KB se omiten independientemente de la extensión.

Soporte de .gitignore

El .gitignore raíz del repositorio se analiza y aplica. Admite:

Patrones comodín (*.log, **/*.tmp)
Patrones de directorio con barra final (logs/)
Patrones anclados (/build)
Patrones de negación (!important.log)
Comentarios (# this line is ignored)

Limitación: Solo se evalúa el .gitignore raíz. Los archivos .gitignore anidados (p. ej., src/.gitignore) no se admiten en v1.

Compatibilidad con Code Mode

La herramienta MCP ingest_repo es compatible con los agentes de Code Mode por diseño:

Nombre de herramienta claro y descriptivo (ingest_repo)
Descripción de varias oraciones que explica los cuatro niveles de detalle
Esquemas Zod fuertemente tipados con .describe() en cada parámetro
No se necesitan cambios del lado del servidor: las herramientas MCP estándar con esquemas tipados son inherentemente compatibles con Code Mode

Límites

Límite	Valor	Configurable
Tamaño máximo del archivo zip	50 MB	variable de entorno `MAX_ZIP_BYTES`
Tamaño máximo de salida	10 MB	variable de entorno `MAX_OUTPUT_BYTES`
Recuento máximo de archivos	5,000	variable de entorno `MAX_FILE_COUNT`
Límite de tasa (sin token)	30 req/min por IP	enlace de límites de tasa `wrangler.jsonc`
Límite de tasa (token de usuario)	5,000 req/h	Cuota por usuario de GitHub
TTL de caché	24 horas	variable de entorno `CACHE_TTL_SECONDS`

Comportamiento del límite de tasa:

Sin X-GitHub-Token: El limitador de tasa de Cloudflare aplica 30 solicitudes por minuto por IP
Con X-GitHub-Token: El limitador de tasa de Cloudflare se omite; se aplica tu cuota personal de GitHub (5,000 req/h)
El encabezado de respuesta X-Token-Source indica qué token se usó (user, server o none)

Comportamiento del almacenamiento en caché:

Las claves de caché usan SHA de confirmación resueltos para la invalidación automática cuando los repositorios se actualizan. Las entradas de caché antiguas expiran naturalmente después del TTL. Si la resolución del SHA falla, se omite el almacenamiento en caché y siempre se obtienen datos frescos.

Licencia

MIT