Scrapbox/CoSense

Um servidor para a plataforma Scrapbox/CoSense para recuperar, listar, pesquisar e criar páginas.

Documentação

scrapbox-cosense-mcp

Visão Geral

Servidor MCP para Cosense (anteriormente Scrapbox).

Ferramenta	Descrição	Autenticação Necessária
`get_page`	Obter conteúdo da página, metadados e links	Para projetos privados
`list_pages`	Navegar pelas páginas com ordenação e paginação (máx. 1000)	Para projetos privados
`search_pages`	Busca em texto completo com destaque de palavras-chave (máx. 100 resultados)	Para projetos privados
`create_page`	Criar uma página via API WebSocket com corpo em Markdown/Scrapbox	Sim
`get_page_url`	Gerar URL direta para uma página	Não
`insert_lines`	Inserir texto após uma linha especificada em uma página	Sim
`edit_lines`	Substituir linha(s) com correspondência exata, incluindo um bloco de várias linhas (primeira correspondência, ou todas com `matchAll`)	Sim
`delete_lines`	Excluir linha(s) com correspondência exata, incluindo um bloco de várias linhas (primeira correspondência, ou todas com `matchAll`)	Sim
`delete_page`	Excluir uma página esvaziando todas as linhas — opt-in, veja abaixo	Sim
`rewrite_page`	Substituir todo o conteúdo de uma página — opt-in, veja abaixo	Sim
`get_smart_context`	Obter uma página e suas páginas vinculadas (1-salto/2-saltos) em formato otimizado para IA	Sim

create_page, insert_lines, edit_lines e rewrite_page suportam um parâmetro format ("markdown" ou "scrapbox") para controlar a conversão de conteúdo.

edit_lines substitui apenas a primeira linha correspondente por padrão. Defina matchAll: true para substituir todas as ocorrências. O padrão é deliberadamente conservador: uma linha como um marcador de lista ou uma linha em branco pode se repetir muitas vezes em uma página, e substituir todas de uma vez raramente é o que o chamador pretendia.

targetLineText pode conter quebras de linha para corresponder a um bloco contíguo de linhas. O bloco é substituído como um todo, então n linhas podem se tornar m linhas (por exemplo, colapsando várias linhas em uma). Correspondências de bloco com matchAll: true não se sobrepõem.

delete_lines usa a mesma semântica de correspondência exata (e de bloco), mas remove as linhas correspondentes em vez de substituí-las. Ele se recusa a excluir a linha do título (a primeira linha), porque isso renomearia ou removeria a própria página — use delete_page para isso.

`delete_page` e `rewrite_page` são opt-in

delete_page e rewrite_page não são registrados a menos que COSENSE_ENABLE_DELETE=true esteja definido. Sem isso, nenhuma das ferramentas aparece na lista de ferramentas, então um agente não pode chamá-las nem por engano. Este servidor é frequentemente adicionado a uma configuração MCP compartilhada, então a destruição de página inteira é exposta apenas para aqueles que deliberadamente a ativam.

A justificativa: insert_lines, edit_lines e delete_lines exigem correspondência exata, o que só é possível se o chamador realmente leu a página — eles só podem destruir linhas que já conhecem. delete_page e rewrite_page agem na página inteira independentemente de o chamador tê-la lido, então eles recebem uma porta de opt-in separada.

delete_page esvazia todas as linhas de uma página, e o Cosense remove uma página quando todas as suas linhas estão vazias. Não há desfazer. Duas proteções adicionais são incorporadas:

A página já deve existir. Uma página ausente retorna um erro em vez de um sucesso silencioso. (A API REST retorna uma linha de título mesmo para uma página que nunca foi criada, então a verificação analisa persistent, da mesma forma que create_page faz.)
dryRun: true informa quantas linhas seriam removidas e mostra as cinco primeiras, sem tocar na página.

`COSENSE_PROJECT_ALLOW_LIST` limita projetos alcançáveis

Toda ferramenta aceita uma substituição de projectName, que é como um único servidor atende vários projetos. Um ID de sessão frequentemente alcança mais projetos do que o padrão, então sem um limite, um agente que nomeia o projeto errado pode ler ou escrever lá. COSENSE_PROJECT_ALLOW_LIST é a cerca de opt-in: quando definido, apenas os projetos listados e COSENSE_PROJECT_NAME são aceitos, e qualquer outra coisa falha antes que uma solicitação seja enviada. Os nomes são correspondidos exatamente, incluindo maiúsculas/minúsculas, então uma variante de grafia não pode passar despercebida. Definir a variável para um valor vazio restringe apenas ao projeto padrão. Não definida mantém o comportamento antigo sem restrições.

rewrite_page substitui todo o conteúdo de uma página (o título é preservado como a primeira linha). Ele tem as mesmas proteções, mais duas próprias:

A página já deve existir — a verificação de persistent é invertida em relação a create_page, então um erro de digitação não pode criar silenciosamente uma nova página.
Conteúdo vazio é rejeitado — remover uma página é trabalho do delete_page.
dryRun: true informa as contagens de linhas antes/depois e pré-visualiza sem tocar na página.

Quando você executa várias instâncias deste servidor para projetos diferentes, defina a variável em cada instância que deve ter permissão para excluir:

{
  "mcpServers": {
    "cosense-notes": {
      "command": "npx",
      "args": ["-y", "scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "notes",
        "COSENSE_SID": "s:your-session-id",
        "COSENSE_TOOL_SUFFIX": "notes",
        "COSENSE_ENABLE_DELETE": "true"
      }
    },
    "cosense-archive": {
      "command": "npx",
      "args": ["-y", "scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "archive",
        "COSENSE_SID": "s:your-session-id",
        "COSENSE_TOOL_SUFFIX": "archive"
      }
    }
  }
}

Aqui, a instância notes expõe delete_page_notes, enquanto a instância archive não expõe nenhuma ferramenta de exclusão.

Observe que insert_lines e edit_lines se comportam de maneira diferente quando a linha alvo está ausente. insert_lines anexa ao final da página, porque "adicionar este texto em algum lugar" ainda tem um resultado razoável. edit_lines retorna um erro e deixa a página intocada, porque "substituir esta linha específica" não tem fallback significativo — anexar a substituição produziria silenciosamente uma página que o chamador nunca pediu.

Início Rápido

Extensão de Desktop (.mcpb) — Mais Fácil

Baixe scrapbox-cosense-mcp.mcpb de GitHub Releases
Clique duas vezes — o Claude Desktop abre um diálogo de instalação
Digite o nome do seu projeto (e o ID de Sessão para projetos privados)

Plugin Claude Code

Adicione o marketplace:

/plugin marketplace add worldnine/scrapbox-cosense-mcp

Instale o plugin:
```
/plugin install scrapbox-cosense@worldnine-scrapbox-cosense-mcp
```
Instala globalmente por padrão. Use --scope project ou --scope local para outros escopos.
Defina as variáveis de ambiente no seu arquivo de configurações:
```
{
  "env": {
    "COSENSE_PROJECT_NAME": "your_project_name",
    "COSENSE_SID": "your_sid"
  }
}
```
Arquivo Escopo
~/.claude/settings.json Todos os projetos (global)
.claude/settings.local.json Apenas este projeto (ignorado pelo git)

Arquivo	Escopo
`~/.claude/settings.json`	Todos os projetos (global)
`.claude/settings.local.json`	Apenas este projeto (ignorado pelo git)

O plugin inclui configuração do servidor MCP e uma habilidade /cosense para operações de CLI.

Claude Code (Configuração Manual do MCP)

Se você preferir configuração manual em vez do plugin:

claude mcp add scrapbox-cosense-mcp \
  -e COSENSE_PROJECT_NAME=your_project \
  -e COSENSE_SID=your_sid \
  -- npx -y scrapbox-cosense-mcp

Claude Desktop / Outros Clientes MCP

Adicione ao seu arquivo de configuração:

Cliente	Arquivo de Configuração
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%/Claude/claude_desktop_config.json`
Cursor	`.cursor/mcp.json` (raiz do projeto)
Windsurf	`~/.codeium/windsurf/mcp_config.json`

{
  "mcpServers": {
    "scrapbox-cosense-mcp": {
      "command": "npx",
      "args": ["-y", "scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "your_project_name",
        "COSENSE_SID": "your_sid"
      }
    }
  }
}

Compilar a partir do Código-Fonte

git clone https://github.com/worldnine/scrapbox-cosense-mcp.git
cd scrapbox-cosense-mcp
npm install && npm run build

Configuração

Obrigatório

Variável	Descrição
`COSENSE_PROJECT_NAME`	Nome do seu projeto Scrapbox/Cosense
`COSENSE_SID`	ID de Sessão (cookie `connect.sid`) para projetos privados — Como obtê-lo

Opcional

Variável	Padrão	Descrição
`API_DOMAIN`	`scrapbox.io`	Domínio da API
`SERVICE_LABEL`	`cosense (scrapbox)`	Nome de exibição nas descrições das ferramentas
`COSENSE_PAGE_LIMIT`	`100`	Limite inicial de busca de páginas (1–1000)
`COSENSE_SORT_METHOD`	`updated`	Ordenação inicial: atualizado, criado, acessado, vinculado, visualizações, título
`COSENSE_TOOL_SUFFIX`	—	Sufixo do nome da ferramenta para múltiplas instâncias (ex.: `main` → `get_page_main`)
`COSENSE_CONVERT_NUMBERED_LISTS`	`false`	Converter listas numeradas em listas com marcadores na conversão Markdown
`COSENSE_EXCLUDE_PINNED`	`false`	Excluir páginas fixadas da lista inicial de recursos
`COSENSE_ENABLE_DELETE`	`false`	Registrar as ferramentas `delete_page` e `rewrite_page` (e os comandos CLI `delete` / `rewrite`). Sem isso, nenhum está disponível
`COSENSE_PROJECT_ALLOW_LIST`	—	Nomes de projetos separados por vírgula que `projectName` / `--project` podem alvo. `COSENSE_PROJECT_NAME` é sempre permitido. Não definido significa sem restrição; definido para um valor vazio significa apenas o projeto padrão

Uso via CLI

O mesmo binário também funciona como uma CLI autônoma:

scrapbox-cosense-mcp get "Page Title"
scrapbox-cosense-mcp search "keyword"
scrapbox-cosense-mcp list --sort=updated --limit=20
scrapbox-cosense-mcp create "New Page" --body="Markdown content"
scrapbox-cosense-mcp insert "Page" --after="target line" --text="new text"
scrapbox-cosense-mcp edit "Page" --target="old line" --text="new text"
scrapbox-cosense-mcp delete-lines "Page" --target="old line"
scrapbox-cosense-mcp delete "Page" --dry-run   # needs COSENSE_ENABLE_DELETE=true
scrapbox-cosense-mcp rewrite "Page" --body="new content" --dry-run   # needs COSENSE_ENABLE_DELETE=true
scrapbox-cosense-mcp url "Page Title"

Flag	Descrição
`--compact`	Saída compacta eficiente em tokens (recomendado para agentes de IA)
`--project=NAME`	Substituir nome do projeto
`--json`	Saída como JSON
`--help`	Mostrar ajuda (suporta `<command> --help` para detalhes)

Múltiplos Projetos

Todas as ferramentas aceitam um parâmetro opcional projectName para alvo um projeto diferente de um único servidor. Para múltiplos projetos privados com credenciais diferentes, execute instâncias separadas do servidor com COSENSE_TOOL_SUFFIX.

Para limitar quais projetos um agente pode alcançar, defina COSENSE_PROJECT_ALLOW_LIST (separado por vírgulas). Solicitações nomeando qualquer outro projeto são rejeitadas antes de qualquer chamada de API, e o erro lista os projetos permitidos. A correspondência diferencia maiúsculas de minúsculas.

Veja docs/multiple-projects.md para exemplos detalhados de configuração.

Desenvolvimento

Comando	Descrição
`npm run build`	Compilar (TypeScript → JavaScript)
`npm run watch`	Recompilação automática durante o desenvolvimento
`npm test`	Executar suíte de testes
`npm run lint`	Executar ESLint
`npm run inspector`	Depurar com MCP Inspector

Contribuindo

Crie um branch de funcionalidade a partir de main
Adicione testes para suas alterações
Execute npm run lint && npm test
Crie um pull request — o CI é executado automaticamente

Licença

MIT

Scrapbox/CoSense

Documentação