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

395 lines
14 KiB
Markdown
Raw 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
```powershell
# 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
```powershell
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)
```powershell
# 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\`:
```powershell
$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:
```powershell
# 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\`:
```powershell
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)
```powershell
# 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
```powershell
engram connect http://185.187.169.109:3801 --api-key <token-del-cloud>
```
### 10.2 Si el cloud no responde
```bash
# 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
```powershell
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`.
```powershell
# 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:
```powershell
pip install telethon
```
---
## 12. Resumen de pasos para instalación limpia
```powershell
# === 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