PeerBridge MCP

English | 繁體中文 | 简体中文

Reúne a Codex, Claude Code, Grok, Kimi, DeepSeek, Gemini, modelos locales y otros Agentes compatibles con MCP u OpenAI en un solo equipo de IA auditable.

PeerBridge conecta clientes oficiales, servicios de retransmisión, API compatibles y modelos locales sin encerrar al equipo en un único proveedor. Ofrece a cada Agente un asiento igualitario, memoria compartida aprobada, discusión paralela acotada, propiedad de tareas, puntuación mutua, auditorías entre agentes y una sala controlada por humanos donde el trabajo permanece visible. Un panel de Tokens en vivo muestra el uso por proveedor y modelo. PeerBridge se ejecuta localmente sobre SQLite, mantiene las credenciales de los proveedores fuera del historial de chat y del proyecto, y conserva un registro vinculado por SHA de mensajes, decisiones, evidencias, puntuaciones, revisiones y traspasos.

Los mensajes humanos o de Agentes pueden despertar la sala; la colaboración se detiene por consenso, bloqueos, estancamiento o límites explícitos, y el operador puede intervenir en cualquier momento.

Estado: alfa. El núcleo de coordinación y auditoría está probado, pero la API pública y el esquema de la base de datos pueden cambiar antes de la versión 1.0.

La continuidad operativa y la comercialización son límites de diseño explícitos. Consulte memoria y operaciones de larga duración y el límite del núcleo abierto. El módulo remoto/móvil es Experimental y desactivado por defecto. Las entradas de la hoja de ruta no son afirmaciones de capacidad.

Por qué

Ejecutar dos agentes de codificación contra un mismo repositorio crea modos de fallo predecibles:

• ambos agentes editan los mismos archivos;

• un agente asume que un par está en línea cuando no lo está;

• los mensajes de chat se pierden o se reconocen globalmente en lugar de por consumidor;

• una revisión aprueba archivos obsoletos en lugar de los archivos que realmente se probaron;

• el humano no puede ver quién posee una tarea ni por qué se marcó como completada.

PeerBridge aborda esos fallos de coordinación sin convertir a ningún agente en el jefe. Una tarea tiene un único permiso de escritura, los pares pueden revisarse entre sí y un humano puede intervenir.

Related MCP server: JustClone Coordination MCP Server

Arquitectura

flowchart LR
    H["Human operator"] --> M["Pixel control room"]
    C["Codex / Claude Code"] --> S1["PeerBridge stdio process"]
    A["Grok / Kimi / DeepSeek / Gemini / local Agents"] --> S2["PeerBridge stdio process"]
    M --> S3["PeerBridge stdio process"]
    R["Private mobile UI"] -->|"Tailnet HTTPS"| T["Tailscale Serve"]
    T -->|"loopback only"| S4["Human MCP message gateway"]
    S1 --> DB[("Shared SQLite store")]
    S2 --> DB
    S3 --> DB
    S4 --> DB
    DB --> L["SHA-linked audit events"]
    DB --> W["Mailbox, leases, reviews, proofs"]

Cada cliente MCP lanza su propio proceso de servidor stdio con un --agent-id distinto. Esos procesos se coordinan a través de una base de datos SQLite local del proyecto .peerbridge/peerbridge.sqlite3. El modo WAL de SQLite y las transacciones BEGIN IMMEDIATE serializan los cambios de estado.

Características

• Presencia por agente con caducidad, no una bandera de conexión permanente.

• Etiquetas de identidad de tiempo de ejecución auditadas para cliente, ruta de proveedor y modelo seleccionado.

• Mensajes directos y de difusión vinculados por SHA.

• Biblioteca Global de Agentes persistente con asientos reutilizables y con ámbito de sala; añadir un Agente a una sala nunca lo elimina de la biblioteca ni de otra sala.

• Conversaciones multisesión duraderas con sesiones de membresía independientes, cursores de bandeja de entrada, límites de respuesta y recibos de colaboración con ámbito de sala.

• Libro de Memoria neutral al proveedor con registros Privados (solo del propietario), de Sala (solo para miembros) y de Proyecto (aprobados por humanos), cada uno vinculado por SHA a su evidencia fuente explícita.

• Recibos por consumidor y cursores duraderos contiguos.

• Concesiones de tareas con token de capacidad, caducidad y recuperación.

• Comprobaciones deterministas de superposición de rutas de lectura/escritura.

• Políticas de solo_allowed, two_party_required, presence_aware y cuórum de N pares.

• Solicitudes de revisión por pares vinculadas a la fuente y veredictos entre pares igualitarios.

• Puntuación mutua de Agentes y rastros de auditoría entre agentes vinculados a la fuente revisada exacta.

• Panel de uso de Tokens en vivo con desglose por proveedor/modelo y tendencias de entrada, salida, escritura en caché y lectura en caché.

• Sincronización con un clic del proveedor/modelo de CC Switch a través de su CLI oficial, mientras que las credenciales permanecen en la instalación existente de CC Switch del usuario.

• Rehash de archivos en vivo antes de completar la tarea.

• Borradores de plan y parche aislados que nunca se aplican automáticamente.

• Cadena de eventos SHA-256 por ámbito de solo añadidura con verificador.

• Sala de control local estilo Pixel con composición de mensajes MCP humanos.

• El núcleo de coordinación no tiene dependencias de tiempo de ejecución más allá de la biblioteca estándar de Python; la retroalimentación cifrada opcional usa el extra feedback (cryptography).

• Soporte MCP de doble era: inicialización heredada y el modelo de descubrimiento 2026-07-28.

• Control móvil privado opcional sin alquiler mediante loopback más Tailscale Serve.

• Paginación del historial de sala acotada, renderizado de pestaña activa y un supervisor de buzón de memoria baja singleton para ejecutores de proveedor opcionales.

Inicio rápido

Aplicación portátil para Windows

Descargue PeerBridgeControlRoom-0.1.0a6-windows-x64-portable.zip desde la versión Alpha de GitHub, extraiga el ZIP completo en una carpeta con permisos de escritura y haga doble clic en Launch PeerBridge.cmd. La aplicación portátil crea su espacio de trabajo local en %LOCALAPPDATA%\PeerBridge\workspace; no incluye credenciales de proveedor ni datos de tiempo de ejecución privados.

Este ejecutable Alpha no está firmado con código, por lo que Windows SmartScreen puede pedirle que revise el editor. Verifique el SHA-256 de la versión antes de abrirlo. PeerBridge no proporciona un instalador automático ni modifica un entorno Python existente.

Instalar desde el código fuente

Requisitos: Python 3.11 o superior.

git clone https://github.com/hoylon/peerbridge-mcp.git
cd peerbridge-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
peerbridge init --project-root . --scope demo
peerbridge doctor --project-root . --scope demo

Ejecute un servidor manualmente:

peerbridge serve --project-root . --agent-id codex-main --scope demo

Cuando un cliente puede seleccionar varios modelos oficiales o respaldados por retransmisión, registre la ruta sin exponer credenciales:

peerbridge serve --project-root . --agent-id grok-relay-reviewer --scope demo `
  --client-name relay-coding-client `
  --provider-id relay:grok-official-channel `
  --model-id grok

agent-id identifica al trabajador lógico. client-name identifica la aplicación o adaptador compatible con MCP. provider-id es una etiqueta de ruta no secreta proporcionada por el operador, y model-id identifica el modelo seleccionado. Un sitio web oficial de Grok o DeepSeek y una ruta de retransmisión son identidades separadas incluso cuando exponen la misma familia de modelos.

Los endpoints directos compatibles con OpenAI no requieren CC Switch. En la página Conexiones seguras, guarde la URL base de la API y la clave de API en el Administrador de Credenciales de Windows, luego registre una ruta por Agente lógico. La clave de API nunca entra en SQLite ni en un mensaje MCP. Algunas retransmisiones aceptan un ID de modelo solicitado pero informan un alias de despliegue estable en las respuestas. En ese caso, establezca MODELO DE RESPUESTA ESPERADO explícitamente. Por ejemplo, una ruta puede solicitar grok-4.6 mientras requiere que la respuesta informe grok-4.6-build. Un alias no configurado o cambiante falla de forma cerrada en lugar de tratarse silenciosamente como el modelo solicitado.

El servidor habla JSON-RPC delimitado por nueva línea sobre stdin/stdout. Normalmente un cliente MCP lo inicia por usted, por lo que un servidor iniciado manualmente esperando entrada es un comportamiento esperado.

Conectar clientes

Use una ruta absoluta del ejecutable de Python para que cada cliente lance el mismo entorno instalado y la base de datos compartida.

Codex

codex mcp add peerbridge -- C:\path\to\peerbridge-mcp\.venv\Scripts\python.exe `
  -m peerbridge_mcp serve --project-root C:\path\to\your-project `
  --agent-id codex-main --scope your-project

Claude Code

claude mcp add --scope project --transport stdio peerbridge -- `
  C:\path\to\peerbridge-mcp\.venv\Scripts\python.exe `
  -m peerbridge_mcp serve --project-root C:\path\to\your-project `
  --agent-id claude-code --scope your-project

Use diferentes nombres de entrada del servidor MCP cuando ambos clientes escriban una configuración de proyecto compartida, por ejemplo peerbridge-codex y peerbridge-claude. Consulte configuración del cliente para ejemplos en TOML, JSON, Linux y macOS. El mismo servidor stdio puede registrarse en Kimi Code CLI; otros proveedores pueden requerir un ejecutor separado respaldado por API. Consulte límites de integración de agentes.

PeerBridge informa la capacidad efectiva de cada Asiento de sala enlazado en lugar de inferirla del nombre del Agente:

• MCP NATIVE: un cliente o terminal real compatible con MCP posee la sesión y puede llamar al servidor PeerBridge directamente.

• MCP TOOL: un modelo respaldado por API está dentro del bucle de herramientas MCP acotado y en lista blanca de PeerBridge; tiene capacidad de herramienta pero no se representa como una sesión de cliente nativa.

• INFERENCE: la ruta puede devolver una respuesta de modelo acotada pero no puede llamar a las herramientas de PeerBridge. Las pestañas de chat web y los fallbacks de CLI de una sola vez pertenecen aquí.

Cualquier otro cliente o terminal que implemente MCP puede usar el mismo comando stdio que se muestra en configuración del cliente. Una ruta configurada no se considera activa hasta que ese cliente esté realmente en ejecución y autorizado.

Referencias de clientes oficiales:

• Configuración MCP de Codex

• Configuración MCP de Claude Code

• Kimi Code CLI

Sala de control Pixel

peerbridge monitor --project-root C:\path\to\your-project --scope your-project

El monitor muestra mensajes, propiedad de tareas, revisiones entre pares, registros de prueba y el registro de eventos. Su compositor envía un mensaje humano a través de la misma ruta stdio MCP que un agente, por lo que la intervención humana recibe los mismos hashes y rastro de auditoría.

Los Agentes viven en una Biblioteca Global de Agentes persistente. Arrastrar o añadir un Agente a una sala crea un asiento con ámbito de sala; no mueve ni consume la identidad global. Por lo tanto, el mismo Agente puede participar en varias salas a la vez. Cada asiento tiene un room_session_id, ruta solicitada y cursor de sala independientes. Eliminar un asiento detiene la entrega futura en esa sala mientras conserva sus mensajes e historial de auditoría. El contexto no se copia silenciosamente entre salas; se requiere un mensaje de resumen explícito y auditado cuando el operador quiera compartir contexto.

Cada sala personalizada tiene una política de automatización explícita. Off registra el historial sin despertar un modelo. One round pregunta a cada Asiento de agente enrutado en paralelo exactamente una vez. Bounded discussion avanza rondas paralelas solo después de que todos los envíos actuales sean terminales. Las respuestas terminan con CONTINUE, CONSENSUS o BLOCKED; el coordinador se detiene por consenso, bloqueos, estancamiento, el límite de rondas o el presupuesto de mensajes. La barra de la sala permite al humano pausar y reanudar una ronda en curso, continuar una discusión acotada después de una condición de parada automática, o detenerla explícitamente.

Las respuestas nunca crean una cascada de respuestas no controlada. Solo los mensajes creados por el coordinador son enviables, el avance de ronda es idempotente y cada ámbito tiene un bloqueo de escritor supervisor. Iniciar una nueva publicación de sala detiene una discusión abierta anterior mientras conserva su historial y motivo de parada.

El compositor de escritorio puede adjuntar hasta cinco archivos PNG/JPEG/GIF/WebP o UTF-8 texto/Markdown/CSV/JSON/log seleccionados explícitamente (8 MiB cada uno, 16 MiB en total). PeerBridge valida el tipo declarado, rechaza texto similar a credenciales, copia cada archivo en el almacén local ignorado .peerbridge-artifacts/chat/ bajo su nombre SHA-256, y vincula solo esa ruta relativa direccionada por contenido al mensaje. La ruta absoluta original y el nombre de archivo no entran en SQLite. Los mensajes iniciales de difusión/discusión reciben el enlace una vez; las rondas posteriores no lo duplican. Transportar un adjunto no prueba que un proveedor seleccionado pueda interpretar imágenes, por lo que las rutas no compatibles deben tratarlo como una referencia de archivo auditable.

La página Memoria Compartida muestra registros de memoria explícitos separados del chat. PeerBridge no extrae ni sincroniza cadenas de pensamiento ocultas, estado de conversación del lado del proveedor o credenciales. Un Agente puede escribir su propio resumen Privado de borrador, los miembros activos de la sala pueden leer la memoria de Sala, y solo human-operator puede publicar o revocar memoria de Proyecto. La promoción de Proyecto requiere un mensaje fuente vinculado por SHA, memoria padre o artefacto de proyecto. La revocación conserva el registro original y añade un nuevo recibo de auditoría en lugar de eliminar el historial.

Los ejecutores respaldados por API compatibles con OpenAI reciben solo las herramientas de solo lectura list_memories y read_memory por defecto. Por lo tanto, pueden usar los mismos hechos aprobados que Codex, Claude Code, Grok, Kimi, DeepSeek o un modelo local sin obtener permiso para publicar memoria a nivel de proyecto. Cada sala mantiene una sesión de modelo y un cursor independientes incluso cuando el mismo Agente global tiene un asiento en varias salas.

Control móvil privado

La página remota Experimental opcional expone una interfaz humana deliberadamente limitada a través de Tailscale Serve. El backend se vincula solo a 127.0.0.1; el proxy de la tailnet proporciona la identidad de usuario autenticada. Soporta observación con ámbito y mensajes MCP humanos auditados, no ejecución de shell ni mutación de archivos.

.\scripts\launch_remote_control.cmd -Port 8765 -Scope your-project

Consulte control remoto y móvil privado para conocer el límite de seguridad, las pruebas, la configuración del teléfono y la prohibición explícita de exposición pública a través de Tailscale Funnel.

Estado del producto y métricas opcionales

PeerBridge expone un límite de capacidad legible por máquina sin activar un servicio alojado, flujo de pago ni proveedor de derechos comerciales:

peerbridge product --project-root . status
peerbridge product --project-root . status --capability remote.experimental.self_hosted

El hook de analítica local está desactivado por defecto. Sin una aceptación explícita, no crea un ID de instalación, no pone en cola un evento ni contacta con un endpoint de red. La Alpha actual no tiene ningún emisor de analítica; los datos habilitados permanecen en la máquina local como contadores agregados por día UTC con un ID de instalación aleatorio y restablecible.

peerbridge analytics --project-root . status
peerbridge analytics --project-root . enable
peerbridge analytics --project-root . export
peerbridge analytics --project-root . disable

El download_count de los activos de GitHub Release mide descargas de archivos, no usuarios únicos. Las estimaciones reales de DAU/WAU/MAU requieren un futuro recopilador transparente además de una aceptación explícita de la aplicación, y deben describirse como instalaciones activas, no personas. Los prompts, cuerpos de mensaje, claves de API, salidas de modelos, nombres/rutas de archivos, nombres de proyectos, identidades de cuentas, direcciones IP y metadatos arbitrarios quedan fuera del esquema público de eventos. Véase telemetría y métricas de lanzamiento y hooks remotos/comerciales experimentales.

Los anuncios son independientes de la analítica. La Alpha empaquetada habilita una conexión de anuncios HTTPS de solo lectura por defecto para que los avisos urgentes puedan aparecer sin una comprobación de actualización. Cada solicitud envía la configuración regional de la interfaz seleccionada, el cursor de anuncios por configuración regional y un User-Agent fijo no identificativo del cliente de anuncios de PeerBridge; la infraestructura de red normal también puede observar la dirección IP de origen. No envía ID de instalación, credenciales, rutas de proyecto, contenido de mensajes ni salida de modelos. La página Anuncios ofrece un interruptor de red independiente: desactivarlo detiene las solicitudes de anuncios y deja legible la caché local acotada. Las notificaciones emergentes tienen su propia preferencia independiente. Si el archivo de preferencias guardado no se puede leer, tanto el sondeo de red como las notificaciones emergentes fallan en modo cerrado hasta que el usuario guarde explícitamente preferencias nuevas.

Los comentarios se envían de forma privada a través de HTTPS. Los metadatos ordinarios del informe, los diagnósticos seleccionados por el usuario, los datos de contacto y los adjuntos están protegidos en tránsito, pero no están cifrados de extremo a extremo dentro del paquete de soporte. Solo una credencial opcional que el usuario elige incluir explícitamente se cifra localmente con la clave pública de soporte fijada de los mantenedores antes de la subida. Véase privacidad de los comentarios.

La sala de control proporciona una base de configuración regional persistida en zh-Hant / zh-Hans / inglés, un tutorial de primera ejecución reproducible y una comprobación de actualización explícita de solo lectura. Una instalación Alpha informa de las nuevas versiones de GitHub. Un futuro canal Stable solo seguirá el carril de versiones Stable. El comprobador nunca descarga ni instala código; la actualización firmada con un clic y la reversión siguen siendo trabajo futuro.

La página Conexiones seguras admite dos rutas de incorporación locales:

• introducir un endpoint HTTPS privado y una clave de API; PeerBridge guarda ambos en el Administrador de credenciales del usuario actual de Windows y escribe solo identificadores redactados y huellas SHA-256 a través de MCP;

• descubrir proveedores existentes de Claude, Codex, Gemini, OpenCode, Hermes u OpenClaw a través de la CLI oficial de CC Switch, obtener los IDs de modelo usando la credencial ya guardada de CC Switch, registrar una ruta de PeerBridge y cambiar solo tras una confirmación humana explícita.

Para una URL compatible con OpenAI que especifica solo el host, PeerBridge añade la base de API /v1 convencional. Si el proveedor publica una ruta de compatibilidad explícita, introduzca esa ruta base completa; PeerBridge la conserva. Esto admite endpoints como la base de compatibilidad /v1beta/openai/ de Gemini sin código específico del proveedor.

PeerBridge no incluye claves de API en bruto ni endpoints privados completos en mensajes MCP, SQLite, eventos de auditoría, recibos, registros, argumentos de línea de comandos, enlaces profundos, Git o telemetría. No lee la base de datos de CC Switch ni exporta la configuración de CC Switch. La creación automática de proveedores de CC Switch está deshabilitada intencionalmente porque sus contratos públicos de enlace profundo/importación pueden exponer una clave fuera del almacén de secretos del sistema operativo.

El compositor usa una cascada verificada: Agente destinatario, ruta de proveedor registrada, un modelo disponible en esa ruta y luego un modo de razonamiento disponible para ese modelo exacto. Las familias de modelos y los niveles de razonamiento son campos separados; una variante de modelo como gpt-5.6-luna no debe presentarse como un nivel de razonamiento. Un mensaje enrutado permanece en REQUESTED hasta que una sesión destinataria cuya identidad de tiempo de ejecución observada coincida con todos los campos solicitados lo reconozca. Una sesión no coincidente no puede reconocer el mensaje. Solo entonces PeerBridge añade un recibo de ruta VERIFIED vinculado a SHA.

Las rutas guardadas se pueden registrar a través de MCP:

{
  "route_id": "codex-luna-medium",
  "agent_id": "codex-main",
  "provider_id": "openai-official",
  "model_id": "gpt-5.6-luna",
  "reasoning_mode": "medium",
  "route_class": "official"
}

Para un proveedor con un alias de respuesta verificado, añada el enlace separado:

{
  "route_id": "relay-grok-4.6",
  "agent_id": "grok-relay",
  "provider_id": "relay-grok-sui-xiang",
  "model_id": "grok-4.6",
  "response_model_id": "grok-4.6-build",
  "route_class": "relay"
}

model_id es la identidad de la solicitud saliente. response_model_id es la identidad exacta del modelo requerida en cada respuesta de finalización; cuando se omite, su valor por defecto es model_id. Ambos están vinculados a SHA en el perfil de ruta y en el recibo de inferencia.

Llame a upsert_route_profile con esa carga útil, luego seleccione el perfil en el monitor o pase route_profile_id a send_message. Los perfiles y las etiquetas introducidas por el usuario son solicitudes de enrutamiento, no prueba de identidad ascendente. Lance cada par MCP con sus etiquetas observadas reales, incluido --reasoning-mode, para que la puerta de recibos pueda verificarlas.

Flujo de trabajo recomendado

1. Cada agente llama a bridge_status y workboard antes de empezar a trabajar.

2. El escritor previsto llama a claim_task con rutas de lectura y escritura precisas.

3. El escritor llama a announce_work mientras trabaja fuera de PeerBridge.

4. Registra hashes en vivo y evidencia de pruebas con record_proof.

5. Si la política de aprobación requiere un par, llama a request_review.

6. El par lee los artefactos vinculados y llama a submit_review.

7. El escritor llama a complete_task; PeerBridge vuelve a calcular los hashes de los archivos y comprueba la política.

8. Cualquiera puede llamar a verify_audit_chain o ejecutar peerbridge doctor.

request_review es una cola de gobernanza manual. Nunca invoca un modelo y aparece en la página Revisión, no en el chat de la sala. Para despertar a los Agentes de sala enrutados, publique a través de post_room_message: once envía una ronda paralela, mientras que discussion ejecuta rondas paralelas acotadas. Las respuestas nunca activan por sí mismas otra propagación.

PeerBridge coordina el trabajo. Los clientes de codificación siguen leyendo, editando y probando archivos con sus herramientas normales.

Modos de aprobación

El modo sensible a la presencia admite uso intermitente. Evita bloquear todo el trabajo cuando solo hay un agente de pago en ejecución, pero sigue exigiendo revisión cuando el par nombrado está realmente en línea. El modo de cuórum está pensado para tres o más agentes conectados de forma independiente. No inicia, paga ni autentica a esos agentes.

Límites de seguridad

• .peerbridge/ puede contener metadatos de conversación y tareas. Está ignorado por Git, pero no está cifrado. Proteja el directorio del proyecto con permisos del sistema operativo.

• Los cuerpos de memoria son datos explícitos de coordinación, no un almacén de secretos cifrado. Nunca ponga credenciales, razonamiento oculto ni datos personales no relacionados en un registro de memoria.

• La detección de secretos es un filtro de mejor esfuerzo que falla en modo cerrado, no un sistema DLP completo.

• La cadena de auditoría detecta muchas mutaciones, pero la eliminación de una cola no anclada no puede demostrarse solo con la base de datos. Exporte o ancle externamente las cabezas de cadena importantes.

• Un usuario local malicioso con acceso al sistema de archivos está fuera del modelo de amenazas actual.

• Un proceso local puede alcanzar la interfaz de bucle local y falsificar cabeceras de proxy; la cuenta del sistema operativo sigue siendo un límite de confianza para el modo móvil privado.

• PeerBridge nunca interpreta una revisión como permiso para ejecutar comandos destructivos del shell.

Lea el modelo de amenazas completo antes de usar el puente en repositorios sensibles.

Objetivos no perseguidos

• Despertar o pagar automáticamente por otro modelo de IA.

• Reemplazar Git, la revisión de código, la CI o los permisos del repositorio.

• Aplicar parches generados.

• Alojar un servicio MCP remoto multiinquilino.

• Cifrar la base de datos SQLite local.

• Afirmar que una revisión de IA equivale a una revisión de seguridad humana.

Desarrollo

python -m pytest
python -m compileall -q src
python -m build

Véase CONTRIBUTING.md, arquitectura y el recorrido de demostración. El trabajo futuro en la nube y móvil se separa explícitamente en la hoja de ruta.

Licencia

Apache License 2.0. Véase LICENSE.

El nombre y el logotipo de PeerBridge son activos de marca independientes y no están licenciados bajo Apache-2.0. Véase procedencia de los activos de marca y directrices de marcas comerciales.