jjminguez/biblioteca_conocimiento_laboratorio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
biblioteca_conocimiento_lab…/INSTALACION_OPENCODE.md

14 KiB
Raw Permalink Blame History

INSTALACION_OPENCODE.md — Guía de instalación completa

Objetivo: Reproducir el entorno OpenCode exacto en cualquier máquina Windows nueva. Fecha: 28 Junio 2026 Repositorio principal: https://git.v-encore-lab.com/jjminguez/biblioteca_negocio_prolongo.git

1. Prerrequisitos del sistema

  • SO: Windows 10/11 (x64)
  • Shell: PowerShell 5.1 (incluido en Windows)
  • Git: Instalado y configurado con acceso al remoto git.v-encore-lab.com
  • Editor/Obsidian: C:\Users\%USERNAME%\AppData\Local\Obsidian\Obsidian.exe (instalar desde https://obsidian.md)

2. Runtimes necesarios

# Node.js 22.x (LTS) — incluye npm y npx
winget install OpenJS.NodeJS.LTS

# Bun 1.3.x (runtime JS alternativo, necesario para duckduckgo-mcp)
powershell -c "irm bun.sh/install.ps1 | iex"

# Python 3.11.x (watcher Telegram, scripts auxiliares)
winget install Python.Python.3.11

# uv 0.11.x (gestor de paquetes Python, necesario para mcp-obsidian)
powershell -ExecutionPolicy Bypass -Command "irm https://astral.sh/uv/install.ps1 | iex"

Verificación de runtimes

node --version   # debe mostrar v22.x
npm --version    # debe mostrar 10.x
bun --version    # debe mostrar 1.3.x
python --version # debe mostrar 3.11.x
uv --version     # debe mostrar 0.11.x

3. Binarios independientes

Engram (memoria persistente vía MCP)

# Instalación del CLI de Engram
# Descargar el binario desde su fuente oficial y colocarlo en:
C:\Users\%USERNAME%\bin\engram.exe

# Verificar
engram --version   # debe mostrar >= v0.6.1

Nota: El binario actual ocupa ~18.5 MB. Si no tienes el instalador, consultar con el equipo.

4. Repositorios Git a clonar

Todos los repos deben clonarse bajo C:\Users\%USERNAME%\Documents\GitHub\:

$githubRoot = "$env:USERPROFILE\Documents\GitHub"
New-Item -ItemType Directory -Force -Path $githubRoot

# 1. Repositorio principal (este)
git clone https://git.v-encore-lab.com/jjminguez/biblioteca_negocio_prolongo.git $githubRoot\biblioteca_negocio_prolongo

# 2. MCP Image Vision (análisis de imágenes vía OpenRouter)
#   Crear manualmente si no tienes acceso al repo original:
New-Item -ItemType Directory -Force -Path "$githubRoot\image-vision-mcp"
#   Copiar package.json y src/index.js desde la máquina origen.
#   Luego ejecutar:
#       cd $githubRoot\image-vision-mcp
#       npm install
#       npm run build

NOTA: image-vision-mcp no es un repo Git (fue creado localmente). En una reinstalación limpia, copia la carpeta entera desde backup o reconstrúyela con los archivos fuente. Ver sección 5.2 para sus detalles.

5. MCP Servers — detalle técnico

Cada MCP se define en C:\Users\%USERNAME%\.config\opencode\opencode.jsonc.

5.1 Engram (local)

Campo Valor
Runtime Binario nativo
Comando C:\Users\%USERNAME%\bin\engram.exe mcp --tools=agent
Tipo local
Variables Ninguna required

5.2 Image Vision (local)

Campo Valor
Runtime Node.js
Comando node C:\Users\%USERNAME%\Documents\GitHub\image-vision-mcp\dist\index.js
Dependencias npm @modelcontextprotocol/sdk ^1.0.0
Variables requeridas IMAGE_VISION_AUTH_TOKEN, IMAGE_VISION_BASE_URL, IMAGE_VISION_MODEL, VISION_API_PROVIDER
API Provider OpenRouter

Archivos fuente de image-vision-mcp:

  • package.json — metadatos + dependencia MCP SDK
  • src/index.js — servidor MCP que expone extract_text_from_screenshot y image_analysis
  • dist/index.js — copia de src/index.js (generada por npm run build)

5.3 Context7 (remoto)

Campo Valor
Tipo remote
URL https://mcp.context7.com/mcp
Header CONTEXT7_API_KEY (desde .env)

5.4 Fetch (local)

Campo Valor
Runtime npx (Node.js)
Comando npx -y @h16rkim/mcp-fetch-server
Variables Ninguna

5.5 Sequential Thinking (local)

Campo Valor
Runtime npx (Node.js)
Comando npx -y @modelcontextprotocol/server-sequential-thinking
Variables Ninguna

5.6 DuckDuckGo Search (local)

Campo Valor
Runtime bunx (Bun)
Comando C:\Users\%USERNAME%\.bun\bin\bunx.exe duckduckgo-mcp
Variables Ninguna
Nota Usa ruta absoluta a bunx.exe porque OpenCode no hereda el PATH completo

5.7 Obsidian (local)

Campo Valor
Runtime uvx (uv / Python)
Comando C:\Users\%USERNAME%\.local\bin\uvx.exe mcp-obsidian
Variables OBSIDIAN_API_KEY, OBSIDIAN_HOST=127.0.0.1, OBSIDIAN_PORT=27124
Nota Usa ruta absoluta a uvx.exe por el mismo motivo que bunx

5.8 Telegram (local)

Campo Valor
Runtime npx (Node.js)
Comando npx -y mcp-telegram
Working Dir C:\Users\%USERNAME%
Variables TELEGRAM_API_ID, TELEGRAM_API_HASH (desde .env), TELEGRAM_AGENT_HOME=.telegram-agent
Nota Tras instalación limpia, requiere telegram_login para autenticar la sesión

6. Variables de entorno (.env)

Archivo: C:\Users\%USERNAME%\Documents\GitHub\biblioteca_negocio_prolongo\.env

Variable Usada por ¿Compartible?
CONTEXT7_API_KEY MCP Context7 Compartir con el equipo
IMAGE_VISION_AUTH_TOKEN MCP Image Vision (OpenRouter) Compartir con el equipo
IMAGE_VISION_BASE_URL MCP Image Vision Fijo: https://openrouter.ai/api/v1
IMAGE_VISION_MODEL MCP Image Vision Fijo: google/gemini-2.5-flash
VISION_API_PROVIDER MCP Image Vision Fijo: openai
VOICEMONKEY_TOKEN Alexa / VoiceMonkey Compartir con el equipo
VOICEMONKEY_DEVICE Alexa / VoiceMonkey Compartir con el equipo
OBSIDIAN_API_KEY MCP Obsidian Generada por plugin, única por vault
TELEGRAM_API_ID MCP Telegram Personal (cuenta de Telegram de Juanma)
TELEGRAM_API_HASH MCP Telegram Personal (cuenta de Telegram de Juanma)

IMPORTANTE: .env está en .gitignore — NO se sube al repositorio. Guardar copia en:

  • Unidad compartida de red (Z:\GitHub)
  • O en gestor de secretos (1Password, LastPass, etc.)
  • O en Engram (memorias config con scope personal)

Las variables TELEGRAM_* son específicas de la cuenta de Telegram de cada usuario. Si otra persona instala esto, necesitará sus propias credenciales de Telegram API en https://my.telegram.org.

7. Configuración de OpenCode

7.1 Archivo principal: opencode.jsonc

Ruta: C:\Users\%USERNAME%\.config\opencode\opencode.jsonc

Este archivo se genera automáticamente al lanzar OpenCode por primera vez. Se debe reemplazar con la versión del repositorio:

# IMPORTANTE: Si tu nombre de usuario NO es "juanm", reemplázalo primero:
# (Get-Content "$githubRoot\biblioteca_negocio_prolongo\config\opencode.jsonc") -replace 'juanm', $env:USERNAME | Set-Content "$env:USERPROFILE\.config\opencode\opencode.jsonc"

# Si tu usuario SÍ es juanm, simplemente:
Copy-Item "$githubRoot\biblioteca_negocio_prolongo\config\opencode.jsonc" "$env:USERPROFILE\.config\opencode\opencode.jsonc"

Si el directorio .config\opencode no existe, créalo: New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode"

7.2 Otros archivos en .config\opencode\

  • package.json / package-lock.json — dependencias de plugins OpenCode
  • tui.json — configuración de la interfaz TUI
  • plugins/ — plugins instalados
  • .gitignore — excluye node_modules

Estos se regeneran automáticamente. No es necesario respaldarlos, pero si los tienes copiados aceleran el primer arranque.

8. Instrucciones de IA (AGENTS.md + CLAUDE.md)

Son archivos de instrucciones que el asistente IA lee automáticamente:

Archivo Ruta Propósito
AGENTS.md Raíz del repo biblioteca_negocio_prolongo Reglas del asistente para este proyecto
CLAUDE.md C:\Users\%USERNAME%\.claude\CLAUDE.md Instrucciones globales de Engram para cualquier proyecto

Ambos ya están en el repositorio. CLAUDE.md debe copiarse manualmente a ~\.claude\:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude"
Copy-Item "$githubRoot\biblioteca_negocio_prolongo\config\CLAUDE.md" "$env:USERPROFILE\.claude\CLAUDE.md"

9. Obsidian

9.1 Instalación

  1. Instalar Obsidian desde https://obsidian.md
  2. Abrir el vault Obsidian Vault ubicado en C:\Users\%USERNAME%\Documents\Obsidian Vault
  3. Ir a Settings > Community Plugins > Browse
  4. Instalar "Local REST API" (por Adam Coddington, v4.1.3+)
  5. Activar el plugin
  6. En la configuración del plugin, copiar la API Key generada y guardarla en .env como OBSIDIAN_API_KEY

9.2 Vaults esperados

  • wiki-prolongo — documentación del proyecto sincronizada (el principal)
  • Obsidian Vault — vault personal de Juanma

9.3 Watchdog de sincronización (Windows Scheduled Task)

# Crear tarea programada que ejecute el sync al iniciar sesión
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-File `"C:\Users\%USERNAME%\Documents\GitHub\biblioteca_negocio_prolongo\scripts\sync_prolongo.ps1`""
$trigger = New-ScheduledTaskTrigger -AtLogon
$principal = New-ScheduledTaskPrincipal -UserId "$env:USERNAME" -RunLevel Highest
Register-ScheduledTask -TaskName "ProlongoObsidianSync" -Action $action -Trigger $trigger -Principal $principal -Description "Sincroniza documentación del proyecto con Obsidian"

10. Engram Cloud (memoria compartida)

El cloud de Engram corre en un VPS Contabo. No es necesario para trabajar, pero permite compartir memoria entre sesiones/máquinas y con el equipo.

10.1 Conexión al cloud

engram connect http://185.187.169.109:3801 --api-key <token-del-cloud>

10.2 Si el cloud no responde

# Conectarse por SSH al VPS
ssh -i C:\Users\%USERNAME%\Documents\GitHub\contabo\contabo root@185.187.169.109
cd /opt/engram && git pull
docker compose -f docker-compose.cloud.yml up -d --build --force-recreate cloud

10.3 Verificar conexión

engram doctor --project biblioteca_negocio_prolongo

11. Telegram Watcher (script auxiliar)

Script que monitorea mensajes de Telegram entrantes y los registra en telegram_mensajes.log.

# El watcher se lanza automáticamente al iniciar sesión de OpenCode (Regla 6 de AGENTS.md)
# Manualmente:
Start-Process powershell -WindowStyle Hidden -ArgumentList '-Command', 'python C:\Users\%USERNAME%\Documents\GitHub\biblioteca_negocio_prolongo\scripts\telegram_watcher.py'

Dependencias Python del watcher:

pip install telethon

12. Resumen de pasos para instalación limpia

# === FASE 1: Sistema base ===
winget install OpenJS.NodeJS.LTS
winget install Python.Python.3.11
powershell -c "irm bun.sh/install.ps1 | iex"
powershell -ExecutionPolicy Bypass -Command "irm https://astral.sh/uv/install.ps1 | iex"

# === FASE 2: Clonar repos ===
$githubRoot = "$env:USERPROFILE\Documents\GitHub"
New-Item -ItemType Directory -Force -Path $githubRoot
git clone https://git.v-encore-lab.com/jjminguez/biblioteca_negocio_prolongo.git $githubRoot\biblioteca_negocio_prolongo

# === FASE 3: Configurar .env ===
# Copiar .env desde unidad compartida o gestor de secretos a:
#   $githubRoot\biblioteca_negocio_prolongo\.env

# === FASE 4: Configurar OpenCode ===
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode"
Copy-Item "$githubRoot\biblioteca_negocio_prolongo\config\opencode.jsonc" "$env:USERPROFILE\.config\opencode\opencode.jsonc"

# === FASE 5: Configurar CLAUDE.md ===
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude"
Copy-Item "$githubRoot\biblioteca_negocio_prolongo\config\CLAUDE.md" "$env:USERPROFILE\.claude\CLAUDE.md"

# === FASE 6: Image Vision MCP ===
# Copiar carpeta image-vision-mcp desde backup a $githubRoot\image-vision-mcp
cd $githubRoot\image-vision-mcp
npm install
npm run build

# === FASE 7: Engram ===
# Copiar engram.exe a C:\Users\%USERNAME%\bin\engram.exe
engram connect http://185.187.169.109:3801 --api-key <token>

# === FASE 8: Obsidian ===
# 1. Instalar Obsidian
# 2. Abrir vault "Obsidian Vault" y "wiki-prolongo"
# 3. Instalar plugin "Local REST API" v4.1.3+
# 4. Copiar API Key generada al .env

# === FASE 9: Tareas programadas ===
# Crear ProlongoObsidianSync (ver sección 9.3)

# === FASE 10: Telegram ===
# Al primer uso, OpenCode pedirá hacer login en Telegram
# Seguir las instrucciones (teléfono → código → 2FA)

# === FASE 11: Arrancar OpenCode ===
# Abrir OpenCode en el directorio del proyecto:
# opencode C:\Users\%USERNAME%\Documents\GitHub\biblioteca_negocio_prolongo

13. Archivos del repositorio relevantes para instalación

Archivo Función
INSTALACION_OPENCODE.md Este documento
AGENTS.md Reglas del asistente IA para este proyecto
config/opencode.jsonc Configuración de MCPs y providers
config/CLAUDE.md Instrucciones globales de Engram
.env Variables de entorno (NO en Git)
scripts/telegram_watcher.py Watcher de mensajes Telegram
scripts/sync_prolongo.ps1 Script de sincronización Obsidian
MEMORIA_ABSOLUTA.md Protocolo de memoria del proyecto
ESTADO_DIARIO.md Estado diario del proyecto
DOCUMENTACION.md Índice de documentación

14. Verificación post-instalación

Para confirmar que todo funciona, abrir OpenCode y ejecutar:

re

Debe responder con el estado del proyecto. Luego verificar que todos los MCP aparecen como Connected en el panel de MCP Tools (no "Connection Closed").

MCPs que deben aparecer como Connected:

  1. ✅ engram
  2. ✅ image-vision
  3. ✅ context7
  4. ✅ fetch
  5. ✅ sequential-thinking
  6. ✅ duckduckgo-search
  7. ✅ obsidian
  8. ✅ telegram

Generado: 28 Junio 2026 — Mantener actualizado con cada cambio de infraestructura.

Reference in New Issue View Git Blame Copy Permalink