Fossick

Explora todo GitHub desde tu agente de IA.

Encuentra librerías, descubre gemas, busca patrones de código y lee código de producción real: en más de 200M de repos, PyPI y npm.

Contenido

• Qué es Fossick
• Ejemplos
• Instalación
• Herramientas
• Por qué Fossick
• Preguntas frecuentes
• Configuración
• Desarrollo
• Licencia

Qué es Fossick

fossick /ˈfɒsɪk/ verbo (australiano/nuevozelandés) — prospectar o buscar gemas, especialmente el tipo de minería a pequeña escala donde se criban lechos de arroyos y relaves antiguos buscando lo que los operadores más grandes pasaron por alto.

Eso es exactamente lo que hace esta herramienta, pero para código.

Fossick le da a tu agente de IA siete herramientas de solo lectura para explorar todo GitHub, PyPI y npm, cubriendo el ciclo completo de descubrimiento de principio a fin:

1. Busca y descubre. Criba más de 200M de repos con clasificación de relevancia multi-consulta, encuentra las librerías pequeñas pero buenas que las herramientas más grandes entierran, consulta paquetes en PyPI y npm.
2. Profundiza en cualquier repo sin clonarlo. Navega el árbol de un repo remoto con filtros de profundidad y glob, lee cualquier archivo en cualquier rama/etiqueta/commit, y ve a la definición de cualquier clase, función o tipo — todo en GitHub remoto, sin necesidad de checkout local.
3. Busca patrones de código en todo GitHub. Búsqueda de texto completo, regex y con cualificadores en todos los archivos públicos — descubre cómo se usa realmente una API en producción, no solo en la documentación.

Útil cada vez que quieras que tu agente acceda al corpus de código más grande del mundo:

• Elige la librería correcta. Encuentra una opción pequeña, enfocada y mantenida activamente para cualquier tarea — no solo la más popular.
• Descubre gemas ocultas. Superficie la librería de 500 estrellas que clasifica más alto en relevancia que la de 50,000 estrellas.
• Profundiza en un repo que encontraste. Recorre su estructura, lee su README, encuentra dónde está definida su API principal — sin git clone.
• Encuentra patrones de uso en código real. Busca cómo se llama una API en producción y luego lee los archivos coincidentes en contexto.
• Inspírate. Mira cómo otros estructuraron proyectos similares, qué patrones usaron, qué compensaciones hicieron.
• Mantente actualizado. Descubre qué está en tendencia, recién lanzado o nuevo en un ecosistema — más allá del corte de entrenamiento de tu modelo.

No hace arqueología de código — git blame, historial de PRs, diffs de versiones. Usa git y gh para eso.

Ejemplos

Una vez que Fossick está conectado, esto es lo que puedes pedirle a tu agente.

Descubre librerías y paquetes

• "Encuéntrame una librería TUI de Rust pequeña y mantenida activamente — algo más nuevo que ratatui."
• "¿Qué está usando la gente en lugar de LangChain estos días?"
• "Muéstrame frameworks web de Python en tendencia lanzados en los últimos 90 días."
• "¿Cuál es una buena alternativa ligera a Pydantic para validación en tiempo de ejecución?"

Profundiza en un repo específico

• "Explora la estructura de astral-sh/uv — ¿qué hay en crates/?"
• "Lee el __init__.py principal de pydantic/pydantic."
• "¿Dónde está definida la clase Stream en anthropics/anthropic-sdk-python?"
• "¿Cuál es la última versión de modelcontextprotocol/python-sdk y cuándo se lanzó?"

Encuentra patrones de código en el mundo real

• "¿Cómo configuran realmente las apps FastAPI de producción el logging estructurado con structlog y asyncio?"
• "Muéstrame ejemplos reales de tokio::select! usado con cancelación por timeout."
• "Encuentra Dockerfiles que construyan imágenes Python multi-etapa con uv."
• "¿Cómo llama la gente al endpoint de streaming de la API de OpenAI desde Go?"

Evalúa una dependencia antes de adoptarla

• "¿La librería requests sigue mantenida?"
• "Compara la frescura de httpx vs aiohttp — fechas de último lanzamiento, actividad reciente."
• "¿Quién usa realmente msgspec? Muéstrame uso real en codebases de producción."
• "Encuentra el repo de GitHub detrás del paquete PyPI polars y verifica su último lanzamiento."

Instalación

Requisito previo: uv — instala con curl -LsSf https://astral.sh/uv/install.sh | sh. Luego uvx descargará y ejecutará Fossick bajo demanda. Sin necesidad de clonar.

Claude Code

Tres ámbitos de instalación. Elige el que coincida con cómo quieres que Fossick esté disponible — globalmente, compartido con tu equipo, o solo para ti en un proyecto. El flag de ámbito controla dónde se escribe la configuración (ámbitos MCP de Claude Code).

Global (recomendado para uso personal)

Disponible en cada proyecto de tu máquina. Almacenado en ~/.claude.json, privado para tu cuenta de usuario.

claude mcp add fossick --scope user uvx fossick-mcp

Compartido con el equipo (commiteado en git)

Almacenado en .mcp.json en la raíz del proyecto, verificado en control de versiones. Cualquiera que clone el repo obtiene el mismo servidor MCP. Úsalo cuando todo el equipo debería tener Fossick.

claude mcp add fossick --scope project uvx fossick-mcp

Solo este proyecto (predeterminado)

El ámbito local es el predeterminado. Solo habilitado en el proyecto actual, solo para ti. Almacenado en ~/.claude.json bajo la ruta de este proyecto — no commiteado, no compartido con colaboradores.

claude mcp add fossick uvx fossick-mcp

Instalación manual

Si prefieres omitir la CLI, escribe la configuración tú mismo. La forma JSON es la misma independientemente del ámbito — solo cambia el archivo:

• ~/.claude.json para ámbito de usuario / local
• .mcp.json (raíz del proyecto) para ámbito de proyecto

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

Otros clientes

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

code --add-mcp '{"name":"fossick","command":"uvx","args":["fossick-mcp"]}'

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

{
  "mcpServers": {
    "fossick": {
      "type": "stdio",
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

codex mcp add fossick -- uvx fossick-mcp

[mcp_servers.fossick]
command = "uvx"
args = ["fossick-mcp"]

git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync

{
  "mcpServers": {
    "fossick": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"]
    }
  }
}

Herramientas

Siete herramientas de solo lectura, organizadas por su rol en el flujo de trabajo de descubrimiento.

Encontrar candidatos

Evaluar un candidato

Buscar código en GitHub

Todas las herramientas son de solo lectura, idempotentes y seguras para auto-aprobar. Cada respuesta termina con pasos siguientes encadenados por pistas para que el agente sepa qué hacer después.

Por qué Fossick

• Construido para el flujo de trabajo de descubrimiento. Las herramientas siguen la forma natural: encontrar candidato → profundizar → leer la API → ver cómo otros la usan. Las sugerencias de pasos siguientes encadenadas mantienen a tu agente en el camino durante todo el ciclo.
• Profundiza en cualquier repo público sin clonar. Explora árboles de repos remotos con filtros de profundidad + glob, lee cualquier archivo en cualquier rama/etiqueta/commit, y ejecuta búsqueda de símbolos basada en AST real para ir a la definición de cualquier clase, función o tipo — todo en GitHub remoto.
• Búsqueda multi-consulta con clasificación inteligente. search_repos acepta una lista de formulaciones en una sola llamada y aplica clasificación de relevancia compuesta que prioriza la coincidencia literal sobre la popularidad bruta — saca a la superficie la gema de 500 estrellas que supera a la de 50,000 estrellas.
• Eficiente con tokens por diseño. 7 herramientas enfocadas (no 30+), salidas en markdown formateado (no volcados JSON), caché TTL, encadenamiento de pistas que reduce las rondas de razonamiento del agente, y búsqueda multi-consulta que agrupa N solicitudes en 1. Cada descripción de herramienta y respuesta está dimensionada para mantener tu presupuesto de contexto libre para trabajo real.
• Consciente de límites de tasa. Rastrea los buckets de la API de Búsqueda y Núcleo de GitHub por separado, duerme en agotamiento, reintenta con backoff exponencial.
• Cero configuración para usuarios de gh. ¿Ya tienes la CLI de GitHub autenticada? Nada que configurar.
• Se lleva bien con otros. De solo lectura, idempotente, seguro para auto-aprobar. Combina Fossick con github-mcp-server cuando también necesites actuar en tus propios repos (issues, PRs, Actions).

Preguntas frecuentes

Configuración

Autenticación

Fossick resuelve un token de GitHub automáticamente:

1. Variables de entorno GH_TOKEN, GITHUB_TOKEN o GITHUB_PERSONAL_ACCESS_TOKEN
2. gh auth token de la CLI de GitHub — no se necesita configuración si ya has iniciado sesión

Para pasar un token explícitamente:

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}

Un token solo necesita acceso de lectura a repositorios públicos (no seleccionar ningún alcance está bien).

Límites de tasa

Fossick rastrea ambos buckets de la API de GitHub y se pausa automáticamente cuando cualquiera de ellos se agota.

Los reintentos usan retroceso exponencial en errores de límite de tasa y errores transitorios. Los resultados se almacenan en caché brevemente para evitar llamadas API redundantes, con TTL más largos para contenido fijado a un SHA de commit específico.

Desarrollo

Requisitos previos

• Python 3.11+
• uv

Configuración

git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync

Ejecutar

Inicia el servidor MCP en stdio (para pruebas manuales o configuración local del cliente MCP):

uv run fossick-mcp

Probar

Pruebas unitarias y de registro — sin red, se ejecutan en segundos:

uv run pytest

Pruebas de integración en vivo — acceden a GitHub real contra modelcontextprotocol/python-sdk@v1.14.0 fijado:

uv run pytest -m live

Compilar

uv build

Produce dist/fossick_mcp-<version>.tar.gz y la rueda correspondiente.

Arquitectura

Consulta CLAUDE.md para el recorrido completo de la arquitectura, patrones clave y la receta para agregar nuevas herramientas.

Historial de estrellas

Licencia

MIT — a buscar sin límite.