DevTwin MCP

Dale a los agentes de codificación de IA una comprensión viva y estructurada de tu entorno de desarrollo local.

DevTwin es un servidor del Model Context Protocol (MCP) que responde a una pregunta central para un agente de codificación de IA: ¿por qué el entorno de este desarrollador es diferente, está roto o no es saludable?

Detecta la tecnología del proyecto, comprueba las versiones de runtime instaladas frente a lo que el proyecto realmente requiere, inspecciona el estado de las dependencias y del lockfile, encuentra los servicios locales necesarios (Postgres, Redis, ...) y si están en ejecución, comprueba puertos y el estado de Git, y convierte todo eso en diagnósticos estructurados basados en evidencia -- sin enviar nunca tu entorno a un backend en la nube, y sin exponer nunca valores secretos al modelo.

Contenido

• Por qué existe DevTwin

• Preguntas frecuentes: Claude CLI ya tiene un shell, ¿entonces por qué un MCP?

• Beneficios

• Coste de tokens

• Compensaciones honestas

• Con vs. sin DevTwin: un ejemplo práctico

• Ejemplos de preguntas que esto desbloquea

• Ejemplos por lenguaje

• Arquitectura

• Ecosistemas compatibles

• Instalación

• Configuración del cliente MCP

• Usarlo en otro proyecto

• Referencia de herramientas

• Modelo de seguridad

• Modelo de privacidad

• Arquitectura local-first

• Desarrollo

• Contribuciones

• Hoja de ruta

• Licencia

Por qué existe DevTwin

• Los agentes de codificación de IA leen bien el código, pero son ciegos al entorno en el que ese código realmente se ejecuta.

• "¿Por qué falla npm test en mi máquina?" normalmente no tiene nada que ver con el código -- es una versión de Node incorrecta, un servicio que no está en ejecución, o dependencias que nunca se instalaron.

• DevTwin le da a un agente la misma señal que un ingeniero senior recopilaría a mano -- node --version, git status, lsof -i :5432, docker ps -- como llamadas a herramientas estructuradas en lugar de conjeturas.

Preguntas frecuentes: Claude CLI ya tiene un shell, ¿entonces por qué un MCP?

Esta suele ser la primera pregunta que hace un desarrollador, y es justa. En un cliente como Claude Code que ya tiene una herramienta Bash, puedes simplemente pedirle que ejecute node --version, docker ps, lsof -i :5432, etc. directamente -- no se necesita ningún servidor MCP. La brecha que cierra DevTwin no es "¿se puede hacer esto en absoluto?" -- es esta:

Respuesta honesta específicamente para Claude CLI: dado que ya tiene Bash, la ventaja de DevTwin allí es menor que "capacidad que no tenías" -- son garantías de seguridad y salida estructurada y consistente, no acceso completamente nuevo. Por eso tampoco es gratis -- ver Coste de tokens para saber cuánto cuesta realmente conectarlo, y cuándo merece la pena.

Algunas preguntas más que vale la pena hacerse antes de adoptar esto:

"¿No es esto solo un script doctor (make doctor, bin/setup) con pasos extra?" Conceptualmente, sí -- muchos repositorios maduros ya escriben uno a mano. La diferencia de DevTwin es que la mayoría de los repositorios no tienen uno, escribir uno bueno por ecosistema es trabajo real, su salida es JSON estructurado sobre el que un agente puede razonar en lugar de texto plano que lee un humano, y las mismas 10 herramientas funcionan de forma idéntica en todos los repositorios en lugar de un script hecho a medida por proyecto con sus propias convenciones y puntos ciegos.

"¿Esto solo funciona con Claude / Claude Code?" No. DevTwin habla el Model Context Protocol estándar -- cualquier cliente compatible con MCP (Claude Desktop, Cursor, Windsurf, etc.) puede conectarse a él de la misma manera. Nada de esto es específico de Claude.

"¿Es seguro depender de esto -- se mantiene activamente?" Está en estado Alpha y es un proyecto joven -- lee el código (es corto) antes de confiar en él en un flujo de trabajo del que dependas, igual que harías con cualquier nueva dependencia de herramientas de desarrollo.

"¿Podría sugerir algo incorrecto, o ejecutar automáticamente una recomendación mala?" Ninguna herramienta aquí ejecuta una cadena de recommendations -- esas son solo texto para que el agente (o tú) lo lea y decida. dev_check es la única herramienta que ejecuta algo, y solo comandos que reconoció por sí misma contra una lista fija -- ver Modelo de seguridad.

"¿Llama a casa o envía telemetría a algún sitio?" No. Cero llamadas de red propias -- ver Arquitectura local-first.

"No quiero que un servidor MCP ejecute ningún comando en mi máquina." 9 de las 10 herramientas son de solo lectura puras (lectura de archivos, comprobaciones de versiones). Solo dev_check ejecuta algo, y solo comandos que el propio DevTwin reconoció de los archivos del proyecto, comprobados contra una lista de permitidos, con shell=False y un tiempo de espera -- ver Modelo de seguridad para saber exactamente qué permite y qué no.

Beneficios

• Menos diagnósticos erróneos. Sin DevTwin, un agente que depura un fallo solo puede leer código y adivinar -- a menudo propondrá una corrección de código para lo que en realidad es una versión de Node incorrecta o una base de datos detenida. DevTwin le da la verdad del terreno en lugar de una conjetura.

• Una llamada en lugar de muchas. Una sola llamada a dev_health agrupa ~10 comprobaciones subyacentes (versiones de runtime, estado de dependencias, servicios, puertos, Git) en un resultado estructurado y puntuado -- en lugar de que un agente haga una docena de idas y vueltas de shell separadas y analice la salida de CLI sin procesar cada vez.

• La misma comprobación cada vez. Las comprobaciones exactas por ecosistema (Gradle wrapper vs. Gradle del sistema, .nvmrc vs. engines de package.json, ...) están codificadas una vez, para que el diagnóstico sea consistente entre sesiones en lugar de depender de lo que al agente se le ocurra ejecutar.

• Más seguro que darle un shell a un agente. Sin ejecución arbitraria de comandos, sin operaciones destructivas, nunca -- ver Modelo de seguridad.

• Los secretos nunca se tocan. Las variables de entorno que parecen secretas se comprueban solo por presencia; los valores nunca se leen ni se devuelven -- ver Modelo de privacidad.

• Funciona incluso donde el agente no tiene shell. Los clientes MCP sin herramienta Bash (algunos asistentes de IDE, agentes restringidos) obtienen esta capacidad por completo, no cero capacidad.

Coste de tokens

Números reales, no una estimación -- medidos directamente de los esquemas de herramientas MCP de este propio servidor (mcp.list_tools()) y de una respuesta real de dev_health(), usando la aproximación estándar de ~4 caracteres por token.

Dos momentos diferentes gastan tokens, y cuestan de manera muy diferente:

Desglose de esquema por herramienta (medido):

La conclusión honesta: para un único diagnóstico puntual en una sesión que de otro modo nunca toca una pregunta de entorno, el Bash sin procesar puede salir más barato en tokens totales -- el impuesto fijo de ~1.400 tokens del esquema a menudo supera el ahorro de reemplazar varios comandos de shell con una llamada. Ver la comparación práctica a continuación para números reales en ambos lados.

El caso de DevTwin se fortalece cuantas más preguntas de entorno surgen en una sesión (el impuesto fijo se paga una vez; cada pregunta posterior cuesta ~150 tokens con DevTwin frente a cientos más con Bash sin procesar cada vez) -- y su ventaja real no es en absoluto el recuento bruto de tokens, es la consistencia, la seguridad y el funcionamiento en clientes MCP que no tienen herramienta Bash. Ver Beneficios y Compensaciones honestas.

Implicación práctica: registra DevTwin por proyecto, no para todo el usuario, para que el impuesto fijo solo se pague en sesiones donde sea realmente útil -- ver Usarlo en otro proyecto.

Compensaciones honestas

DevTwin no es una herramienta de uso diario para un entorno estable -- nadie necesita volver a comprobar "¿está Postgres en ejecución?" en cada función que escribe. Es una herramienta de emergencia: de alto valor en momentos específicos (un clon reciente, una compilación que falla misteriosamente, justo antes de un commit), e inactiva el resto del tiempo. Ese es el patrón de uso previsto, no una deficiencia.

• El gasto de tokens se paga en cada turno en el momento en que se conecta, se use o no — consulta Coste de tokens para cifras reales medidas.

• No gana de forma fiable en tokens para una sola consulta puntual; gana en consistencia, seguridad y alcance en clientes sin shell — consulta Beneficios.

• Si un agente ya tiene acceso completo al shell de un repositorio que controlas por completo y rara vez tiene desviación de entorno, puede que ahí no necesites DevTwin en absoluto.

• DevTwin se justifica sobre todo en: repositorios compartidos/de incorporación, configuraciones de agentes menos fiables o sin shell, y monorepos multiecosistema donde "qué compruebo siquiera" es la parte difícil.

Con DevTwin vs. sin DevTwin: un ejemplo práctico

Supón que le preguntas a un agente "¿por qué falla npm test?" y la causa real es un desajuste de la versión de Node y que Postgres no está en ejecución.

Sin DevTwin (agente usando Bash puro): tiene que adivinar la secuencia correcta, un comando a la vez:

cat package.json                      # spot "engines": {"node": ">=20"}
node --version                        # v16.20.0 -- mismatch found
grep -i "pg\|postgres" package.json   # spot the Postgres dependency
cat .env                              # risk: may print a real secret into context
lsof -i :5432                         # nothing listening
docker ps                             # check if it's in a container instead

Seis idas y vuelos, una ruta de investigación que el agente tuvo que improvisar, una posibilidad real de que un secreto se filtre en la conversación en el paso 4, y aproximadamente 400-800 tokens de texto de comando más salida (varía según los tamaños de archivo y cuántos contenedores Docker estén ejecutándose).

Con DevTwin, una sola llamada:

dev_health()

{
  "status": "error",
  "summary": "2 issues found: runtime drift, service down",
  "issues": [
    "Node 16.20.0 installed, project requires >=20 (from package.json engines)",
    "Postgres required (found in docker-compose.yml) but not running on 5432"
  ],
  "recommendations": [
    "nvm install 20 && nvm use 20",
    "docker compose up -d postgres"
  ]
}

La misma conclusión, ~150 tokens por la respuesta — más el canon fijo de esquema de ~1.400 tokens ya pagados em ese turno de todos modos (consulta Coste de tokens). Una llamada en lugar de seis, sin posibilidad de filtrar un secreto y exactamente la misma comprobación prerfijada cada vez, en lugar de una investigación improvisada que varía de una sesión a otra.

Preguntas de ejemplo que esto permite

• "Revisa mi entorno de desarrollo."

• "¿Por qué falla la compilación de mi proyecto Kotlin?"

• "¿Es correcta mi versión de Node para este repositorio?"

• "¿Por qué no se conecta mi aplicación a Postgres?"

• "¿Se desvía mi entorno de lo que this repostorio espera?"

• "¿Qué debería ejecutar antes de hacer commit?"

• "Acabo de clonar este repositorio, ¿qué necesito para ponerlo en marcha?"

Ejemplos por lenguaje

Una fila por ecosistema soportado: una pregunta que realmente harías, qué comprueba DevTwin para responderla y el comando de test/build que reconoce para dev_check.

Arquitectura

Un solo servidor MCP, muchos adaptadores de ecosistema: no un servidor separado por lenguaje.

MCP server -> core (workspace/detector/health/drift/diagnostics) ->
adapters (python/node/jvm/go/rust/dotnet/swift/ruby/php/generic) ->
system inspection (os/process/ports/env/fs/docker) ->
service detection (postgres/redis/generic)

Detalles completos en docs/architecture.md. Cómo añadir un nuevo adaptador de lenguaje: docs/adapters.md.

Ecosistemas soportados

También los proyectos que no coincidan con un adaptador específico siguen obteniendo una salida útil del adaptador genérico: DevTwin nunca se queda vacío para un proyecto no reconocido.

Instalación

uv pip install devtwin-mcp
# or
pip install devtwin-mcp

Para desarrollo local desde un clon de este repositorio, consulta docs/development.md.

Configuración del cliente MCP

SinTaxis de configuración exacta varía según el cliente; consulta la documentación de tu cliente. Genéricasmente, DevTwin es un servidor MCP por stdio que se invoca como:

{
  "mcpServers": {
    "devtwin": {
      "command": "devtwin"
    }
  }
}

Para desarrollo local desde un clon (sin instalar el paquete):

{
  "mcpServers": {
    "devtwin": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/devtwin-mcp", "devtwin"]
    }
  }
}

Verifica el descubrimiento de herramientas con el MCP Inspector:

npx @modelcontextprotocol/inspector uv run devtwin

Usarlo en otro proyecto (para otros desarrolladores)

DevTwin es un solo binario: puedes apuntar todos los proyectos que quieraas a la misma instalación, sin necesidad de reinstalarlo para cada proyecto. Dos ámbitos de aplicación:

Ámbito de proyecto: pon un .mcp.json en la raíz del proyecto:

{
  "mcpServers": {
    "devtwin": {
      "command": "/absolute/path/to/devtwin-mcp/.venv/bin/devtwin"
    }
  }
}

o con la CLI de Claude Code:

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope project

Ámbito de usuario:

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope user

Después de añadirlo, reinicia el cliente (o reconecta el servidor MCP); luego simplemente haz preguntas normales: vea Pregunta de ejemplo que esto habilita.

Consejo para monorepos: en un repositorio que mezcla plataformas (p. ej., Android, iOS y backend), dirige las preguntas a la subcarpeta específica en lugar de a la raíz del repositorio, p. ej. "Revisa el estado de la app android/". dev_detect, en la raíz de un repositorio mixto, informa de todos los ecosistemas que encuentra; es útil una vez, pero es ruidoso para una comprobación específica.

Referencia de herramientas

Todas las herramientas devuelven {status, summary, data, issues, recommendations}. status es uno de ok, warning, error o unknown.

Modelo de seguridad

• Sin ejecución arbitraria de comandos. No existe la herramienta execute_shell. dev_check solo ejecuta comandos que el propio DevTwin reconoce a partir de los archivos del proyecto, verificados contra una lista de permitidos, ejecutados con shell=False y un tiempo límite.

• Sin acciones destructivas, nunca. DevTwin nunca ejecuta git reset --hard, rm -rf, kill -9, docker compose down, eliminación de archivos de bloqueo o mutación de .env.

• dev_prepare solo planifica. Clasifica cada paso propuesto (read_only/safe/requires_approval/dangerous) y nunca ejecuta nada por sí mismo.

Detalles completos: docs/security.md.

Modelo de privacidad

• Las variables de entorno se verifican solo en cuanto a su presencia cuando su nombre parece secreto (PASSWORD, TOKEN, SECRET, API_KEY, PRIVATE_KEY, ACCESS_KEY, AUTH, CREDENTIAL, ...) — los valores nunca se devuelven.

• Los archivos .env se escanean solo para obtener los nombres de las variables.

• dev_precommit marca archivos en el área de preparación (staging) que parecen secretos sin leer ni informar sobre su contenido.

Arquitectura local-primero

• Sin componente de servidor, sin cuenta, sin llamadas de red propias más allá de los comandos locales que inspecciona (git, docker, cadenas de herramientas de lenguaje).

• Todo lo que informa proviene de archivos y procesos que ya están en la máquina donde se ejecuta.

Desarrollo

uv sync --all-extras
uv run pytest
uv run ruff check .
uv run mypy src
uv run devtwin

Consulta docs/development.md para el flujo de trabajo completo.

Contribuciones

Consulta CONTRIBUTING.md. Añadir un nuevo ecosistema de lenguaje es la contribución más común — consulta docs/adapters.md para una plantilla, o src/devtwin/adapters/swift.py, ruby.py y php.py para ejemplos reales y fusionados en los que puedes basar el tuyo.

Hoja de ruta

• Adaptadores de ecosistema adicionales: Elixir, Dart, Scala, C/C++ (CMake/Bazel/Buck), Nix (consulta docs/adapters.md para saber cómo añadir uno)

• Detectores de servicios adicionales (MySQL/MariaDB, MongoDB, Kafka, RabbitMQ)

• Comparación de deriva más rica contra la configuración de CI (p. ej., matrices de runtime de GitHub Actions)

• Caché local opcional de comprobaciones costosas entre llamadas a herramientas dentro de una sesión

Licencia

Apache-2.0 — consulta LICENSE.