Loading repository data…
edsadr / repository
Agente de reporting inteligente para repositorios Open Source, construido con **[Mastra](https://mastra.ai)** y **TypeScript**. Analiza actividad de desarrollo, features, issues y discusiones de cualquier repositorio de GitHub
Este repositorio contiene el código del workshop "Construyendo un Agente de Reporting Open Source con Mastra y TypeScript".
Antes de comenzar el taller, asegúrate de tener instaladas las siguientes herramientas:
Clona este repositorio.
Instala las dependencias:
pnpm install
Crea tu archivo de variables de entorno .env en la raíz del proyecto, tomando como base el archivo .env.example:
cp .env.example .env
Añade tus credenciales:
GOOGLE_GENERATIVE_AI_API_KEY="tu-api-key"
GITHUB_PERSONAL_ACCESS_TOKEN="tu-github-pat"
Este repositorio ya viene con Mastra inicializado.
Si quieres repetir el proceso de scaffolding desde cero siguiendo la documentación actual de Mastra, puedes usar cualquiera de estas opciones:
pnpm create mastra
pnpm dlx create-mastra@latest
En este workshop partimos del proyecto ya creado, así que para el módulo 1 basta con revisar la estructura base y ejecutar Studio.
Los archivos principales del proyecto actual están en:
src/mastra/index.tssrc/mastra/agents/oss-reporter-agent.tssrc/mastra/mcp/github-mcp-client.tssrc/mastra/tools/repository-analysis-tools.tsEn este módulo, la adaptación principal consiste en limpiar el scaffold inicial y dejar un agente base enfocado en OSS Reporter.
Para arrancar el entorno de desarrollo local y acceder a la interfaz de prueba e interacciones:
pnpm run dev
Abre tu navegador en http://localhost:4111 e interactúa con el agente desde Studio. Allí puedes probar el agente base y revisar los logs y trazas que se guardan con la configuración de observabilidad del proyecto.
Para instalar las Mastra Skills siguiendo la documentación actual:
pnpm dlx skills add mastra-ai/skills
Para consultar el archivo de contexto raíz de la documentación:
https://mastra.ai/llms.txt
Si quieres configurar el Mastra MCP Docs Server en una herramienta compatible con MCP, usa la guía oficial de tu editor y una configuración equivalente a:
{
"mcpServers": {
"mastra": {
"type": "stdio",
"command": "pnpm",
"args": ["dlx", "@mastra/mcp-docs-server@latest"]
}
}
}
Documentación oficial consultada para este módulo:
https://mastra.ai/guides/getting-started/quickstartcreate-mastra: https://mastra.ai/reference/cli/create-mastrahttps://mastra.ai/docs/build-with-ai/skillshttps://mastra.ai/docs/getting-started/build-with-aihttps://mastra.ai/docs/build-with-ai/mcp-docs-serverEn el estado actual del proyecto, el agente ya está conectado al GitHub MCP Server usando el cliente MCPClient de @mastra/mcp.
src/mastra/mcp/github-mcp-client.tshttps://api.githubcopilot.com/mcp/GITHUB_PERSONAL_ACCESS_TOKENOSS ReporterCon GITHUB_PERSONAL_ACCESS_TOKEN configurado y pnpm run dev activo, puedes pedirle al agente tareas como:
Lee el README de edsadr/oss-reporter
Lista los issues recientes de edsadr/oss-reporter
Muestra las ramas activas de edsadr/oss-reporter
Si la autenticación falla o el token no está presente, el agente debería indicarlo explícitamente.
Sobre el contexto recuperado desde GitHub MCP, el proyecto ahora incluye tools nativas de Mastra para estructurar el análisis del repositorio.
src/mastra/tools/repository-analysis-tools.tsanalyzeDevelopmentToolanalyzeFeaturesToolanalyzeDevelopmentTool
commitCount, branchCount, developmentMomentum, keySignals y recommendedFocusanalyzeFeaturesTool
openPullRequestCount, featureMomentum, proposedCapabilities y recommendedFocusAmbas tools usan inputSchema y outputSchema con zod para asegurar respuestas estructuradas y predecibles en formato JSON.
El flujo implementado hasta este punto es:
En el estado actual del proyecto, el módulo 4 combina dos capas complementarias:
Observational Memory
RAG local
El agente OSS Reporter usa @mastra/memory con:
lastMessages: 12generateTitle: trueobservationalMemory con:
model: google/gemini-2.5-flashscope: threadEste enfoque es especialmente útil porque el agente combina:
La primera fuente documental del RAG es:
docs/open-source-maintainers-guide.mdEse documento contiene buenas prácticas para maintainers open source sobre:
La infraestructura del knowledge base vive en:
src/mastra/rag/workshop-knowledge-base.tsY la tool expuesta al agente es:
src/mastra/tools/workshop-knowledge-tool.tssearchWorkshopKnowledgeToolsearchWorkshopKnowledgeToolEsta tool:
El flujo del agente a partir del módulo 4 es:
Con pnpm run dev activo, puedes hacer preguntas como:
¿Cuáles son las mejores prácticas para hacer triage de issues en un proyecto open source?
¿Qué recomienda nuestra base de conocimiento sobre sostenibilidad para maintainers?
Resume buenas prácticas para revisión de pull requests en proyectos open source
El proyecto ahora usa un patrón supervisor + subagentes para repartir trabajo especializado.
El agente principal OSS Reporter ahora actúa como supervisor:
La coordinación vive en:
src/mastra/agents/oss-reporter-agent.tssrc/mastra/agents/issue-analyst-agent.ts
src/mastra/agents/discussion-analyst-agent.ts
El análisis estructurado de la capa comunitaria vive en:
src/mastra/tools/community-analysis-tools.tsTools incluidas:
analyzeIssuesTool
analyzeDiscussionsTool
El supervisor usa hooks de delegación para:
El flujo del agente a partir del módulo 5 es:
Con pnpm run dev activo, puedes probar prompts como:
Analiza los issues abiertos de owner/repo y prioriza el triage para la próxima semana
Resume las discusiones activas de owner/repo e identifica decisiones o preguntas abiertas
Coordina un análisis del repositorio owner/repo: desarrollo reciente, issues críticos y discusiones relevantes
El siguiente paso del workshop introduce una capa determinista para ensamblar un reporte final reutilizando todo lo construido antes.
src/mastra/workflows/repository-report-workflow.tsEl workflow:
owner, repo, reportType y focusossReporterAgent para desarrollo y featuresissueAnalystAgent para issuesdiscussionAnalystAgent para discusionessearchWorkshopKnowledgeTool para reforzar recomendaciones con buenas prácticas de maintainers1 a 3 tareas accionablesreports/weeklymaintainer-triagerelease-readinessEl workflow produce:
El workflow queda registrado en src/mastra/index.ts como:
repositoryReportWorkflowUna vez levantado Mastra, puedes ejecutar el workflow con inputs como:
{
"owner": "edsadr",
"repo": "oss-reporter",
"reportType": "weekly",
"focus": "priorizar mantenimiento y claridad del backlog"
}
El módulo 7 introduce una capa de evaluación centrada en agentes. En lugar de medir sólo la calidad del reporte final, ahora el proyecto también evalúa cómo se comportan el supervisor y los subagentes especializados.
Selected from shared topics, language and repository description—not editorial ratings.
Socrates-Programmer /
WorkOrder Portal es una aplicación fullstack con Next.js, React, Node.js y TypeScript para gestionar órdenes de trabajo y tickets. Permite crear, asignar y dar seguimiento a solicitudes con prioridades, comentarios y archivos adjuntos. Incluye dashboard con métricas, reportes en CSV y roles de usuario (cliente, agente, admin).