langmcp

LangMCP

Servidor MCP de solo lectura para inspeccionar checkpoints de LangGraph, estado de hilos y memoria a largo plazo.

LangMCP te ayuda a responder la pregunta de depuración que los traces no siempre responden:

¿Qué está realmente guardado en mi capa de persistencia de LangGraph en este momento?

No es un MCP SQL genérico. Utiliza las APIs nativas de checkpointer y store de LangGraph, se conecta mediante perfiles nombrados y mantiene las credenciales de la base de datos fuera de los argumentos de las herramientas.

Por qué LangMCP

Cuando un agente con estado se comporta de manera extraña, el problema a menudo no es solo el prompt. Podría ser el checkpoint desde el que se reanudó, el ID de usuario en el estado configurable, el namespace del store utilizado para la memoria, o un historial de mensajes sobredimensionado.

LangMCP ofrece a clientes MCP como Cursor y Claude Desktop una superficie de inspección segura para esas preguntas.

LangMCP	No LangMCP
Inspección de solo lectura de la persistencia de LangGraph	Ejecución arbitraria de SQL
Conexiones basadas en perfiles	DSNs crudos en argumentos dirigidos a modelos
Herramientas, recursos y prompts para depurar el estado	Un reemplazo para LangSmith o LangGraph Studio
Servidor MCP stdio local para desarrollo	API de LangGraph Agent Server

Usa LangSmith para traces, LangGraph Studio para flujos de trabajo gráficos visuales, y LangMCP cuando quieras que un asistente en tu editor inspeccione el estado persistido a través de una interfaz de solo lectura y acotada.

Características

• Configuración basada en perfiles con expansión de variables de entorno.
• Cumplimiento de solo lectura en v0.1.
• Redacción de secretos en comprobaciones de salud y salida de errores.
• Inspección de checkpointer para PostgreSQL, SQLite y Redis.
• Inspección de memoria a largo plazo de PostgreSQL PostgresStore.
• Herramientas MCP para hilos, checkpoints, datos de store y análisis.
• Recursos MCP para URIs de estado estables y legibles.
• Prompts MCP para flujos de trabajo de depuración repetibles.
• Paginación y truncamiento para respuestas grandes.

Instalación

uv pip install "langmcp[all]"

O ejecuta sin instalar:

uvx "langmcp[all]" --version

LangMCP es compatible con Python 3.11 y 3.12. El repositorio incluye un archivo .python-version configurado para Python 3.12.

Configuración

Copia los archivos de ejemplo de configuración y entorno:

cp examples/langmcp.example.toml langmcp.toml
cp .env.example .env

Establece una URI de base de datos de solo lectura en .env:

POSTGRES_URI=postgresql://READONLY_USER:READONLY_PASSWORD@HOST:5432/DB_NAME
LANGMCP_READ_ONLY=true

LangMCP carga .env automáticamente cuando está presente. Las variables de entorno existentes del shell tienen prioridad.

Ejemplo de langmcp.toml:

[defaults]
profile = "dev"
read_only = true
max_response_chars = 250000

[profiles.dev]
checkpointer = "${POSTGRES_URI}"
store = "${POSTGRES_URI}"
user_namespace = "users/{user_id}"

[profiles.local_sqlite]
checkpointer = "sqlite:///./.langgraph/checkpoints.db"

[profiles.local_redis]
checkpointer = "redis://localhost:6379/0"

Establece user_namespace en la plantilla de namespace que tu grafo utiliza para la memoria a largo plazo. El valor predeterminado es {user_id} por compatibilidad. Para stores organizados como users/<user_id>/..., usa users/{user_id}. La herramienta summarize_user_memory también acepta namespace_prefix para anular la plantilla de perfil en una sola llamada.

Anulaciones de entorno:

• LANGMCP_CONFIG
• LANGMCP_PROFILE
• LANGMCP_READ_ONLY
• POSTGRES_URI
• LANGMCP_CHECKPOINTER_URI
• LANGMCP_STORE_URI

Verificar la configuración

Ejecuta:

langmcp doctor --config ./langmcp.toml

El comando doctor comprueba la conectividad, los tipos de backend, el estado de configuración, las versiones de paquetes y redacta los campos sensibles de la URI.

Configuración de Cursor

Consulta examples/cursor-mcp.json.

Forma mínima:

{
  "mcpServers": {
    "langmcp": {
      "command": "uvx",
      "args": ["langmcp[all]", "serve", "--config", "ABSOLUTE_PATH_TO_LANGMCP_TOML"],
      "env": {
        "LANGMCP_READ_ONLY": "true",
        "POSTGRES_URI": "postgresql://READONLY_USER:READONLY_PASSWORD@HOST:5432/DB_NAME"
      }
    }
  }
}

Inicia el servidor directamente:

langmcp serve --config ./langmcp.toml

Ejemplos de prompts para el asistente

Una vez conectado a través de MCP, pregúntale a tu asistente:

Use LangMCP to summarize thread THREAD_ID and check whether user memory exists for USER_ID.

Compare checkpoint CHECKPOINT_A and CHECKPOINT_B for thread THREAD_ID. Tell me what changed.

Analyze whether thread THREAD_ID is carrying too much context.

Investigate a possible memory gap for thread THREAD_ID and user USER_ID.

Herramientas MCP

Todas las herramientas aceptan profile opcional salvo que se indique lo contrario. Las respuestas incluyen profile, truncated y campos de paginación cuando corresponda.

Herramienta	Descripción
health_check	Conectividad, tipos de backend, URIs redactadas
list_profiles	Nombres de perfiles y tipos de backend
list_threads	Descubrir IDs de hilos
get_thread_state	Estado del checkpoint más reciente o específico
list_checkpoint_history	Lista paginada de checkpoints
get_checkpoint	Instantánea completa de un checkpoint
compare_checkpoints	Valores de diff y delta del recuento de mensajes
summarize_thread	Resumen en formato de transcripción
analyze_context_window	Estimación de tokens y advertencias de tamaño
analyze_memory_gaps	Pistas de ID de usuario de store frente a hilo
list_namespaces	Tuplas de namespace del store
search_store	Búsqueda bajo un prefijo de namespace
get_store_item	Valor completo del store por clave
summarize_user_memory	Claves agrupadas bajo una plantilla de namespace de usuario configurada o explícita

Recursos MCP

Los recursos exponen estado legible a través de URIs MCP estables.

URI del recurso	Descripción
langmcp://profiles	Perfiles configurados y perfil activo
langmcp://profiles/{profile}/health	Estado de conectividad y configuración
langmcp://profiles/{profile}/threads	IDs de hilos descubiertos
langmcp://profiles/{profile}/threads/{thread_id}/state	Estado más reciente del hilo
langmcp://profiles/{profile}/threads/{thread_id}/summary	Resumen del hilo en formato de transcripción
langmcp://profiles/{profile}/threads/{thread_id}/checkpoints	Historial reciente de checkpoints
langmcp://profiles/{profile}/threads/{thread_id}/checkpoints/{checkpoint_id}	Instantánea completa del checkpoint
langmcp://profiles/{profile}/threads/{thread_id}/context-analysis	Análisis de la ventana de contexto
langmcp://profiles/{profile}/store/namespaces	Namespaces de memoria a largo plazo
langmcp://profiles/{profile}/store/items/{namespace}/{key}	Un elemento del store
langmcp://profiles/{profile}/users/{user_id}/memory-summary	Resumen de memoria del usuario

Para namespaces de varias partes, prefiere la herramienta get_store_item si tu cliente MCP trata / como separador de rutas dentro de los parámetros de recursos.

Prompts MCP

Los prompts agrupan investigaciones repetibles.

Prompt	Descripción
debug_thread	Diagnosticar un hilo a partir del resumen, checkpoints, análisis de contexto y pistas de memoria
investigate_memory_gap	Comprobar si el estado del hilo y la memoria a largo plazo están alineados
compare_thread_checkpoints	Explicar diferencias de comportamiento entre dos checkpoints
inspect_user_memory	Resumir y verificar la memoria a largo plazo de un usuario

Matriz de backends

Backend	Checkpointer	Store en v0.1
PostgreSQL	Completo	Completo a través de PostgresStore
SQLite	Completo	No compatible
Redis	Completo	No compatible

Seguridad

1. Las herramientas aceptan nombres de perfiles, no DSNs crudos.
2. read_only=true se aplica en v0.1.
3. Usa un usuario de PostgreSQL de solo lectura para entornos compartidos.
4. Las contraseñas se redactan en health_check y en la salida de la CLI.
5. El descubrimiento de hilos en Redis usa SCAN con límites. Evita escaneos amplios en instancias muy grandes.
6. Haz commit de examples/langmcp.example.toml y .env.example, no de archivos langmcp.toml o .env reales.

Desarrollo

uv pip install -e ".[all,dev]"
ruff check .
pytest tests/unit -v

Las pruebas de integración usan servicios Docker locales:

docker compose -f docker-compose.test.yml up -d
POSTGRES_URI=postgresql://langgraph:langgraph@localhost:5442/langgraph \
  REDIS_URI=redis://localhost:6379/0 \
  pytest tests/integration -v -m integration

Usa los valores de prueba locales de docker-compose.test.yml. Son solo para pruebas de integración con Docker.

Hoja de ruta

• Adaptador de LangGraph Agent Server.
• Transporte HTTP con autenticación de equipo.
• Herramientas de inspección de vector stores.
• Flujos de escritura cuidadosamente acotados, como update_thread_state y resume_thread.

Contribuciones

Las issues y los pull requests son bienvenidos. Consulta CONTRIBUTING.md.

Ideas para primeras contribuciones:

• Añadir ejemplos para un backend de persistencia específico de LangGraph.
• Mejorar los mensajes de error para backends de store no compatibles.
• Añadir una prueba de recurso o prompt para un caso límite.

Licencia

MIT. Consulta LICENSE.