Cursor

Pré-requisitos

Use o Cursor IDE com Configurações -> Recursos -> MCP ou suporte do marketplace. Interface e pré-requisitos:

• Interface concreta: Cursor IDE (~/.cursor/mcp.json ou Configurações -> Recursos -> MCP).
• Endpoint: https://xmemo.dev/mcp.
• Modo de autenticação preferencial: Browser OAuth.
• Modo de autenticação alternativo: Token de portador direto para ambientes headless e contêineres.
• Conta: Conta válida do XMemo em https://xmemo.dev.

Instalação / configuração

Abra Cursor Configurações -> Recursos -> MCP ou configure ~/.cursor/mcp.json. Para operação headless, use o bloco de configuração direta com referência de token de ambiente em vez do fluxo do navegador:

• Caminho OAuth: Configure apenas a URL hospedada e deixe o primeiro uso acionar o consentimento do navegador.
• Alternativa direta: Mantenha o token em XMEMO_KEY, nunca diretamente no arquivo de configurações.
• Não misture a configuração de URL OAuth com um cabeçalho Authorization na mesma entrada.

Definir a credencial

O caminho OAuth não requer chave — conclua o Browser OAuth no primeiro prompt. Para a alternativa headless direta, defina XMEMO_KEY no ambiente de shell e nunca cole valores de token nas configurações do Cursor:

# OAuth path: no XMEMO_KEY needed (browser prompt)
# Direct fallback:
export XMEMO_KEY='<your-xmemo-token>'

Gerar / confirmar XMEMO_AGENT_INSTANCE_ID

Os trechos de código revisados de OAuth e direto do Cursor não exigem um cabeçalho de instância no lado do cliente. Se um wrapper headless fornecer XMEMO_AGENT_INSTANCE_ID, gere-o uma vez por perfil local e reutilize-o.

Preservar o bloco de configuração existente

Caminho OAuth preferencial: Use a configuração revisada do Cursor de apenas URL em ~/.cursor/mcp.json para autenticação OAuth baseada em navegador:

{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp"
    }
  }
}

Bloco de configuração de fallback direto

Fallback direto headless: Ao executar o Cursor em ambientes headless ou não interativos, configure o cabeçalho Authorization referenciando ${env:XMEMO_KEY} do seu ambiente local:

{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}"
      }
    }
  }
}

Reiniciar o cliente

Reinicie o Cursor ou desative e ative o servidor MCP em Configurações -> Recursos -> MCP após editar a configuração para que as alterações tenham efeito.

Testar com uma chamada real de recall

Faça a primeira chamada MCP somente leitura. Esta é uma invocação real de recall, não um espaço reservado para verificação de integridade, e não grava na memória.

recall({ query: "connection check", limit: 1 })

Resposta esperada (formato literal)

Uma chamada bem-sucedida retorna o formato de texto classificado público abaixo; a referência e o conteúdo são valores reais do espaço de memória autorizado.

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

Primeira tarefa útil: Ciclo de vida de memória sintética

Exercite a tarefa completa de memória sintética dentro do Cursor Composer ou modo Agent:

• 1. Salvar fato sintético: Peça ao Cursor para lembrar da convenção ("Demo project timestamps use UTC.") em "projects/demo-onboarding/conventions".
• 2. Transição sem estado: Inicie um novo chat no Cursor Composer ou reabra o espaço de trabalho do projeto.
• 3. Recall com atribuição de fonte: Consulte "demo project timestamp format". Confirme Reference e Location retornados.
• 4. Corrigir memória: Chame update_memory com o ID ativo para formatar os registros de data e hora com ISO 8601.
• 5. Limpeza opcional: Chame forget com o ID da memória quando os testes de integração forem concluídos.

Recursos e ferramentas de perfil

O Cursor tem acesso a ferramentas qualificadas por perfil definidas no contrato de documentação do MCP para o perfil cursor-plugin:

• Ferramentas de memória principais: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context, search_knowledge.
• Ferramentas de instantâneos e conflitos: create_restart_snapshot, restore_restart_snapshot, list_memory_versions, list_memory_conflicts, resolve_memory_conflict.
• Ferramentas de projeto e planejamento: get_mcp_identity, get_project_context, get_timeline, list_memory_todos, complete_memory_todo, create_memory_todo, update_project_decision, update_project_todo, update_state.
• Skills em nuvem e governança: recall_cloud_skill, save_cloud_skill, propose_write, propose_todo_mutation, propose_profile_mutation, query_audit, record_event, memory_stats.

Limitações e limites

Limites operacionais e restrições para o Cursor:

• Pureza de configuração: Não misture a configuração apenas de URL OAuth com um cabeçalho Authorization no mesmo bloco de servidor.
• Limite do espaço de trabalho: O acesso à memória é estritamente limitado ao espaço de trabalho do usuário autenticado.
• Requisito de token headless: O fallback de MCP direto requer o provisionamento explícito de token de ambiente.

Erros comuns

O Cursor pode falhar no seu caminho OAuth ou no seu fallback headless direto:

• invalid_grant — O código de autorização OAuth é inválido, expirou ou já foi usado: reconecte o Cursor e autorize novamente.
• 401 invalid_token — O token de fallback direto está ausente, expirado ou inválido: verifique XMEMO_KEY no ambiente headless.
• 403 insufficient_scope — A credencial não concede memory:read: aprove o escopo necessário ou emita um token com ele.

Atualização e remoção

Procedimentos de manutenção para o Cursor:

• Atualização: Desative e ative o servidor nas configurações de MCP do Cursor para recarregar esquemas.
• Remoção: Exclua a entrada xmemo de ~/.cursor/mcp.json ou remova-a das configurações de MCP do Cursor.