telegram-mcp-bridge

telegram-mcp-bridge es una interfaz remota y segura para usar un subconjunto de mcp-dev-core desde Telegram. No es un agente autonomo, no expone shell arbitraria y no aprueba ni aplica cambios sensibles desde el celular.

Arquitectura

Telegram Bot
  -> telegram-mcp-bridge
    -> MCP client (stdio)
      -> mcp-dev-core
        -> tools seguras

Objetivo de esta fase:

• acceso remoto controlado a tools de lectura y diagnostico
• sesiones por chat para continuidad operativa
• policy local adicional antes de invocar MCP
• respuestas breves, truncadas y entendibles

Estructura

telegram-mcp-bridge/
├─ src/
│  ├─ bot/
│  │  ├─ telegram-bot.ts
│  │  ├─ command-router.ts
│  │  └─ handlers/
│  │     ├─ command-handlers.ts
│  │     └─ index.ts
│  ├─ config/
│  │  └─ env.ts
│  ├─ mcp/
│  │  ├─ mcp-client.ts
│  │  └─ tool-runner.ts
│  ├─ security/
│  │  └─ access-control.ts
│  ├─ sessions/
│  │  └─ chat-session-store.ts
│  ├─ utils/
│  │  └─ text.ts
│  └─ index.ts
├─ tests/
├─ package.json
├─ tsconfig.json
├─ vitest.config.ts
├─ eslint.config.js
├─ .env.example
└─ README.md

Variables de entorno

Se validan con Zod al arrancar:

• TELEGRAM_BOT_TOKEN
• TELEGRAM_ALLOWED_CHAT_IDS
• MCP_SERVER_COMMAND
• MCP_SERVER_ARGS
• MCP_EXECUTION_MODE_DEFAULT
• BRIDGE_PERSISTENCE_ENABLED
• BRIDGE_STATE_DIR

Notas:

• TELEGRAM_ALLOWED_CHAT_IDS usa formato CSV: 123,456
• MCP_SERVER_ARGS usa JSON array de strings para evitar parsing ambiguo de shell
• MCP_EXECUTION_MODE_DEFAULT define policy local adicional del bridge

Comandos soportados

• /start
• /help
• /status -> read_system_status
• /snapshot -> read_state_snapshot
• /sessions -> list_sessions
• /newsession <titulo> -> create_session
• /setsession <sessionId> -> asocia una sesion existente al chat
• /artifacts -> list_artifacts
• /readfile <ruta> -> read_file
• /search <texto> -> search_codebase
• /runtests -> run_tests si la policy local lo permite
• /runlint -> run_linter si la policy local lo permite

Seguridad

Controles implementados en esta fase:

• allowlist explicita de chat IDs autorizados
• allowlist explicita de tools expuestas por el bridge
• bloqueo local de run_tests y run_linter cuando MCP_EXECUTION_MODE_DEFAULT=safe
• sin chat libre estilo GPT
• sin run_command
• sin write_file_patch apply
• sin approve_proposal
• sin commits
• sin acceso a WhatsApp

La idea es que el bridge agregue una capa de policy propia encima de las restricciones ya existentes en mcp-dev-core.

Como ejecutar

1. Instala dependencias:

npm install

2. Compila mcp-dev-core y asegurate de conocer el entrypoint del servidor MCP por stdio.

3. Crea .env a partir de .env.example.

Ejemplo:

TELEGRAM_BOT_TOKEN=123456:replace-me
TELEGRAM_ALLOWED_CHAT_IDS=123456789
MCP_SERVER_COMMAND=node
MCP_SERVER_ARGS=["/home/elorro/mcp-dev-core/dist/src/server/main.js"]
MCP_EXECUTION_MODE_DEFAULT=safe
BRIDGE_PERSISTENCE_ENABLED=true
BRIDGE_STATE_DIR=.bridge-state

4. Inicia el bridge:

npm run dev

Para build de produccion:

npm run build
npm start

Ejemplos de uso

/status
/snapshot
/newsession revisar smoke tests
/sessions
/setsession 550e8400-e29b-41d4-a716-446655440000
/readfile src/server/main.ts
/search write_file_patch
/runtests

Tests

La suite no usa Telegram real. Cubre:

• access control
• parseo de comandos
• store de sesiones
• tool runner con cliente MCP mockeado
• handlers principales

Ejecutar:

npm test

Limitaciones de esta fase

• no hay conversacion libre ni enrutamiento semantico
• no hay streaming de respuestas
• no hay aprobacion remota de proposals
• no hay cambios de archivos ni git write
• no hay multi-tenant real ni RBAC avanzado
• el mapping chat -> session es simple y local

Siguientes fases recomendadas

1. Agregar read_session y set_active_session de forma controlada.
2. Incorporar auditoria local del bridge con correlation IDs.
3. Soportar respuestas chunked cuando Telegram exceda el limite.
4. Añadir health checks y reconexion con backoff para el proceso MCP.
5. Introducir vistas resumidas por tool para mejorar UX movil.