Model Context Protocol (MCP)

Conecte assistentes de IA externos—incluindo Claude Desktop, Cursor, Antigravity, Windsurf e VS Code—diretamente aos seus workspaces locais do Noust em tempo real.

O servidor oficial @noust-app/mcp fornece comunicação bidirecional segura e 100% local entre modelos de IA e suas notas, documentos markdown do Nexus Pages e a topologia do canvas.

---

O que a IA Pode Fazer no Seu Workspace?

Em vez de copiar e colar textos para dentro de janelas de chat, o MCP concede ao seu assistente de IA acesso autônomo e contextual para compreender e interagir com o seu quadro:

• 🔍 Pesquisa e Consulta Inteligente: Peça para o assistente pesquisar notas, páginas do Nexus ou objetivos. O modelo obtém o conteúdo completo dos itens sem truncamento, ignorando tags visuais de HTML/CSS.

  "Procure no meu workspace do Noust pelo checklist de deploy e resuma as tarefas pendentes."

• ✍️ Criação, Edição e Exclusão no Canvas em Tempo Real: A IA cria novos cards, atualiza anotações existentes ou remove notas obsoletas direto na sua tela enquanto você assiste.

  "Crie uma nova nota no meu canvas com os 3 pontos principais que alinhamos nesta conversa."

• 🎯 Gestão de Objetivos e Metas: Acompanhe o progresso do projeto de forma autônoma. Modelos de IA podem criar novos objetivos, atualizar prazos, prioridades, marcar metas como concluídas, adicionar atualizações ou excluir itens.

  "Adicione um objetivo de alta prioridade para publicar o staging antes de sexta-feira e marque a meta anterior de migração como concluída."

• 📄 Controle Completo de Documentos Nexus: Estruture bases de conhecimento ricas sem esforço. Seu assistente pode criar novos documentos globais do Nexus, anexar seções em Markdown, atualizar conteúdos ou deletar documentos.

  "Crie um novo documento no Nexus intitulado 'Arquitetura da API' detalhando os endpoints discutidos."

• 🏷️ Flags Reutilizáveis e Harmonia de Cores: Consulte e crie flags personalizadas para os domínios do seu canvas. O assistente pode listar as cores já existentes (list_flags), selecionar tons distintos sob demanda (por exemplo, criando um tom de laranja único) ou gerar paletas contrastantes automaticamente.

  "Liste as flags deste domínio e crie uma nova flag 'Revisão' com um tom de laranja diferente das existentes."

• 🧭 Navegação Visual Interativa: Peça para a IA localizar qualquer elemento ou abrir documentos. O Noust move a câmera do canvas, ajusta o zoom e destaca notas com efeito de brilho, ou abre e foca documentos do Nexus diretamente.

  "Mostre na tela onde estão as metas da sprint de marketing."

• 🖼️ Visão Multimodal para Imagens Anexadas: Modelos com capacidade de visão (Claude 3.5 Sonnet, GPT-4o, Gemini) conseguem analisar imagens, diagramas e mockups colados dentro das suas notas.
• 📦 Contexto Direto com Recursos MCP: Em vez de disparar chamadas de ferramentas, modelos e clientes de IA podem anexar dados do workspace ativo, conteúdos de notas ou documentos do Nexus diretamente na janela de contexto através de URIs padrão de recursos MCP (noust://).

  "Analise noust://workspace/active para compreender a topologia dos domínios antes de sugerir melhorias."

• 🗂️ Roteamento Multi-Workspace e Entre Abas: Trabalhe em múltiplos workspaces abertos simultaneamente. O assistente de IA pode inspecionar abas ativas, direcionar ações a um workspace específico pelo nome através do parâmetro workspace, ou interagir diretamente com a pasta local ancorada.

  "Liste meus workspaces ativos e adicione uma nota de release no workspace 'Mobile App'."

---

Arquitetura Dual-Mode (Online & Offline)

O @noust-app/mcp foi arquitetado para ser resiliente tanto com o Noust aberto quanto fechado:

1. Modo Offline (Direto do Disco): Quando o Noust está fechado, o servidor MCP lê diretamente o arquivo .noust salvo na sua pasta local. A IA pode realizar buscas textuais profundas, consultar notas por ID ou referência amigável (ex.: 1A1) e analisar imagens completamente offline.
2. Modo Ao Vivo (WebSocket Bridge Zero-Trust): Quando o Noust está aberto no navegador com o salvamento local e o MCP ativados (painel Agent no Menu Shell), uma ponte WebSocket local efêmera (127.0.0.1:8421) conecta-se automaticamente. A IA ganha permissão para criar notas, editar cards e navegar no canvas na hora.

Workspaces Criptografados

Se o arquivo .noust estiver criptografado com a senha do usuário, o servidor MCP só funcionará com o Noust aberto e ativo no navegador. Dessa forma, agentes de IA não conseguem ler o conteúdo do .noust diretamente do disco e são estritamente forçados a utilizar as ferramentas oficiais via MCP Server.

Roteamento Multi-Workspace e Entre Abas

O Noust suporta abrir diferentes workspaces simultaneamente em várias abas do navegador, cada uma linkada à sua própria pasta local. O @noust-app/mcp gerencia ambientes multi-workspace de forma limpa e previsível:

• Âncora de Workspace Local: Quando o servidor MCP é iniciado com --workspace <pasta>, ele detecta o arquivo .noust local desse diretório. Se uma aba do navegador estiver sincronizando esse workspace, todas as operações têm essa aba como alvo padrão automático.
• Aba Única Ativa: Se houver apenas uma aba de workspace ativa no seu navegador, as operações são direcionadas a ela automaticamente, sem exigir o parâmetro de workspace.
• Desambiguação Entre Abas: Quando múltiplos workspaces estiverem ativos em diferentes abas do navegador e o cliente estiver rodando fora de um diretório de workspace específico (ou direcionando ações a outra aba), todas as ferramentas aceitam o parâmetro opcional workspace. Se houver ambiguidade, o servidor lista os nomes dos workspaces ativos e orienta o assistente a especificar qual workspace deve ser inspecionado ou editado.
• Inspeção de Status dos Workspaces: A ferramenta get_workspace_status relata todas as sessões ativas do navegador, os workspaces conectados e o alvo padrão atual.

---

Recursos Padrão do MCP (Resources)

Além de ferramentas executáveis (tools), o @noust-app/mcp implementa a especificação oficial de Recursos do Model Context Protocol (resources/list e resources/read). Isso permite que clientes de IA compatíveis—como Claude Desktop, Cursor e Antigravity—inspecionem o estado do workspace ou anexem notas e documentos diretamente no contexto do prompt sem o custo de chamadas de ferramentas:

URI do Recurso	Tipo	Formato	Descrição
noust://workspace/active	Estático	JSON (application/json)	Visão geral completa do workspace ativo: ID, nome, domínios, contagem de notas, documentos do Nexus e status da ponte ao vivo.
noust://notes/{noteId}	Modelo Dinâmico	Markdown (text/markdown)	Conteúdo completo de uma nota do canvas formatado em Markdown limpo (com título, domínio, referência no canvas 1A1 e corpo). Listado automaticamente via resources/list.
noust://documents/{docId}	Modelo Dinâmico	Markdown (text/markdown)	Conteúdo completo de um documento markdown do Nexus Pages (com título e corpo). Listado automaticamente via resources/list.
noust://objectives/active	Estático	JSON (application/json)	Lista em tempo real de todos os objetivos, metas, marcos, categorias e flags ativas no workspace.

Descoberta Automática de Recursos e Dual-Mode

• Autocompletar de Contexto em IDEs: Ambientes com suporte a resources/list listam automaticamente todas as notas e documentos do Nexus em seus seletores de contexto (como a referência @ no Cursor ou o seletor de recursos do Claude Desktop).
• Continuidade Dual-Mode: Quando o Noust está aberto no navegador com a ponte ativada, os recursos refletem o estado dinâmico em memória. Com o Noust fechado, os recursos são lidos diretamente do arquivo .noust local no disco.

---

Configuração Rápida nos Assistentes

Você não precisa instalar nada globalmente. Os clientes MCP executam o servidor sob demanda via npx.

Pré-requisitos

1. Node.js >= 18.0.0 instalado na máquina.
2. Um workspace do Noust vinculado a uma pasta local através do Salvamento Local Automático.
3. Ativar a Ponte MCP no Noust no painel Agent do Menu Shell.

1. Claude Desktop

Adicione o noust ao arquivo de configuração do seu Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "noust": {
      "command": "npx",
      "args": [
        "-y",
        "@noust-app/mcp",
        "--workspace",
        "/caminho/absoluto/para/sua/pasta-do-noust"
      ]
    }
  }
}

Formatação de Caminhos no Windows

Em arquivos JSON no Windows, os caminhos devem utilizar barras duplas (ex.: "C:\\Users\\SeuNome\\Documents\\Noust") ou barras normais (ex.: "C:/Users/SeuNome/Documents/Noust") para evitar erros de sintaxe no JSON.

2. Cursor IDE

Adicione o noust no .cursor/mcp.json do seu projeto ou em Settings > Features > MCP Servers:

{
  "mcpServers": {
    "noust": {
      "command": "npx",
      "args": [
        "-y",
        "@noust-app/mcp",
        "--workspace",
        "/caminho/absoluto/para/sua/pasta-do-noust"
      ]
    }
  }
}

3. Antigravity IDE

Adicione o noust no mcp_config.json do seu ambiente:

{
  "mcpServers": {
    "noust": {
      "command": "npx",
      "args": [
        "-y",
        "@noust-app/mcp",
        "--workspace",
        "/caminho/absoluto/para/sua/pasta-do-noust"
      ]
    }
  }
}

---

Segurança e Privacidade (Zero-Knowledge)

Modelos de IA na Nuvem e Privacidade de Dados

Embora o Noust e o @noust-app/mcp operem 100% localmente na sua máquina (127.0.0.1) e nunca transmitam suas notas ou dados para servidores do Noust, qualquer informação consultada pelas ferramentas do MCP (search_workspace, get_note, get_document, get_objective, etc.) torna-se contexto no prompt do seu assistente de IA.

Se o seu assistente estiver configurado para usar modelos na nuvem de terceiros (como Claude/Anthropic, ChatGPT/OpenAI ou Gemini/Google), o conteúdo recuperado do workspace será enviado pela internet aos servidores desse provedor de IA, ficando sujeito aos termos e políticas de privacidade da respectiva empresa.

Para ambientes com exigência estrita de soberania de dados ou informações estritamente confidenciais, configure seu cliente MCP para utilizar modelos de IA locais e auto-hospedados (por exemplo, via Ollama, LM Studio ou modelos open-source locais).

O @noust-app/mcp adota princípios rigorosos de segurança local-first:

• Loopback 100% Local: Todo o tráfego ocorre estritamente em 127.0.0.1. Nenhuma nota, token ou metadado é enviado para qualquer servidor externo.
• Token Efêmero de Segredo Compartilhado: Cada sessão gera um token aleatório de 256 bits (.noust-bridge.token) protegido com permissões de arquivo 0600. Apenas a aba do navegador local com permissão concedida na pasta consegue se autenticar.
• Confinamento Canônico de Caminhos: O servidor valida caminhos reais (realpath) e recusa categoricamente acessar arquivos fora do diretório autorizado do workspace ou sem a extensão .noust.
• Sanitização de Entradas: Todo o conteúdo criado por agentes externos de IA passa automaticamente pelo DOMPurify antes da renderização no canvas, impedindo injeções maliciosas de scripts (XSS).
• Imunidade contra CSWSH e DNS Rebinding: A ponte valida cabeçalhos Host e rejeita origens não autorizadas no navegador.
• Workspaces Criptografados: Se o arquivo .noust estiver criptografado com a senha do usuário, o servidor MCP só funcionará com o Noust aberto e ativo no navegador. Dessa forma, agentes de IA não conseguem ler o conteúdo do .noust diretamente do disco e são estritamente forçados a utilizar as ferramentas oficiais via MCP Server.

---

Documentação Técnica e Código-Fonte

Para desenvolvedores, opções de linha de comando (-d / -r) e especificação completa das ferramentas, consulte o repositório open-source oficial:

🔗 GitHub: noust-app/mcp