FindUnderstandFix

Servidor MCP que conecta Claude con GitHub para guiarte en tu primera contribución open source.

¿Qué es esto?

FindUnderstandFix es un servidor MCP (Model Context Protocol) que le da a Claude 5 herramientas nuevas para ayudarte a contribuir a proyectos open source — sin salir del chat.

💡 No hay comandos que memorizar. Solo habla con Claude de forma natural.

Cómo funciona

┌─────────────────────────────────────────────────────────────────┐
│                        Tú le hablas a Claude                    │
│      "Busca issues de Python para principiantes"                │
└──────────────────────────────┬──────────────────────────────────┘
                               │  MCP (stdio)
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                   FindUnderstandFix Server                      │
│                                                                 │
│  🔍 search_issues        📋 get_issue_detail                    │
│  🧠 explain_issue        🚀 get_contribution_guide              │
│  💡 get_hints                                                   │
└──────────────┬──────────────────────────┬───────────────────────┘
               │                          │
               ▼                          ▼
   ┌───────────────────┐      ┌─────────────────────┐
   │  GitHub REST API  │      │  Claude Haiku (LLM) │
   │  Issues · Repos   │      │  Explain · Hints    │
   └───────────────────┘      └─────────────────────┘

Demo

Ejemplo de conversación real

> Busca issues abiertas en Python para principiantes, respóndeme en español

🔍 Issues abiertas en Python (10 resultados)

1. [Fix incorrect timezone handling in datetime.fromisoformat] — python/cpython
   📅 Hace 1 día | ⭐ 62.4k estrellas | 🏷️ bug, good first issue
   🔗 https://github.com/python/cpython/issues/9821

2. [Add type hints to pathlib.Path methods] — python/cpython
   📅 Hace 3 días | ⭐ 62.4k estrellas | 🏷️ enhancement, good first issue
   🔗 https://github.com/python/cpython/issues/9734
...

> Explícame la issue #1

🧠 EXPLICACIÓN — Fix incorrect timezone handling in datetime.fromisoformat

¿De qué se trata?
Esta issue reporta que datetime.fromisoformat() no interpreta correctamente
los offsets de zona horaria cuando el string incluye el formato "+HH:MM:SS"...

¿Por qué ocurre?
La función solo valida offsets de 5 caracteres (+HH:MM) pero el estándar
ISO 8601 también permite segundos en el offset (+HH:MM:SS)...

¿Cuál es el impacto?
Afecta a cualquier aplicación que procese timestamps internacionales...

¿Por qué es buena para empezar?
El fix es puntual (~15 líneas), hay un test que falla reproducible y
los maintainers dejaron pistas claras en los comentarios.

Requisitos

Node.js v20+          https://nodejs.org
GitHub Token          https://github.com/settings/tokens  (scope: public_repo)
Claude Desktop        https://claude.ai/download
  o Claude Code       npm install -g @anthropic/claude-code
Anthropic API Key     https://console.anthropic.com  (opcional — para explain e hints)

Instalación

Opción A — Instalador automático ✅ Recomendado

Windows:

git clone https://github.com/devch-tech/FindUnderstandFix.git
cd FindUnderstandFix
.\install.ps1

macOS / Linux:

git clone https://github.com/devch-tech/FindUnderstandFix.git
cd FindUnderstandFix
chmod +x install.sh && ./install.sh

El instalador hace todo: verifica Node.js, compila, pide los tokens y actualiza la config de Claude.

Opción B — Instalación manual

1. Clonar y compilar

git clone https://github.com/devch-tech/FindUnderstandFix.git
cd FindUnderstandFix
npm install && npm run build

2. Agregar a Claude Code — edita ~/.claude.json:

{
  "mcpServers": {
    "findunderstandfix": {
      "command": "node",
      "args": ["/ruta/absoluta/FindUnderstandFix/dist/server/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      },
      "type": "stdio"
    }
  }
}

3. Agregar a Claude Desktop — edita:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "findunderstandfix": {
      "command": "node",
      "args": ["/ruta/absoluta/FindUnderstandFix/dist/server/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

4. Reiniciar Claude y verificar con /mcp → debe aparecer findunderstandfix · connected

Variables de entorno

Herramientas

Busca en GitHub issues abiertas filtradas por lenguaje, dificultad y tipo.

Frases que lo activan:

"Busca issues de Python para principiantes"
"Show me beginner Rust bugs"
"Encuentra 5 issues de Go de dificultad intermedia"
"Find JavaScript feature requests, answer in English"

Obtiene título, descripción, labels, autor, comentarios y datos del repositorio.

Frases que lo activan:

"Muéstrame el detalle de https://github.com/owner/repo/issues/123"
"¿De qué trata la issue #3?"
"Get the full info of that issue"

Usa Claude Haiku para explicar la issue adaptada a tu nivel. Cubre: qué es, por qué ocurre, impacto y por qué es buena para empezar.

Requiere ANTHROPIC_API_KEY

Frases que lo activan:

"Explícame esa issue"
"Explain this issue for a beginner"
"¿De qué trata esta issue? Nivel avanzado"

Genera 10 pasos con comandos git exactos y personalizados para contribuir. No usa LLM — los comandos son deterministas y se basan en datos reales del repo.

Frases que lo activan:

"Dame los pasos para contribuir, mi usuario es devch"
"How do I start contributing? My username is devch"
"Walk me through contributing to that issue"

Genera pistas de nivel 1 a 3 para ayudarte a resolver la issue sin darte la respuesta directa.

Requiere ANTHROPIC_API_KEY

Frases que lo activan:

"Dame una pista para resolver esa issue"
"Give me a more specific hint"
"Dame la pista 3"

Lenguajes soportados

Alias: c++ → C++ · c# → C# · csharp → C# · cpp → C++

Caché

Errores frecuentes

Estructura del proyecto

FindUnderstandFix/
├── src/
│   ├── shared/
│   │   ├── types.ts          # Interfaces TypeScript compartidas
│   │   ├── constants.ts      # Lenguajes soportados, alias, display names
│   │   ├── i18n.ts           # Traducciones EN/ES/PT/IT + helper t()
│   │   ├── cache.ts          # Caché en memoria con TTL
│   │   ├── github.ts         # Cliente GitHub REST API
│   │   └── anthropic.ts      # Cliente Claude Haiku
│   └── server/
│       ├── tools/
│       │   ├── search_issues.ts
│       │   ├── get_issue_detail.ts
│       │   ├── explain_issue.ts
│       │   ├── get_contribution_guide.ts
│       │   └── get_hints.ts
│       └── index.ts          # Entry point MCP
├── dist/                     # Compilado por tsc (no se sube al repo)
├── install.ps1               # Instalador Windows
├── install.sh                # Instalador macOS/Linux
├── package.json
├── tsconfig.json
└── .env.example

Contribuir

¡Las PRs son bienvenidas! Si encuentras un bug o quieres agregar soporte para un nuevo lenguaje:

1. Fork → rama → cambios → PR
2. Describe el problema que resuelve tu PR
3. Si agregas un lenguaje nuevo, actualiza src/shared/constants.ts

Hecho con ❤️ usando Claude · Model Context Protocol · GitHub API