langmcp

LangMCP

Servidor MCP somente leitura para inspecionar checkpoints do LangGraph, estado de threads e memória de longo prazo.

O LangMCP ajuda você a responder à pergunta de depuração que os traces nem sempre respondem:

O que está realmente salvo na minha camada de persistência do LangGraph agora?

Não é um MCP SQL genérico. Ele usa APIs nativas de checkpointer e store do LangGraph, conecta-se por meio de perfis nomeados e mantém as credenciais do banco de dados fora dos argumentos das ferramentas.

Por que LangMCP

Quando um agente com estado se comporta de forma estranha, o problema geralmente não é apenas o prompt. Pode ser o checkpoint do qual ele retomou, o ID do usuário no estado configurável, o namespace do store usado para memória ou um histórico de mensagens muito grande.

O LangMCP oferece aos clientes MCP, como Cursor e Claude Desktop, uma superfície de inspeção segura para essas perguntas.

LangMCP	Não é LangMCP
Inspeção somente leitura da persistência do LangGraph	Execução arbitrária de SQL
Conexões baseadas em perfil	DSNs brutos em argumentos voltados ao modelo
Ferramentas, recursos e prompts para depurar estado	Um substituto para LangSmith ou LangGraph Studio
Servidor MCP stdio local para desenvolvimento	API do LangGraph Agent Server

Use LangSmith para traces, LangGraph Studio para fluxos de trabalho visuais de grafos e LangMCP quando quiser que um assistente no seu editor inspecione o estado persistido por meio de uma interface estreita somente leitura.

Recursos

• Configuração baseada em perfil com expansão de variáveis de ambiente.
• Aplicação de somente leitura na v0.1.
• Redação de segredos em verificações de saúde e saída de erros.
• Inspeção de checkpointer PostgreSQL, SQLite e Redis.
• Inspeção de memória de longo prazo PostgreSQL PostgresStore.
• Ferramentas MCP para threads, checkpoints, dados do store e análise.
• Recursos MCP para URIs de estado estáveis e legíveis.
• Prompts MCP para fluxos de trabalho de depuração repetíveis.
• Paginação e truncamento para respostas grandes.

Instalação

uv pip install "langmcp[all]"

Ou execute sem instalar:

uvx "langmcp[all]" --version

O LangMCP suporta Python 3.11 e 3.12. O repositório inclui um arquivo .python-version definido para Python 3.12.

Configuração

Copie os arquivos de exemplo de configuração e ambiente:

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

Defina um URI de banco de dados somente leitura em .env:

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

O LangMCP carrega .env automaticamente quando presente. Variáveis de ambiente do shell existentes têm precedência.

Exemplo 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"

Defina user_namespace para o template de namespace que seu grafo usa para memória de longo prazo. O padrão é {user_id} para compatibilidade. Para stores organizados como users/<user_id>/..., use users/{user_id}. A ferramenta summarize_user_memory também aceita namespace_prefix para substituir o template do perfil em uma única chamada.

Substituições de ambiente:

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

Verificar Configuração

Execute:

langmcp doctor --config ./langmcp.toml

O comando doctor verifica conectividade, tipos de backend, status de configuração, versões de pacotes e redige campos sensíveis de URI.

Configuração no Cursor

Veja examples/cursor-mcp.json.

Formato mínimo:

{
  "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"
      }
    }
  }
}

Inicie o servidor diretamente:

langmcp serve --config ./langmcp.toml

Exemplos de Prompts para o Assistente

Depois de conectar via MCP, pergunte ao seu assistente:

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.

Ferramentas MCP

Todas as ferramentas aceitam profile opcional, salvo indicação contrária. As respostas incluem profile, truncated e campos de paginação quando aplicável.

Ferramenta	Descrição
health_check	Conectividade, tipos de backend, URIs redigidos
list_profiles	Nomes de perfis e tipos de backend
list_threads	Descobrir IDs de threads
get_thread_state	Estado do checkpoint mais recente ou específico
list_checkpoint_history	Lista paginada de checkpoints
get_checkpoint	Snapshot completo de um checkpoint
compare_checkpoints	Valores de diff e delta de contagem de mensagens
summarize_thread	Resumo em formato de transcrição
analyze_context_window	Estimativa de tokens e avisos de tamanho
analyze_memory_gaps	Dicas de ID de usuário no store versus na thread
list_namespaces	Tuplas de namespace do store
search_store	Busca sob prefixo de namespace
get_store_item	Valor completo do store por chave
summarize_user_memory	Chaves agrupadas sob um template de namespace de usuário configurado ou explícito

Recursos MCP

Os recursos expõem estado legível por meio de URIs MCP estáveis.

URI do Recurso	Descrição
langmcp://profiles	Perfis configurados e perfil ativo
langmcp://profiles/{profile}/health	Conectividade e status de configuração
langmcp://profiles/{profile}/threads	IDs de threads descobertos
langmcp://profiles/{profile}/threads/{thread_id}/state	Estado mais recente da thread
langmcp://profiles/{profile}/threads/{thread_id}/summary	Resumo da thread em formato de transcrição
langmcp://profiles/{profile}/threads/{thread_id}/checkpoints	Histórico recente de checkpoints
langmcp://profiles/{profile}/threads/{thread_id}/checkpoints/{checkpoint_id}	Snapshot completo do checkpoint
langmcp://profiles/{profile}/threads/{thread_id}/context-analysis	Análise de janela de contexto
langmcp://profiles/{profile}/store/namespaces	Namespaces de memória de longo prazo
langmcp://profiles/{profile}/store/items/{namespace}/{key}	Um item do store
langmcp://profiles/{profile}/users/{user_id}/memory-summary	Resumo de memória do usuário

Para namespaces com várias partes, prefira a ferramenta get_store_item se seu cliente MCP tratar / como separador de caminho dentro dos parâmetros de recurso.

Prompts MCP

Os prompts empacotam investigações repetíveis.

Prompt	Descrição
debug_thread	Diagnosticar uma thread a partir de resumo, checkpoints, análise de contexto e dicas de memória
investigate_memory_gap	Verificar se o estado da thread e a memória de longo prazo estão alinhados
compare_thread_checkpoints	Explicar diferenças de comportamento entre dois checkpoints
inspect_user_memory	Resumir e verificar a memória de longo prazo de um usuário

Matriz de Backends

Backend	Checkpointer	Store na v0.1
PostgreSQL	Completo	Completo via PostgresStore
SQLite	Completo	Não suportado
Redis	Completo	Não suportado

Segurança

1. As ferramentas aceitam nomes de perfis, não DSNs brutos.
2. read_only=true é aplicado na v0.1.
3. Use um usuário PostgreSQL somente leitura para ambientes compartilhados.
4. Senhas são redigidas em health_check e na saída da CLI.
5. A descoberta de threads no Redis usa SCAN com limites. Evite varreduras amplas em instâncias muito grandes.
6. Faça commit de examples/langmcp.example.toml e .env.example, não de arquivos reais de langmcp.toml ou .env.

Desenvolvimento

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

Os testes de integração usam serviços Docker locais:

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

Use os valores de teste locais de docker-compose.test.yml. Eles são apenas para testes de integração com Docker.

Roadmap

• Adaptador para LangGraph Agent Server.
• Transporte HTTP com autenticação de equipe.
• Ferramentas de inspeção de vector store.
• Fluxos de escrita cuidadosamente escopados, como update_thread_state e resume_thread.

Contribuindo

Issues e pull requests são bem-vindos. Veja CONTRIBUTING.md.

Boas ideias para primeiras contribuições:

• Adicionar exemplos para um backend de persistência específico do LangGraph.
• Melhorar mensagens de erro para backends de store não suportados.
• Adicionar um teste de recurso ou prompt para um caso de borda.

Licença

MIT. Veja LICENSE.