Scrapbox/CoSense

Un servidor para la plataforma Scrapbox/CoSense que permite recuperar, listar, buscar y crear páginas.

Documentación

scrapbox-cosense-mcp

Resumen

Servidor MCP para Cosense (anteriormente Scrapbox).

Herramienta	Descripción	Autenticación requerida
`get_page`	Obtener contenido de página, metadatos y enlaces	Para proyectos privados
`list_pages`	Explorar páginas con ordenación y paginación (máx. 1000)	Para proyectos privados
`search_pages`	Búsqueda de texto completo con resaltado de palabras clave (máx. 100 resultados)	Para proyectos privados
`create_page`	Crear una página mediante la API WebSocket con cuerpo Markdown/Scrapbox	Sí
`get_page_url`	Generar URL directa para una página	No
`insert_lines`	Insertar texto después de una línea especificada en una página	Sí
`edit_lines`	Reemplazar línea(s) con coincidencia exacta, incluido un bloque de varias líneas (primera coincidencia, o todas con `matchAll`)	Sí
`delete_lines`	Eliminar línea(s) con coincidencia exacta, incluido un bloque de varias líneas (primera coincidencia, o todas con `matchAll`)	Sí
`delete_page`	Eliminar una página vaciando cada línea — opcional, ver más abajo	Sí
`rewrite_page`	Reemplazar el contenido completo de una página — opcional, ver más abajo	Sí
`get_smart_context`	Obtener una página y sus páginas enlazadas (1 salto/2 saltos) en formato optimizado para IA	Sí

create_page, insert_lines, edit_lines y rewrite_page admiten un parámetro format ("markdown" o "scrapbox") para controlar la conversión de contenido.

edit_lines reemplaza solo la primera línea coincidente de forma predeterminada. Establezca matchAll: true para reemplazar cada aparición. El valor predeterminado es deliberadamente conservador: una línea como un marcador de viñeta o una línea en blanco puede repetirse muchas veces en una página, y reemplazarlas todas a la vez rara vez es lo que el llamador pretendía.

targetLineText puede contener saltos de línea para coincidir con un bloque contiguo de líneas. El bloque se reemplaza como un todo, por lo que n líneas pueden convertirse en m líneas (por ejemplo, colapsando varias líneas en una). Las coincidencias de bloque con matchAll: true no se superponen.

delete_lines utiliza la misma semántica de coincidencia exacta (y de bloque) pero elimina las líneas coincidentes en lugar de reemplazarlas. Se niega a eliminar la línea de título (la primera línea), porque eso renombraría o eliminaría la página en sí — use delete_page para eso.

`delete_page` y `rewrite_page` son opcionales

delete_page y rewrite_page no se registran a menos que COSENSE_ENABLE_DELETE=true esté establecido. Sin él, ninguna de las dos herramientas aparece en la lista de herramientas, por lo que un agente no puede llamarlas ni siquiera por error. Este servidor a menudo se agrega a una configuración MCP compartida, por lo que la destrucción de páginas completas se expone solo a quienes la activan deliberadamente.

El razonamiento: insert_lines, edit_lines y delete_lines requieren una coincidencia exacta, lo cual solo es posible si el llamador realmente ha leído la página — solo pueden destruir líneas que ya conocen. delete_page y rewrite_page actúan sobre la página completa independientemente de si el llamador la ha leído, por lo que obtienen una puerta de activación separada.

delete_page vacía cada una de las líneas de una página, y Cosense elimina una página una vez que todas sus líneas están vacías. No hay deshacer. Se incorporan dos protecciones adicionales:

La página debe existir. Una página inexistente devuelve un error en lugar de un éxito silencioso. (La API REST devuelve una línea de título incluso para una página que nunca se creó, por lo que la verificación observa persistent, de la misma manera que lo hace create_page).
dryRun: true informa cuántas líneas se eliminarían y muestra las primeras cinco, sin tocar la página.

`COSENSE_PROJECT_ALLOW_LIST` limita los proyectos accesibles

Cada herramienta acepta una anulación de projectName, que es cómo un servidor atiende varios proyectos. Un ID de sesión a menudo alcanza más proyectos que el predeterminado, por lo que sin un límite, un agente que nombre el proyecto incorrecto puede leer o escribir allí. COSENSE_PROJECT_ALLOW_LIST es la valla opcional: cuando se establece, solo se aceptan los proyectos enumerados y COSENSE_PROJECT_NAME, y cualquier otra cosa falla antes de que se envíe una solicitud. Los nombres coinciden exactamente, incluido el uso de mayúsculas, por lo que una variante ortográfica no puede pasar. Establecer la variable a un valor vacío restringe al proyecto predeterminado únicamente. Sin establecer, se mantiene el comportamiento antiguo sin restricciones.

rewrite_page reemplaza el contenido completo de una página (el título se conserva como la primera línea). Tiene las mismas protecciones, más dos propias:

La página debe existir — la verificación de persistent está invertida en relación con create_page, por lo que un error tipográfico no puede crear silenciosamente una página nueva.
El contenido vacío se rechaza — eliminar una página es trabajo de delete_page.
dryRun: true informa los recuentos de líneas antes/después y previsualiza sin tocar la página.

Cuando ejecute varias instancias de este servidor para diferentes proyectos, establezca la variable en cada instancia a la que se le deba permitir eliminar:

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

Aquí, la instancia de notes expone delete_page_notes, mientras que la instancia de archive no expone ninguna herramienta de eliminación.

Tenga en cuenta que insert_lines y edit_lines se comportan de manera diferente cuando la línea objetivo está ausente. insert_lines agrega al final de la página, porque "agregar este texto en algún lugar" aún tiene un resultado razonable. edit_lines devuelve un error y deja la página intacta, porque "reemplazar esta línea específica" no tiene una alternativa significativa — agregar el reemplazo produciría silenciosamente una página que el llamador nunca pidió.

Inicio rápido

Extensión de escritorio (.mcpb) — La más fácil

Descargue scrapbox-cosense-mcp.mcpb desde GitHub Releases
Haga doble clic — Claude Desktop abre un diálogo de instalación
Ingrese su nombre de proyecto (y el ID de sesión para proyectos privados)

Plugin de Claude Code

Agregue el marketplace:

/plugin marketplace add worldnine/scrapbox-cosense-mcp

Instale el plugin:
```
/plugin install scrapbox-cosense@worldnine-scrapbox-cosense-mcp
```
Se instala globalmente de forma predeterminada. Use --scope project o --scope local para otros ámbitos.
Establezca las variables de entorno en su archivo de configuración:
```
{
  "env": {
    "COSENSE_PROJECT_NAME": "your_project_name",
    "COSENSE_SID": "your_sid"
  }
}
```
Archivo Ámbito
~/.claude/settings.json Todos los proyectos (global)
.claude/settings.local.json Solo este proyecto (ignorado por git)

Archivo	Ámbito
`~/.claude/settings.json`	Todos los proyectos (global)
`.claude/settings.local.json`	Solo este proyecto (ignorado por git)

El plugin incluye la configuración del servidor MCP y una habilidad de /cosense para operaciones CLI.

Claude Code (Configuración MCP manual)

Si prefiere la configuración manual en lugar del 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 / Otros clientes MCP

Agregue a su archivo de configuración:

Cliente	Archivo de configuración
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%/Claude/claude_desktop_config.json`
Cursor	`.cursor/mcp.json` (raíz del proyecto)
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 desde el código fuente

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

Configuración

Requerido

Variable	Descripción
`COSENSE_PROJECT_NAME`	Su nombre de proyecto de Scrapbox/Cosense
`COSENSE_SID`	ID de sesión (cookie `connect.sid`) para proyectos privados — Cómo obtenerlo

Opcional

Variable	Predeterminado	Descripción
`API_DOMAIN`	`scrapbox.io`	Dominio de la API
`SERVICE_LABEL`	`cosense (scrapbox)`	Nombre para mostrar en las descripciones de herramientas
`COSENSE_PAGE_LIMIT`	`100`	Límite inicial de obtención de páginas (1–1000)
`COSENSE_SORT_METHOD`	`updated`	Ordenación inicial: actualizado, creado, accedido, enlazado, vistas, título
`COSENSE_TOOL_SUFFIX`	—	Sufijo de nombre de herramienta para múltiples instancias (p. ej., `main` → `get_page_main`)
`COSENSE_CONVERT_NUMBERED_LISTS`	`false`	Convertir listas numeradas en listas con viñetas en la conversión de Markdown
`COSENSE_EXCLUDE_PINNED`	`false`	Excluir páginas fijadas de la lista inicial de recursos
`COSENSE_ENABLE_DELETE`	`false`	Registrar las herramientas `delete_page` y `rewrite_page` (y los comandos CLI `delete` / `rewrite`). Sin él, ninguna está disponible
`COSENSE_PROJECT_ALLOW_LIST`	—	Nombres de proyectos separados por comas a los que `projectName` / `--project` pueden apuntar. `COSENSE_PROJECT_NAME` siempre está permitido. Sin establecer significa sin restricción; establecido a un valor vacío significa solo el proyecto predeterminado

Uso de CLI

El mismo binario también funciona como CLI independiente:

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"

Indicador	Descripción
`--compact`	Salida compacta eficiente en tokens (recomendada para agentes de IA)
`--project=NAME`	Anular el nombre del proyecto
`--json`	Salida como JSON
`--help`	Mostrar ayuda (admite `<command> --help` para detalles)

Múltiples proyectos

Todas las herramientas aceptan un parámetro opcional de projectName para apuntar a un proyecto diferente desde un solo servidor. Para múltiples proyectos privados con diferentes credenciales, ejecute instancias de servidor separadas con COSENSE_TOOL_SUFFIX.

Para limitar a qué proyectos puede acceder un agente, establezca COSENSE_PROJECT_ALLOW_LIST (separados por comas). Las solicitudes que nombren cualquier otro proyecto se rechazan antes de cualquier llamada a la API, y el error enumera los proyectos permitidos. La coincidencia distingue entre mayúsculas y minúsculas.

Consulte docs/multiple-projects.md para ejemplos detallados de configuración.

Desarrollo

Comando	Descripción
`npm run build`	Compilar (TypeScript → JavaScript)
`npm run watch`	Recompilación automática durante el desarrollo
`npm test`	Ejecutar la suite de pruebas
`npm run lint`	Ejecutar ESLint
`npm run inspector`	Depurar con MCP Inspector

Contribuciones

Cree una rama de características desde main
Agregue pruebas para sus cambios
Ejecute npm run lint && npm test
Cree una solicitud de extracción — CI se ejecuta automáticamente

Licencia

MIT

Scrapbox/CoSense

Documentación