MCPunk 🤖

Chatea con tu base de código sin incrustaciones brindándole a LLM herramientas para buscar tu código de manera inteligente.

MCPunk te permite explorar y comprender bases de código mediante la conversación. Funciona de la siguiente manera:

1. Dividir archivos en fragmentos lógicos (funciones, clases, secciones de rebajas)
2. Proporcionar al LLM herramientas para buscar y consultar estos fragmentos
3. Permitir que el LLM encuentre el código específico que necesita para responder a sus preguntas

Sin incrustaciones ni configuraciones complejas: solo una búsqueda clara y auditable que puedes ver y guiar. Funciona a la perfección con Claude Desktop o cualquier otro cliente MCP .

Repositorio de GitHub

Creado con lo siguiente en mente

• El contexto es el rey : los LLM pueden ser excelentes, pero solo si se proporcionan con el contexto apropiado.
• El contexto es valioso : los LLM necesitan contexto, pero no pueden abarcar demasiado. ¡Una farsa! MCPunk es un RAG que proporciona inherentemente pistas contextuales al LLM, lo que le permite centrarse únicamente en el contenido relevante.
• Human in the Loop : puedes ver exactamente qué datos ha considerado el LLM y cómo los encontró. Puedes ingresar al chat y dirigir las cosas a donde quieras.

Configuración

Estas son instrucciones para Claude Desktop, pero MCPunk se puede utilizar en cualquier lugar donde se utilice MCP.

1. Instalar uv
2. Coloque el siguiente fragmento en su claude_desktop_config.json ( detalles sobre claude_desktop_config.json incluida la ubicación )
3. Reinicie Claude Desktop y debería ver las herramientas disponibles después de un pequeño retraso, como la captura de pantalla a continuación.
4. Charla : "Hola amigo, ¿puedes configurar el proyecto ~/git/mcpunk y decirme cómo se fragmentan los archivos de Python?"

( "command": "uvx", podría no funcionar y es posible que tengas que usar, por ejemplo "command": "/Users/michael/.local/bin/uvx", )

Ejemplos de uso

Responda preguntas sobre su base de código

• [Usuario] Hola amigo, ¿puedes configurar el repositorio ~/git/mcpunk y luego ayudarme a entender cómo un usuario de mcpunk obtendría la diferencia de git de la rama actualmente extraída en el repositorio que ha configurado con mcpunk?
• [Claude] Llamar configure_project
• [Claude] Llamar list_all_files_in_project
• [Claude] Llamar find_files_by_chunk_content
• [Claude] ... realiza un total de 21 llamadas de herramientas con MCPunk.
• [Claude] Ahora entiendo cómo funciona la función de diff de Git en McPunk. Resumo cómo un usuario obtendría el diff de Git de la rama actualmente extraída: Para obtener el diff de Git de la rama actualmente extraída en un repositorio configurado con McPunk:
  1. Primero, el usuario debe configurar mcpunk para que funcione con su proyecto utilizando la herramienta configure_project
  2. Para ver qué ramas se han verificado recientemente (para identificar con qué comparar)
  3. Luego, para obtener la diferencia entre la rama actual (HEAD) y una rama de referencia, se mostrarán las diferencias entre la rama actual (HEAD) y la rama de referencia especificada. El parámetro "ref" debe ser el nombre de la rama base (como "main" o "develop") con la que se desea comparar.
• [Usuario] ¡Buen trabajo amigo!

Revisión de relaciones públicas

• [usuario] Hola amigo, ¿puedes configurar el repositorio ~/git/mcpunk y echar un vistazo a la rama actual en comparación con scratch/1.5
• [Claude] Configura ~/git/mcpunk y llama a diff_with_ref para la referencia scratch/1.5
• [Claude] Veo que has realizado varios cambios, principalmente agregando un nuevo archivo de prueba tests/test_git_analysis.py ...
• [usuario] ¿Cómo encaja esto en el resto del código base?
• [Claude] Realiza 5 llamadas a herramientas para listar archivos por fragmentos, listar fragmentos y obtener detalles de los fragmentos
• [Claude] Ya veo: el código analiza la salida de reflog de Git para rastrear las ramas extraídas recientemente. La función principal get_recent_branches toma la ruta del repositorio y devuelve las últimas N ramas extraídas, usando _branches_from_reflog como ayuda para analizar la salida de reflog sin procesar.
• [Usuario] Si tuviera prisa y tuviera que pedirle a alguien que revisara este trabajo, ¿qué le pediría que revisara? Por favor, describa fragmentos de trabajo específicos.
• [Claude]
  • La split("to ")[-1] en _branches_from_reflog parece frágil
  • Los datos de prueba solo muestran nombres de ramas simples, ¿qué pasa con los espacios/caracteres especiales?
  • ¿Es example_reflog representativo de la salida real de reflog de Git?
  • ¿Estamos probando contra el comportamiento real de Git?
• [Usuario] ¡Eres el mejor!

Trabajar en múltiples bases de código

Puedes pedirle a tu LLM que configure varios proyectos y podrá consultarlos libremente. Esto es útil si uno depende del otro y se encuentran en repositorios diferentes. En este caso, el LLM debería reconocerlo mediante importaciones.

¿Qué es MCPunk y otros antecedentes?

MCPunk es un servidor MCP que proporciona herramientas para

• Configura un proyecto, que es un directorio de archivos. Al configurarlo, los archivos se dividirán en fragmentos lógicos. MCPunk está diseñado para código, pero en realidad se puede aplicar a cualquier documento, incluso imágenes si se desea.
• Buscar archivos en un proyecto que contengan texto específico
• Buscar fragmentos en un archivo que contengan texto específico
• Ver el contenido completo de un fragmento específico

Además de esto, proporciona algunos fragmentos integrados. El más maduro es el fragmento de Python.

MCPunk no tiene por qué usarse para conversaciones. Puede usarse, por ejemplo, como parte de la revisión de código en una canalización de integración continua (CI). Es un RAG bastante general.

Curso intensivo de Roaming RAG

Ver

• https://arcturus-labs.com/blog/2024/11/21/roaming-rag--make-*the-model*-find-the-answers/
• https://simonwillison.net/2024/Dec/6/roaming-rag/

La esencia del roaming RAG es

1. Divide el contenido (una base de código, archivos PDF, etc.) en fragmentos. Cada fragmento es un elemento lógico pequeño, como una función, una sección en un documento de Markdown o todas las importaciones en un archivo de código.
2. Proporcionar las herramientas LLM para buscar fragmentos. MCPunk lo hace proporcionando herramientas para buscar archivos que contengan fragmentos con texto específico y para listar el contenido completo de un fragmento específico.

En comparación con el RAG de "búsqueda vectorial" más tradicional:

• El LLM tiene que profundizar para encontrar fragmentos y, naturalmente, es consciente de su contexto más amplio (como en qué archivo se encuentran).
• Los fragmentos siempre deben ser coherentes. Como una función completa.
• Puede ver exactamente lo que está buscando el LLM y, en general, es obvio si está buscando deficientemente y puede ayudarlo sugiriendo términos de búsqueda mejorados.
• Requiere una búsqueda exacta. MCPunk no ofrece búsquedas difusas de ningún tipo.

Trozos

Un fragmento es una subsección de un archivo. Por ejemplo,

• Una sola función de Python
• Una sección de rebajas
• Todas las importaciones desde un archivo Python

Los fragmentos se crean a partir de un archivo mediante fragmentadores , y MCPunk viene con unos cuantos incorporados.

Al configurar un proyecto en MCPunk, este revisa todos los archivos y le aplica el primer fragmento correspondiente. El LLM puede entonces usar herramientas para (1) consultar archivos que contengan fragmentos con texto específico, (2) consultar todos los fragmentos de un archivo específico y (3) obtener el contenido completo de un fragmento.

Esta base permite a Claude navegar de manera efectiva por bases de código relativamente grandes, comenzando con una búsqueda amplia de archivos relevantes y concentrándose en las áreas relevantes.

Fragmentos incorporados:

• PythonChunker fragmenta los datos en clases, funciones, importaciones a nivel de archivo y sentencias a nivel de archivo (p. ej., globales). Aplicable a archivos con extensión .py
• VueChunker divide el contenido en fragmentos de "plantilla", "script", "estilo" o cualquier elemento de nivel superior <blah>....</blah> Aplicable a archivos que terminan en .vue
• MarkdownChunker fragmenta los elementos en secciones de Markdown (por encabezado). Aplicable a archivos con extensión .md
• WholeFileChunker fragmentador de respaldo que crea un único fragmento para todo el archivo. Aplicable a cualquier archivo.

Cualquier fragmento de más de 10 000 caracteres (configurable) se divide automáticamente en varios fragmentos, con nombres con el sufijo part1 , part2 , etc. Esto ayuda a evitar la pérdida de contexto y, al mismo tiempo, permite una navegación razonable de los fragmentos.

Trozos personalizados

Cada tipo de archivo (p. ej., Python vs. C) necesita un fragmentador personalizado. MCPunk viene con algunos integrados . Si ningún fragmentador específico coincide con un archivo, se utiliza un fragmentador predeterminado que simplemente lo integra en un solo fragmento.

La forma sugerida actual de agregar fragmentos es bifurcar este proyecto, agregarlos y ejecutar MCPunk según Development . Para agregar un fragmento

• Agréguelo en file_chunkers.py , heredando de BaseChunker
• Agréguelo a ALL_CHUNKERS en file_breakdown.py

Sería posible implementar algún tipo de sistema de complementos para que los módulos anuncien que tienen fragmentos personalizados para que MCPunk los use, como el sistema de complementos de Pytest, pero actualmente no hay planes para implementar esto (a menos que alguien quiera hacerlo).

Limitaciones

• A veces, LLM no es eficaz en la búsqueda. Por ejemplo, al buscar "dependencia", se omite el término "dependencias". Hay espacio para la búsqueda de elementos.
• A veces, LLM intentará encontrar una pieza específica de código crítico pero no lo encontrará y luego continuará sin reconocer que tiene un conocimiento contextual limitado.
• Los proyectos "grandes" no están bien probados. Un proyecto con unos 1000 archivos Python que contienen un total de unos 250 000 LoC funciona bien. Su configuración tarda unos 5 s. A medida que aumenta el tamaño de la base de código, aumenta el tiempo de fragmentación inicial y probablemente se requieran búsquedas más sofisticadas. El código no suele escribirse pensando en bases de código masivas; verás cosas como todos los datos almacenados en memoria, búsquedas iteradas sobre todos los datos y varios aspectos que requieren una optimización básica.
• Los proyectos pequeños probablemente funcionen mejor con todo el código concatenado y contextualizado. MCPunk solo es apropiado cuando esto no es práctico.
• En algunos casos, sería mejor permitir que LLM capture un archivo completo en lugar de que seleccione fragmentos uno a uno. MCPunk no cuenta con un mecanismo para esto. En la práctica, no he encontrado que esto sea un problema grave.

Configuración

Se pueden configurar varias opciones mediante variables de entorno con el prefijo MCPUNK_ . Para ver las opciones disponibles, consulte settings.py ; estas se cargan desde las variables de entorno mediante Pydantic Settings .

Por ejemplo, para configurar la opción include_chars_in_response :

Hoja de ruta y estado del desarrollo

MCPunk se considera casi completo. No se ha utilizado ampliamente, y como usuario, es probable que encuentre errores o imperfecciones. Se agradecen los informes de errores en https://github.com/jurasofish/mcpunk/issues.

Ideas para la hoja de ruta

• Añade varias indicaciones para ayudarte a usar MCPunk. Sin indicaciones reales del tipo "explícale cómo hacer un panqueque a un extraterrestre", el juego se queda un poco corto.
• Incluya comentarios a nivel de módulo al extraer declaraciones a nivel de módulo de Python.
• Posiblemente derivado de una búsqueda
• Cambiar todo el concepto de "proyecto" para no necesitar que los archivos realmente existan: esto lleva a permitir archivos "virtuales" dentro del proyecto.
  • Considere cambiar los archivos que tienen una ruta a que tengan un URI, por lo que podría ser algo como file://... / http[s]:// / gitdiff:// / etc. URI arbitrarios
• Fragmentación de diffs de Git. Actualmente, existe una herramienta para obtener un diff completo. Este podría ser muy grande. En su lugar, se podría cambiar la herramienta a add_diff_to_project , que coloca los archivos bajo la URI gitdiff:// o en una ruta falsa.
• Almacenamiento en caché de un proyecto, para que no sea necesario volver a analizar todos los archivos cada vez que se reinicia el cliente MCP. Esto puede ser complicado, ya que los cambios en el código de un chunker invalidarán la caché. Probablemente no se priorice, ya que no es tan lento para mis casos de uso.
• Capacidad de los usuarios de proporcionar código personalizado para realizar fragmentación, tal vez similar a los complementos de PyTest
• Algo como Tree Sitter podría usarse para un chunker más genérico.
• Seguimiento de caracteres enviados/recibidos, idealmente por chat.
• Estado, registro, etc. por chat

Desarrollo

ver run_mcp_server.py .

Si configura Claude Desktop como se muestra a continuación, puede reiniciarlo para ver los últimos cambios mientras trabaja en MCPunk desde su versión local del repositorio.

Pruebas, pelusas, CI

Vea los flujos de trabajo de Makefile y acciones de Github.