@dev-bear/mcp

MCP (Model Context Protocol) Server para integrar DevBear con Claude Code y otros asistentes de IA.

Instalacion Rapida

# Agregar a Claude Code (recomendado)
claude mcp add devbear npx @dev-bear/mcp

¡Eso es todo! No necesitas configurar nada mas.

Instalacion Alternativa

Opcion 1: Usar con npx (sin instalar)

npx @dev-bear/mcp

Opcion 2: Instalar globalmente

npm install -g @dev-bear/mcp
devbear-mcp

Opcion 3: Configuracion manual

Edita tu archivo de configuracion de Claude:

Ubicaciones:

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

{
  "mcpServers": {
    "devbear": {
      "command": "npx",
      "args": ["@dev-bear/mcp"]
    }
  }
}

Primer Uso

Opcion A: Personal Access Token (recomendado para LLMs hosted)

Funciona en cualquier cliente MCP (Claude Desktop, Claude Code, Cursor, ChatGPT desktop, Continue, etc.) sin que tengas que pegar tu contrasena en el chat.

1. Entra a DevBear -> Mi Perfil -> "Tokens de Acceso (MCP)" -> Nuevo token.
2. Copia el token (formato dvb_...). Solo se muestra una vez.
3. Configura el MCP con la variable de entorno DEVBEAR_TOKEN:

{
  "mcpServers": {
    "devbear": {
      "command": "npx",
      "args": ["@dev-bear/mcp"],
      "env": { "DEVBEAR_TOKEN": "dvb_xxxxxxxxxxxxxxxx" }
    }
  }
}

4. Reinicia tu cliente. El MCP intercambia el token por una sesion al arrancar.

Tambien puedes pasar el token desde el chat con devbear_login_token(token="dvb_..."), util para probar antes de configurar la env var.

Para revocar un token: Mi Perfil -> Tokens de Acceso -> icono de papelera. El cliente que lo use dejara de funcionar de inmediato.

Opcion B: Login con email y password

Util para uso local desde Claude Code u otros clientes que pueden capturar contrasenas de forma segura:

Tu: "Lista mis proyectos en DevBear"
Claude: "Necesitas autenticarte. Usa devbear_login con tu email y password"

Tu: devbear_login con email="[email protected]", password="tu-password"
Claude: "Autenticado como Juan Perez (developer) en Mi Organizacion"

Sesiones siguientes

Tu sesion se guarda automaticamente. No necesitas hacer login cada vez.

Tu: "Lista mis proyectos"
Claude: [Usa tu sesion guardada automaticamente]

3. Ver tu usuario actual

Tu: devbear_whoami
Claude:
- Email: [email protected]
- Nombre: Juan Perez
- Rol: developer
- Organizacion: Mi Organizacion

4. Cerrar sesion

Tu: devbear_logout
Claude: "Sesion cerrada correctamente"

Herramientas Disponibles

Autenticacion

| Herramienta | Descripcion | |-------------|-------------| | devbear_login | Iniciar sesion con email y contrasena | | devbear_login_token | Iniciar sesion con un Personal Access Token | | devbear_logout | Cerrar sesion | | devbear_whoami | Ver usuario actual |

Proyectos

| Herramienta | Descripcion | |-------------|-------------| | devbear_project_list | Listar proyectos | | devbear_project_get | Detalles de proyecto | | devbear_project_context | Contexto completo para desarrollo |

Tareas

| Herramienta | Descripcion | |-------------|-------------| | devbear_task_list | Listar tareas | | devbear_task_get | Detalles de tarea | | devbear_task_create | Crear tarea | | devbear_task_update | Actualizar tarea | | devbear_task_start | Marcar en progreso | | devbear_task_complete | Marcar completada | | devbear_task_add_comment | Agregar comentario | | devbear_subtask_list | Listar subtareas |

Sprints

| Herramienta | Descripcion | |-------------|-------------| | devbear_sprint_list | Listar sprints del proyecto | | devbear_sprint_get | Detalles de sprint con metricas | | devbear_sprint_create | Crear nuevo sprint | | devbear_sprint_update | Actualizar sprint | | devbear_sprint_activate | Activar sprint (desactiva otros) |

Equipo

| Herramienta | Descripcion | |-------------|-------------| | devbear_team_list | Listar miembros del proyecto | | devbear_team_get | Detalles de miembro con tareas y actividad | | devbear_team_add | Agregar miembro al proyecto | | devbear_team_remove | Remover miembro del proyecto | | devbear_team_update_role | Cambiar rol de un miembro |

Documentos

| Herramienta | Descripcion | |-------------|-------------| | devbear_doc_list | Listar documentos | | devbear_doc_get | Ver documento | | devbear_doc_create | Crear documento | | devbear_doc_update | Actualizar documento |

Diagramas

| Herramienta | Descripcion | |-------------|-------------| | devbear_diagram_list | Listar diagramas | | devbear_diagram_get | Ver diagrama (Mermaid) | | devbear_diagram_create | Crear diagrama | | devbear_diagram_update | Actualizar diagrama |

Prompts y Skills

| Herramienta | Descripcion | |-------------|-------------| | devbear_prompt_list | Listar prompts | | devbear_prompt_get | Ver prompt | | devbear_prompt_create | Guardar prompt | | devbear_prompt_delete | Eliminar prompt | | devbear_prompt_search_by_tech | Buscar por tecnologia |

Metricas y Reportes

| Herramienta | Descripcion | |-------------|-------------| | devbear_metrics_get | Metricas del proyecto | | devbear_project_report | Reporte completo del proyecto | | devbear_ai_activity_summary | Resumen de actividad IA | | devbear_sprint_report | Reporte detallado de un sprint | | devbear_team_report | Reporte de productividad del equipo |

Ejemplos de Uso

"Muestrame los proyectos activos"
"Dame el contexto del proyecto mi-app"
"Lista las tareas pendientes"
"Crea una tarea: Implementar login con Google"
"Marca la tarea ABC como completada"
"Agrega un comentario a la tarea: Avance del 50%"
"Busca prompts de React y TypeScript"
"Muestrame el diagrama de arquitectura"

Permisos (RBAC)

El MCP respeta los permisos de tu cuenta con dos niveles:

Roles de Organizacion

| Accion | Admin | Leader | Developer | QA | Designer | Viewer | |--------|-------|--------|-----------|-----|----------|--------| | Ver proyectos | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Crear proyectos | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | Crear tareas | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | | Editar cualquier tarea | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | Editar tus tareas | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | | Eliminar proyectos | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |

Roles de Proyecto

Ademas del rol de organizacion, puedes tener un rol especifico en cada proyecto:

| Rol | Descripcion | |-----|-------------| | Owner | Control total del proyecto | | Maintainer | Editar/eliminar cualquier recurso del proyecto | | Contributor | Crear y editar sus propios recursos | | Viewer | Solo lectura |

Donde se guardan los datos

| Dato | Ubicacion | Acceso | |------|-----------|--------| | Tu sesion | ~/.devbear/tokens.json (tu PC) | Solo tu | | Tus proyectos | Servidores de DevBear | Tu + tu equipo | | Codigo del MCP | npm | Publico |

Importante: Tus datos NUNCA pasan por npm. El MCP es solo codigo que conecta Claude con DevBear.

Solucion de Problemas

"No autenticado"

devbear_login con email="[email protected]", password="..."

"Acceso denegado"

Tu rol no tiene permisos. Contacta a un admin de tu organizacion.

"Token expirado"

El MCP refresca automaticamente. Si falla:

devbear_logout
devbear_login con email="...", password="..."

Limpiar sesion manualmente

# macOS/Linux
rm ~/.devbear/tokens.json

# Windows
del %USERPROFILE%\.devbear\tokens.json

Requisitos

• Node.js 18+
• Cuenta en DevBear

Self-Hosted (Avanzado)

Si tienes tu propia instancia de DevBear:

SUPABASE_URL=https://tu-instancia.supabase.co \
SUPABASE_ANON_KEY=tu-anon-key \
npx @dev-bear/mcp

Enlaces

• DevBear - Plataforma
• Documentacion - Docs completos
• Reportar problemas

Changelog

v1.9.0

• Feature: Personal Access Tokens (PAT) para autenticacion sin contrasena.
  • Nuevo tool devbear_login_token para login desde el chat con un PAT.
  • Soporte para variable de entorno DEVBEAR_TOKEN (autologin al arrancar).
  • Compatibilidad con LLMs hosted que no pueden capturar contrasenas.
  • Gestion de tokens (crear/listar/revocar) desde Mi Perfil en DevBear.
  • El intercambio PAT -> sesion se hace via edge function mcp-token-exchange.

v1.0.5

• Feature: Herramientas de Sprint (devbear_sprint_list, devbear_sprint_get, devbear_sprint_create, devbear_sprint_update, devbear_sprint_activate)
• Feature: Herramientas de Equipo (devbear_team_list, devbear_team_get, devbear_team_add, devbear_team_remove, devbear_team_update_role)
• Feature: Nuevos reportes (devbear_sprint_report, devbear_team_report)
• Feature: Sistema de permisos RBAC para sprints y equipo

v1.0.4

• Fix: Corregido acceso a proyectos - ahora respeta correctamente RLS
• Fix: getProjectRole() y checkResourceOwnership() usan el token del usuario
• Fix: Operaciones de lectura ya no verifican membresia manualmente
• Mejora: Usuarios con roles validos (owner, maintainer, contributor, viewer) acceden correctamente

v1.0.3

• Fix: Todas las herramientas usan getUserClient() para respetar RLS
• Fix: Removido requiresProjectContext de operaciones de lectura

v1.0.2

• Feature: Sistema de autenticacion con login/logout/whoami
• Feature: Tokens persistentes en ~/.devbear/tokens.json
• Feature: Sistema de permisos RBAC completo

v1.0.0

• Lanzamiento inicial

Licencia

MIT