physics-lint-mcp

📖 Sitio de documentación — la narrativa del portafolio, los conceptos, un recorrido completo y qué demuestra todo esto (y qué no).

Un oráculo de física que tu agente de IA no puede eludir con palabras.

Un LLM no tiene forma de distinguir una matriz de parámetros S físicamente imposible de una plausible — ambas son solo números. Entrégale a un agente un modelo fabricado y razonará con confianza sobre él, lo citará y construirá sobre él. Nada en el bucle objeta.

Estas herramientas MCP le dan al agente la verdad fundamental del álgebra lineal en lugar de su propio juicio.

Inicio rápido en 30 segundos

git clone https://github.com/nickharris808/physics-lint-mcp.git
cd physics-lint-mcp

pip install git+https://github.com/nickharris808/sparam-lint.git@main \
            git+https://github.com/nickharris808/maxwell-lint.git@main \
            .

Los dos verificadores son paquetes separados y se obtienen de sus propios repositorios; el servidor es el . al final. Confirma que el servidor responde por stdio antes de conectarlo a un cliente:

$ printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | physics-lint-mcp | tail -1 | python3 -m json.tool | grep '"name"'
                "name": "check_touchstone",
                "name": "self_test",
                "name": "check_screening",
                "name": "pairwise_error",

Aún no en PyPI. pip install physics-lint-mcp es la instalación prevista una vez publicado; hasta entonces, el comando de tres paquetes anterior es el que funciona.

Related MCP server: mcp-openems

Configurar

Claude Desktop / Cursor / cualquier cliente MCP:

{
  "mcpServers": {
    "physics-lint": {
      "command": "physics-lint-mcp"
    }
  }
}

Se incluye un mcp.json listo para usar con el paquete.

Herramientas

Los esquemas que el servidor anuncia a través de tools/list son la versión autoritativa de esa tabla, y una prueba verifica que ambos coinciden.

Un ejemplo práctico: un agente que no puede engañarse a sí mismo

El fallo que esto previene es específico. A un agente se le entrega un .s2p de un proveedor, se le pregunta si el enlace cerrará, y razona con fluidez sobre números que describen una red que no puede existir. Nada en el bucle objeta, porque un LLM no tiene forma de distinguir una matriz S imposible de una plausible.

Conecta el servidor, y lo primero que vale la pena hacer en una sesión es pedirle al verificador que se demuestre a sí mismo:

Tú: Antes de mirar el modelo, ejecuta self_test.

Agente: (llama a self_test) La batería discrimina: cinco redes construidas para violar una ley cada una fueron todas rechazadas.

Ahora el modelo:

Tú: Comprueba vendor/lna_stage.s2p.

Agente: (llama a check_touchstone con path="vendor/lna_stage.s2p") Esta red no es físicamente realizable como dispositivo pasivo: falla la pasividad y la conservación de energía. No razonaré a partir de sus valores.

Esa última frase no es que el agente sea cuidadoso — es el campo interpretation que viene en el resultado, escrito para que un modelo lo lea. A un agente que solo recibe {"passed": false} a menudo seguirá adelante.

Dos cosas que el diseño prohíbe, y ambas importan más de lo que parecen: el agente no puede reparar el modelo, porque cada herramienta es de solo lectura; y no puede confundir un fallo con un bloqueo, porque un fallo de física regresa como resultado en lugar de un error de transporte. Las siguientes tres secciones son esas dos propiedades en detalle, y la tercera es el caso que te morderá primero.

Solución de problemas

physics-lint-mcp: command not found — el script de consola no se instaló. Comprueba pip show physics-lint-mcp; si está ahí, el directorio bin del entorno no está en PATH, lo cual es común cuando un cliente lanza el servidor con un shell diferente. Usa la ruta absoluta en mcp.json: {"command": "/full/path/to/venv/bin/physics-lint-mcp"}.

El cliente muestra que el servidor no pudo iniciarse — ejecuta primero la prueba de humo stdio del inicio rápido manualmente. Es el mismo camino de código sin la supervisión del cliente, por lo que el traceback es visible.

No module named 'sparam_lint' — los dos verificadores son paquetes separados y no se instalan automáticamente. Instala los tres, como muestra el inicio rápido.

Una llamada a herramienta devuelve isError: true y el agente se detiene — eso es un veredicto de física, no un fallo. El resultado lleva las leyes fallidas y una interpretación; tu agente debería leerlas en lugar de tratar la llamada como fallida.

No regresa nada en absoluto — el servidor habla JSON-RPC por stdio, un objeto por línea. Un cliente que agrupa varios objetos en una línea, o que escribe sin un salto de línea final, se colgará. La solicitud initialize debe venir primero.

La lista de herramientas es más corta que la tabla anterior — estás ejecutando una versión antigua. tools/list se genera a partir de las mismas definiciones contra las que se prueba la tabla, por lo que no pueden discrepar dentro de una versión.

Lo que ve el agente

Cada resultado lleva un campo interpretation escrito para que un modelo lo lea, porque un agente actúa sobre prosa, no sobre un booleano:

{
  "physically_admissible": false,
  "failed_laws": ["passivity", "energy_conservation"],
  "interpretation": "This network is not physically realizable as a passive
    device. Do not use it as a reference and do not reason from its values.
    One legitimate exception: a non-reciprocal device such as a ferrite
    isolator will correctly fail the reciprocity law by design."
}

Esa última frase importa. A un agente que solo se le dice "la reciprocidad falló" "arreglará" útilmente un aislador perfectamente bueno.

Y en un resultado limpio, la interpretación dice lo que el veredicto no significa:

Las cinco leyes se cumplen; la red es físicamente admisible. Ten en cuenta que esto NO significa que sea precisa: un modelo pasivo de la estructura incorrecta pasa todas las leyes aquí.

Cada herramienta es de solo lectura

Nada aquí escribe, fabrica o repara un modelo. Un agente que pudiera parchear silenciosamente una red fallida derrotaría el propósito de tener un oráculo, por lo que la ausencia de E/S está garantizada por una prueba.

Un fallo de física es un resultado, no un error

Un archivo que falla las leyes devuelve un resultado normal con isError: true y el veredicto completo, en lugar de un error a nivel de transporte. El agente necesita ver el fallo para razonar sobre él; un error de protocolo opaco no le enseña nada.

Pruébalo sin un agente

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | physics-lint-mcp

Alcance, honestamente

Estas herramientas verifican admisibilidad física, no precisión. Un modelo pasivo de una estructura completamente incorrecta pasa todas las comprobaciones. Son un piso, no un sustituto de la validación contra una solución de campo o una medición.

El resto del kit de herramientas

Ocho artefactos que responden una pregunta en diferentes lugares: ¿es este modelo físicamente posible? Cada uno es un calificador: puede decirte que un modelo está mal; ninguno puede decirte que uno está bien.

Estas herramientas califican un modelo. Producir uno que sea pasivo por construcción — de modo que no pueda fallar estas leyes cualesquiera que sean sus parámetros — y preciso a velocidad en el régimen de muchos cuerpos, con abstención calibrada y un certificado de aprobación a prueba de fallos, es el núcleo comercial: ChipletOS.

Licencia

Apache-2.0. Ver LICENSE; derechos de autor en NOTICE.

El certificado de aprobación y la síntesis pasiva por construcción junto a los que se escribieron estas herramientas son el núcleo cerrado de ChipletOS.

Contribuir

Una regla innegociable aquí: cada herramienta permanece de solo lectura — un agente que pudiera parchear silenciosamente un modelo fallido derrotaría el propósito de tener un oráculo. CONTRIBUTING.md tiene el detalle. Cada repositorio hermano establece la suya propia, y difieren — eso es deliberado, y es por lo que cada uno es confiable en sus propios términos.

Citación

CITATION.cff es legible por máquina; GitHub renderiza un botón "Cite this repository" a partir de él.