Twining MCP Server

El problema

Pasas dos horas con Claude Code tomando decisiones arquitectónicas. Eliges PostgreSQL en lugar de MongoDB. Te decides por JWT para la autenticación. Marcas una condición de carrera en el módulo de pagos. Luego, la sesión termina.

Mañana comienzas una nueva sesión. Claude no tiene idea de lo que pasó. Las decisiones han desaparecido. Las advertencias han desaparecido. La justificación ha desaparecido. Vuelves a explicar todo, o peor aún, Claude contradice silenciosamente las elecciones de ayer.

Esto empeora con múltiples agentes. El Agente A decide usar REST. El Agente B elige gRPC para el mismo servicio. Ninguno sabe que el otro existe. Te enteras cuando el código no compila.

Las ventanas de contexto son efímeras. Las decisiones de tu proyecto no deberían serlo.

Cómo lo soluciona Twining

Twining es un servidor MCP que proporciona a tus agentes de IA una memoria de proyecto persistente. Las decisiones sobreviven a los reinicios de contexto. Las nuevas sesiones comienzan informadas. El trabajo multi-agente se mantiene coordinado.

# Install in 10 seconds
/plugin marketplace add daveangulo/twining-mcp
/plugin install twining@twining-marketplace

Registra lo que hiciste, en lenguaje natural:

twining_record({
  summary: "Added Redis caching to UserService",
  decisions: ["Chose Redis over Memcached — need persistence across restarts"],
  assumptions: ["Read-heavy workload (10:1 ratio)"],
  scope: "src/services/"
})

Twining analiza tus decisiones en registros estructurados, extrayendo automáticamente la justificación, las alternativas rechazadas y el dominio. Una llamada a herramienta, sin formularios.

Inicia una nueva sesión. Ponte al día al instante:

twining_assemble({ task: "optimize the caching layer", scope: "src/services/" })

Twining califica cada decisión, advertencia y hallazgo según su relevancia para tu tarea, y luego llena un presupuesto de tokens en orden de prioridad. Obtienes exactamente el contexto que necesitas: sin avalanchas de información, sin tener que volver a explicar.

Pregunta por qué las cosas son como son:

twining_why({ scope: "src/auth/middleware.ts" })

Devuelve la cadena completa de decisiones para cualquier archivo: qué se decidió, cuándo, por qué, qué alternativas se rechazaron y qué commit lo implementó.

¿Por qué no usar simplemente CLAUDE.md?

CLAUDE.md es estático. Lo escribes una vez y lo actualizas manualmente. No captura las decisiones a medida que ocurren, no rastrea la justificación o las alternativas, no detecta conflictos entre agentes y no puede ensamblar contexto de forma selectiva dentro de un presupuesto de tokens.

Twining es dinámico. Cada llamada a twining_decide registra una decisión estructurada. Cada twining_post comparte un hallazgo o advertencia. Cada twining_assemble califica la relevancia y entrega precisamente lo que la tarea actual necesita. El directorio .twining/ es la memoria institucional viva de tu proyecto.

¿Por qué no un orquestador?

Los orquestadores (como los enjambres de agentes y coordinadores jerárquicos) dirigen el trabajo asignando tareas. Twining coordina compartiendo el estado. La diferencia es importante:

• Los orquestadores mantienen el contexto de coordinación en su propia ventana de contexto: un punto único de fallo que se degrada a medida que la ventana se llena.

• La pizarra de Twining persiste el estado de coordinación fuera de la ventana de cualquier agente, sobreviviendo a los reinicios de contexto sin pérdida de información.

Los agentes se auto-asignan el trabajo leyendo la pizarra. Sin cuellos de botella centrales. Sin retransmisiones que pierdan contexto. Cada agente ve las decisiones y advertencias de todos los demás agentes, directamente.

Instalación

Instalación del plugin (Recomendado)

# Add the marketplace (one-time)
/plugin marketplace add daveangulo/twining-mcp

# Install the plugin
/plugin install twining@twining-marketplace

Incluye el servidor MCP, habilidades, ganchos de ciclo de vida y cumplimiento previo al commit. Dos puertas: twining_assemble antes de trabajar, twining_record antes de hacer commit; los ganchos aplican ambos automáticamente.

Auto-instalación para equipos

Haz commit de esto en el archivo .claude/settings.json de tu repositorio para que cada miembro del equipo obtenga Twining al clonar:

{
  "extraKnownMarketplaces": {
    "twining-marketplace": {
      "source": {
        "source": "github",
        "repo": "daveangulo/twining-mcp"
      }
    }
  },
  "enabledPlugins": {
    "twining@twining-marketplace": true
  }
}

Cuando los miembros del equipo confían en la carpeta del repositorio, Claude Code instala automáticamente el mercado y el plugin.

Instalación solo para MCP

Para clientes que no son Claude Code (Cursor, Windsurf, etc.):

claude mcp add twining -- npx -y twining-mcp --project .

O añádelo a .mcp.json:

{
  "mcpServers": {
    "twining": {
      "command": "npx",
      "args": ["-y", "twining-mcp", "--project", "."]
    }
  }
}

Las instrucciones del servidor MCP se incluyen automáticamente en la respuesta de inicialización.

Actualización desde una instalación manual

Si configuraste Twining manualmente anteriormente, cambia al plugin:

1. Elimina el servidor MCP manual: claude mcp remove twining

2. Instala el plugin: /plugin marketplace add daveangulo/twining-mcp y luego /plugin install twining@twining-marketplace

3. Limpieza: elimina los ganchos de Twining de .claude/settings.json, elimina .claude/agents/twining-aware.md si existe, elimina las secciones de Twining de CLAUDE.md (las habilidades se encargan de esto ahora)

4. Conserva: el directorio .twining/ (todo el estado se preserva)

5. Verifica: /twining:status

Sácale el máximo provecho

El plugin maneja las instrucciones del agente automáticamente a través de habilidades. Para la ruta de instalación solo MCP, añade las instrucciones de Twining al CLAUDE.md de tu proyecto para que los agentes lo usen automáticamente; consulta docs/CLAUDE_TEMPLATE.md para obtener una plantilla lista para copiar.

Panel de control

Un panel de control web se inicia automáticamente en http://localhost:24282: explora decisiones, entradas de la pizarra, grafo de conocimiento y estado del agente. Configurable mediante TWINING_DASHBOARD_PORT.

Qué hay dentro

Herramientas principales (siempre disponibles)

Estas son las herramientas que los agentes usan en cada sesión:

twining_record acepta decisiones en lenguaje natural como "Elegí Redis sobre Memcached: necesito persistencia" y las analiza automáticamente en registros estructurados con justificación, alternativas rechazadas y dominio inferido. También acepta suposiciones, restricciones, archivos afectados y cadenas de dependencia: todo lo que el almacén de decisiones necesita para un ensamblaje de contexto de alta fidelidad.

Herramientas extendidas (disponibles con full_surface: true)

Para flujos de trabajo avanzados: gestión profunda de decisiones, exploración de grafos, coordinación multi-agente:

Habilítalo con .twining/config.yml:

tools:
  full_surface: true

Cómo funciona

Todo el estado reside en .twining/ como archivos planos: JSONL para la pizarra, JSON para decisiones, grafo, agentes y traspasos. Todo es consultable con jq, grep y rastreable con git. Sin base de datos. Sin nube. Sin cuentas.

Capas de arquitectura:

• Almacenamiento: almacenes respaldados por archivos con bloqueo para acceso concurrente

• Motor: seguimiento de decisiones, pizarra, recorrido de grafos, ensamblaje de contexto con presupuesto de tokens, coordinación de agentes

• Embeddings: local all-MiniLM-L6-v2 a través de @huggingface/transformers, cargado de forma perezosa, con respaldo de palabras clave. El servidor nunca falla al iniciarse debido a problemas de embedding.

• Panel de control: interfaz web de solo lectura con visualización de grafos cytoscape.js y vis-timeline

• Herramientas: definiciones de herramientas MCP validadas con Zod, mapeadas 1:1 a la superficie de herramientas

Consulta TWINING-DESIGN-SPEC.md para ver la especificación completa.

Preguntas frecuentes

¿Twining ralentiza Claude Code? No. Es un servidor MCP local: las llamadas a herramientas son lecturas/escrituras de archivos locales. La búsqueda semántica se carga de forma perezosa en el primer uso.

¿Puedo usarlo con Cursor, Windsurf u otros clientes MCP? Sí. Twining es un servidor MCP estándar. Cualquier host MCP puede conectarse a él.

¿A dónde van mis datos? Todo el estado de coordinación es local en .twining/. Las métricas de llamadas a herramientas se almacenan localmente en .twining/metrics.jsonl (ignorado por git). Se puede habilitar telemetría anónima opcional; consulta Analytics a continuación.

¿Es Twining un orquestador de agentes? No. Es una capa de estado de coordinación. Captura qué decidieron los agentes y por qué, y pone ese conocimiento a disposición de futuros agentes. Úsalo junto con orquestadores, equipos de agentes o sesiones independientes.

Analítica

Twining incluye un sistema de análisis de tres capas para ayudarte a comprender el valor que proporciona.

Pestaña de información del panel de control

El panel de control web incluye una pestaña de Información que muestra:

• Métricas de valor: tasa de prevención de decisiones ciegas, reconocimiento de advertencias, cobertura de pruebas a través de relaciones de grafo tested_by, trazabilidad de commits, ciclo de vida de decisiones, estadísticas del grafo de conocimiento y métricas de coordinación de agentes

• Uso de herramientas: recuento de llamadas, tasas de error, latencia promedio/P95 por herramienta

• Desglose de errores: errores agrupados por herramienta y código de error

Todas las métricas de valor se calculan a partir de los datos existentes en .twining/: no se necesita recopilación de nuevos datos.

Métricas de llamadas a herramientas

Cada llamada a herramienta MCP se instrumenta automáticamente con seguimiento de tiempo y éxito/error. Las métricas se almacenan localmente en .twining/metrics.jsonl (ignorado por git: datos operativos, no arquitectónicos).

Para deshabilitar la recopilación de métricas locales, configúralo en .twining/config.yml:

analytics:
  metrics:
    enabled: false

Telemetría opcional

Los datos de uso agregados anónimos pueden enviarse opcionalmente a PostHog para ayudar a mejorar Twining. Deshabilitado por defecto. Para habilitarlo, añade a .twining/config.yml:

analytics:
  telemetry:
    enabled: true

Eso es todo: la clave del proyecto PostHog está integrada en el código fuente. Si ejecutas tu propia instancia de PostHog, puedes anularla con posthog_api_key y posthog_host.

Qué se envía: nombres de herramientas, duraciones de llamadas, booleanos de éxito/fallo, versión del servidor, SO, arquitectura.

Qué nunca se envía: rutas de archivos, contenido de decisiones, nombres de agentes, mensajes de error, argumentos de herramientas, variables de entorno.

Salvaguardas de privacidad:

• La variable de entorno DO_NOT_TRACK=1 siempre anula la configuración

• CI=true deshabilita automáticamente la telemetría

• La identidad es un hash SHA-256 del nombre de host + raíz del proyecto (nunca rutas sin procesar)

• Los fallos de red son silenciosos: sin reintentos

• posthog-node es una dependencia opcional: no hace nada si no está instalado

Desarrollo

npm install       # Install dependencies
npm run build     # Build
npm test          # Run tests (800+ tests)
npm run test:watch

Requiere Node.js >= 18.

CI/CD

Dos flujos de trabajo de GitHub Actions automatizan la verificación de compilación y la publicación:

CI (.github/workflows/ci.yml): se ejecuta en cada PR y push a main:

• Compila y prueba en Node 18, 20 y 22

• Cancela las ejecuciones en curso cuando llega un nuevo push a la misma rama

Publicar (.github/workflows/publish.yml): se ejecuta en el push de etiquetas v*:

• Compila con POSTHOG_API_KEY integrado para paquetes publicados

• Ejecuta el conjunto completo de pruebas como defensa en profundidad

• Publica en npm con --provenance para la certificación de la cadena de suministro

• Crea un GitHub Release con notas de lanzamiento generadas automáticamente

• Admite activación manual mediante workflow_dispatch con una opción de simulación

Para publicar una nueva versión:

npm version patch   # or minor, major
git push && git push --tags

Secretos requeridos (configurados en Configuración > Secretos del repositorio de GitHub):

Licencia

MIT