Claude Assist MCP

Permite la comunicación entre Claude Code y Claude Desktop para revisiones de código.

GitHub
1
Prueba este MCPPatrocinado

Documentación

MCP Claude Desktop

Un servidor de Model Context Protocol (MCP) que permite a Claude Code comunicarse con Claude Desktop. Este servidor permite a Claude Code enviar prompts a Claude Desktop y consultar respuestas.

Inspirado en claude-chatgpt-mcp, este proyecto adapta el concepto para el ecosistema de Apple utilizando automatización nativa de macOS.

Características

  • Enviar prompts desde Claude Code a Claude Desktop
  • Consulta automática de respuestas con tiempo de espera configurable
  • Listar conversaciones disponibles en Claude Desktop
  • Manejo de errores y lógica de reintentos
  • Registro (logging) exhaustivo

Instalación

Puedes instalar y usar este servidor MCP de dos maneras:

Opción 1: Usando npx (Recomendado)

La forma más sencilla de usar este servidor es directamente con npx, sin necesidad de instalación:

{
  "mcpServers": {
    "claude-desktop": {
      "command": "npx",
      "args": ["mcp-claude-desktop"]
    }
  }
}

Opción 2: Instalación Local

  1. Clona este repositorio:
git clone https://github.com/dpaluy/mcp-claude-desktop
cd mcp-claude-desktop
  1. Instala las dependencias:
npm install
  1. Compila el proyecto:
npm run build
  1. Configura MCP:
{
  "mcpServers": {
    "claude-desktop": {
      "command": "node",
      "args": ["/path/to/mcp-claude-desktop/dist/index.js"]
    }
  }
}

Requisitos del Sistema

  • macOS 11.0+ (Big Sur o posterior)
  • Node.js 18+
  • Aplicación Claude Desktop instalada
  • Permisos de accesibilidad otorgados para AppleScript

Otorgar Permisos de Accesibilidad

  1. Abre Preferencias del Sistema > Seguridad y Privacidad > Privacidad
  2. Selecciona "Accesibilidad" en la barra lateral izquierda
  3. Haz clic en el candado para realizar cambios
  4. Agrega Terminal (o tu aplicación de terminal) a las aplicaciones permitidas
  5. Reinicia tu terminal

Herramientas MCP

Este servidor MCP proporciona dos herramientas:

ask

  • Propósito: Enviar un prompt a Claude Desktop y obtener una respuesta
  • Parámetros:
    • prompt: El texto a enviar a Claude Desktop (obligatorio)
    • conversationId: ID opcional para continuar una conversación específica
    • timeout: Tiempo de espera de respuesta en segundos (opcional, predeterminado: 30, máximo: 300)
    • pollingInterval: Frecuencia de verificación de respuesta en segundos (opcional, predeterminado: 1.5, mínimo: 0.5)

get_conversations

  • Propósito: Obtener una lista de conversaciones disponibles en Claude Desktop
  • Parámetros: Ninguno

Uso

Una vez configurado, Claude Code puede usar el MCP de diversas maneras:

Uso General

Cuando Claude usa estas herramientas, las llamará con parámetros como:

Uso básico:

  • Herramienta: ask
  • Parámetros: { "prompt": "What is dependency injection?" }

Con tiempo de espera personalizado:

  • Herramienta: ask
  • Parámetros: { "prompt": "Explain quantum computing", "timeout": 120 }

Con tiempo de espera e intervalo de consulta:

  • Herramienta: ask
  • Parámetros: { "prompt": "Quick question", "timeout": 10, "pollingInterval": 0.5 }

Obtener conversaciones:

  • Herramienta: get_conversations
  • Parámetros: {}

Cómo Usarlo en Claude

Una vez que el servidor MCP está configurado y en ejecución, puedes usar estas herramientas directamente en Claude:

Uso básico:

  • "Usa la herramienta ask para preguntar a Claude Desktop: ¿Cuáles son las mejores prácticas para el manejo de errores en Python?"
  • "Usa get_conversations para listar todas mis conversaciones de Claude Desktop"

Con tiempo de espera personalizado:

  • "Usa la herramienta ask con tiempo de espera 60 para preguntar a Claude Desktop: Explica la implementación del árbol B+"
  • "Usa ask con tiempo de espera 10 y pollingInterval 0.5 para preguntar a Claude Desktop: ¿Cuánto es 2+2?"

Importante: La configuración del servidor MCP (mostrada arriba) solo indica a Claude cómo iniciar el servidor. Los parámetros de tiempo de espera y pollingInterval se especifican al usar la herramienta en Claude, no en el archivo de configuración del servidor.

Limitaciones Conocidas

Lectura de Respuestas

Debido a la arquitectura basada en Electron de Claude Desktop, esta integración MCP no puede leer las respuestas de Claude programáticamente. La herramienta puede:

  • ✅ Enviar prompts a Claude Desktop
  • ✅ Crear nuevas conversaciones
  • ✅ Activar y enfocar la ventana de Claude
  • ❌ Leer las respuestas de Claude

Esta es una limitación de cómo las aplicaciones Electron exponen los elementos de interfaz a través de las APIs de accesibilidad. Cuando uses la herramienta ask, recibirás una confirmación de que el mensaje fue enviado, pero deberás verificar la ventana de Claude Desktop directamente para ver la respuesta.

Soluciones Alternativas

  1. Usa la API de Claude: Para acceso programático a respuestas, considera usar la API de Claude directamente en lugar de la automatización de escritorio
  2. Verificación manual: Después de enviar un prompt, verifica manualmente la ventana de Claude Desktop para ver la respuesta
  3. Automatización unidireccional: Usa esta herramienta para escenarios donde solo necesites enviar prompts sin leer respuestas

Integración con Claude Commands

Claude Commands te permite crear flujos de trabajo reutilizables que combinan herramientas MCP. Este proyecto funciona perfectamente con Claude Commands para habilitar automatización potente.

Ejemplo: Comando de Revisión de Código entre Pares

Hemos incluido un ejemplo de Claude Command que demuestra cómo usar MCP Claude Desktop para revisiones de código automatizadas. El comando usa git para analizar cambios recientes y los envía a Claude Desktop para obtener retroalimentación de revisión entre pares.

Configuración

  1. Copia el comando de ejemplo a tu directorio de Claude Commands:

    cp examples/claude-peer-review.md ~/.claude/commands/

  2. El comando estará disponible en Claude Code como /claude-peer-review

Uso

El comando de revisión entre pares acepta hasta 3 argumentos:

  • description: Qué cambios revisar (ej., "corrección de autenticación")
  • polling_interval: Frecuencia de verificación de respuesta (predeterminado: 1.5s)
  • timeout: Tiempo máximo de espera para la respuesta (predeterminado: 30s)

Ejemplos:

# Review most recent commit with defaults
/claude-peer-review

# Review with description
/claude-peer-review "bug fix for user login"

# Custom polling interval (2 seconds)
/claude-peer-review "API update" 2

# Custom timeout for complex reviews (2 minutes)
/claude-peer-review "major refactor" 1.5 120

Cómo Funciona

  1. Integración con Git: El comando obtiene automáticamente:

    • Estado actual de git
    • Estadísticas de commits recientes
    • Diff completo de los cambios
    • Nombre de la rama actual

  2. Revisión de Claude Desktop: Envía los cambios a Claude Desktop con preguntas de revisión específicas:

    • Adecuación del código y calidad de implementación
    • Problemas de seguridad o posibles errores
    • Calidad del código y mejores prácticas
    • Sugerencias de mejoras

  3. Manejo de Respuestas: Usa el mecanismo de consulta del servidor MCP para esperar la respuesta de Claude

  4. Generación de Resumen: Proporciona un resumen estructurado de:

    • Cambios revisados
    • Retroalimentación de Claude
    • Acciones tomadas basadas en la retroalimentación
    • Estado final de la revisión

Creando Tus Propios Comands

Puedes crear Claude Commands personalizados que aprovechen MCP Claude Desktop. Los comandos deben:

  1. Incluir las herramientas en el frontmatter:

    ---
allowed-tools: mcp__claude-desktop__ask, mcp__claude-desktop__get_conversations
---

  2. Usar las herramientas MCP con parámetros apropiados:

    mcp__claude-desktop__ask
prompt: "Your prompt here"
timeout: 60
pollingInterval: 2

  3. Manejar los tiempos de espera con elegancia y sugerir tiempos de espera más largos para consultas complejas

Consulta el comando de ejemplo para una implementación completa.

Desarrollo

Ejecución en Modo de Desarrollo

npm run dev

Ejecución de Pruebas

npm test

Linting

npm run lint

Verificación de Tipos

npm run typecheck

API

Herramientas

ask

Envía un prompt a Claude Desktop y obtén una respuesta.

Parámetros:

  • prompt (string, obligatorio): El prompt a enviar
  • conversationId (string, opcional): Continuar una conversación específica
  • timeout (number, opcional): Tiempo de espera de respuesta en segundos
    • Predeterminado: 30 segundos
    • Mínimo: 1 segundo
    • Máximo: 300 segundos (5 minutos)
  • pollingInterval (number, opcional): Frecuencia de verificación de respuesta en segundos
    • Predeterminado: 1.5 segundos
    • Mínimo: 0.5 segundos
    • Máximo: 10 segundos

Respuesta:

String containing Claude's response

get_conversations

Obtén una lista de conversaciones disponibles en Claude Desktop.

Parámetros: Ninguno

Respuesta:

{
  conversations: string[];
  timestamp: string;
}

Arquitectura

El servidor MCP usa AppleScript para comunicarse con Claude Desktop:

  1. Claude Code envía un prompt a través de MCP
  2. AppleScript activa Claude Desktop y crea una nueva conversación
  3. El prompt se escribe en Claude Desktop
  4. El servidor consulta Claude Desktop por la respuesta
  5. Una vez que se detecta una respuesta, se analiza y se devuelve a Claude Code

Solución de Problemas

Problemas Comunes

  1. "La ejecución de AppleScript falló"

    • Asegúrate de que Claude Desktop esté instalado y en ejecución
    • Verifica los permisos de accesibilidad
    • Intenta ejecutar el servidor con un nivel de registro más alto: LOG_LEVEL=3

  2. "Tiempo de espera de respuesta agotado"

    • Aumenta el parámetro de tiempo de espera: timeout: 60 (60 segundos)
    • Para consultas complejas, usa tiempos de espera más largos: timeout: 120 (2 minutos)
    • Reduce el intervalo de consulta para una detección más rápida: pollingInterval: 0.5
    • Verifica si Claude Desktop está respondiendo normalmente
    • Asegúrate de que el sistema no esté bajo carga pesada

  3. "Permiso denegado"

    • Otorga permisos de accesibilidad a tu terminal
    • Ejecuta el comando de compilación con los permisos adecuados

  4. El Servidor MCP se Bloquea Después de Enviar Solicitudes Si el servidor MCP se bloquea después de manejar solicitudes, puedes:

    • Deshabilitar la consulta de respuestas (recomendado para estabilidad):

      export SKIP_CLAUDE_POLLING=true

      Esto enviará el mensaje a Claude Desktop pero no intentará leer la respuesta.

    • Habilitar el registro de depuración para ver qué está sucediendo:

      export LOG_LEVEL=3

    • Verificar la salida de stderr - Todos los registros ahora se escriben en stderr para evitar interferir con el protocolo MCP en stdout.

Limitaciones Conocidas con la Consulta de Respuestas

La consulta de respuestas puede causar inestabilidad ocasionalmente debido a:

  • Duración extendida de la consulta (30 segundos predeterminado)
  • Lectura compleja de elementos de interfaz de aplicaciones Electron
  • Problemas de sincronización con la generación de respuestas de Claude

Considera usar SKIP_CLAUDE_POLLING=true para una operación más confiable si no necesitas leer respuestas.

Contribuciones

¡Damos la bienvenida a contribuciones a MCP Claude Desktop! Ya sea que estés corrigiendo errores, agregando funciones o mejorando la documentación, tu ayuda es apreciada.

Primeros Pasos

  1. Haz un fork del repositorio
  2. Clona tu fork: 
    git clone https://github.com/YOUR_USERNAME/mcp-claude-desktop
cd mcp-claude-desktop
  3. Instala las dependencias: 
    npm install
  4. Crea una nueva rama: 
    git checkout -b feature/your-feature-name

Flujo de Trabajo de Desarrollo

  1. Realiza tus cambios
  2. Ejecuta las pruebas para asegurarte de que todo funcione: 
    npm test
  3. Ejecuta el linting para mantener la calidad del código: 
    npm run lint
  4. Ejecuta la verificación de tipos: 
    npm run typecheck
  5. Compila el proyecto: 
    npm run build

Pautas de Estilo de Código

  • Usa TypeScript para todo el código fuente
  • Sigue el estilo de código existente (aplicado por ESLint)
  • Escribe mensajes de commit significativos
  • Agrega pruebas para nuevas funciones
  • Actualiza la documentación según sea necesario

Envío de Cambios

  1. Haz commit de tus cambios con un mensaje descriptivo: 
    git commit -m "feat: add support for conversation history"
  2. Haz push a tu fork: 
    git push origin feature/your-feature-name
  3. Crea un Pull Request en GitHub

Pautas para Pull Requests

  • Proporciona una descripción clara de los cambios
  • Haz referencia a cualquier problema relacionado
  • Asegúrate de que todas las pruebas pasen
  • Actualiza el README si agregas nuevas funciones
  • Sé receptivo a la retroalimentación de la revisión de código

Reporte de Problemas

  • Usa GitHub Issues para reportar errores
  • Incluye la versión de macOS y la versión de Node.js
  • Proporciona pasos para reproducir el problema
  • Incluye mensajes de error o registros relevantes

Solicitudes de Funciones

  • Abre un issue para discutir nuevas funciones
  • Explica el caso de uso y los beneficios
  • Sé abierto a la retroalimentación y enfoques alternativos

Licencia

MIT