scrapbox-cosense-mcp

English | 日本語

English

MCP server for cosense/scrapbox.

Features

• get_page

  • Get page content from cosense/Scrapbox

    • Input: Page title, optional project name

    • Output: Page content, metadata, links, and editor information

• list_pages

  • Browse and list pages with flexible sorting and pagination

    • Purpose: Discover pages by recency, popularity, or alphabetically

    • Input: Sorting options, pagination, optional project name

    • Output: Page metadata and first 5 lines of content

    • Max: 1000 pages per request

    • Sorting: updated, created, accessed, linked, views, title

• search_pages

  • Search for content within pages using keywords or phrases

    • Purpose: Find pages containing specific keywords or phrases

    • Input: Search query, optional project name

    • Output: Matching pages with highlighted search terms and content snippets

    • Max: 100 results (API limitation)

    • Supports: basic search, AND search, exclude search, exact phrases

• create_page

  • Create a new page in the project with WebSocket API

    • Input: Page title, optional markdown body text, optional project name, optional createActually flag

    • Output: Creates the page immediately and returns success confirmation with URL

    • Note: Markdown content is converted to Scrapbox format

    • Feature: Automatically converts numbered lists to bullet lists (configurable)

    • Authentication: Requires COSENSE_SID for actual page creation

• get_page_url

  • Generate URL for a page in the project

    • Input: Page title, optional project name

    • Output: Direct URL to the specified page

• insert_lines

  • Insert text after a specified line in a page

    • Input: Page title, target line text, text to insert, optional project name

    • Output: Success message with insertion details

    • Behavior: If target line not found, text is appended to the end of the page

Installation

Basic Setup

To use with Claude Desktop, add the server configuration as follows:

For MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json For Windows: %APPDATA%/Claude/claude_desktop_config.json

Single Project Configuration:

Usage Examples

Once configured, you can use the tools in Claude:

Environment Variables

This server uses the following environment variables:

Required Environment Variables

• COSENSE_PROJECT_NAME: Project name

• COSENSE_SID: Session ID for Scrapbox/Cosense authentication (required for private projects) - See how to get this cookie

Optional Environment Variables

• API_DOMAIN: API domain (default: "scrapbox.io")

• SERVICE_LABEL: Service identifier (default: "cosense (scrapbox)")

• COSENSE_PAGE_LIMIT: Initial page fetch limit (1-1000, default: 100)

• COSENSE_SORT_METHOD: Initial page fetch order (updated/created/accessed/linked/views/title, default: updated)

• COSENSE_TOOL_SUFFIX: Tool name suffix for multiple server instances (e.g., "main" creates "get_page_main")

• COSENSE_CONVERT_NUMBERED_LISTS: Convert numbered lists to bullet lists in Markdown (true/false, default: false)

Environment Variable Behavior

• COSENSE_PROJECT_NAME: Required environment variable. Server will exit with an error if not set.

• COSENSE_SID: Required for accessing private projects. If not set, only public projects are accessible. See detailed instructions for obtaining this cookie.

• API_DOMAIN:

  • Uses "scrapbox.io" if not set

  • While unverified with domains other than "scrapbox.io" in the author's environment, this option exists in case some environments require "cosen.se"

• COSENSE_PAGE_LIMIT:

  • Uses 100 if not set

  • Uses 100 if value is invalid (non-numeric or out of range)

  • Valid range: 1-1000

• COSENSE_SORT_METHOD:

  • Uses 'updated' if not set

  • Uses 'updated' if value is invalid

  • Does not affect list_pages tool behavior (only used for initial resource fetch)

How to Get COSENSE_SID Cookie

For accessing private Scrapbox projects, you need to obtain the connect.sid cookie from your browser. Follow these steps:

1. Navigate to your Scrapbox project

   • Open your browser and go to https://scrapbox.io/YOUR_PROJECT_NAME

   • Replace YOUR_PROJECT_NAME with your actual project name

2. Log in to Scrapbox

   • Make sure you're logged in to your Scrapbox account

   • Verify you can access your private project

3. Open Developer Tools

   • Windows/Linux: Press F12 or Ctrl+Shift+I

   • macOS: Press Cmd+Option+I

   • Alternative: Right-click on the page and select "Inspect" or "Inspect Element"

4. Navigate to Cookies

   • In the Developer Tools, look for the "Application" tab (Chrome/Edge) or "Storage" tab (Firefox)

   • In the left sidebar, expand "Cookies"

   • Click on https://scrapbox.io

5. Find and copy the connect.sid cookie

   • Look for a cookie named connect.sid

   • Click on it to see its value

   • Important: The browser displays the URL-encoded value, but you need to use the decoded value

   • Browser shows: s%3Axxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

   • You should use: s:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (note the : after s)

6. Set the environment variable

   • Use the decoded value (with : instead of %3A) as your COSENSE_SID environment variable

   • Correct format: COSENSE_SID=s:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

   • Incorrect format: COSENSE_SID=s%3Axxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Important Notes:

• Keep your connect.sid cookie value secure and never share it publicly

• The cookie may expire after some time; you'll need to obtain a new one if authentication fails

• This cookie provides access to your private projects, so treat it like a password

Multiple Project Support (Advanced)

Method 1: Single Server with Optional Parameters

All tools support an optional projectName parameter to target different projects from a single server:

• Default behavior: Uses COSENSE_PROJECT_NAME environment variable when no project is specified

• Multi-project usage: Specify projectName parameter to access different projects

• Backward compatibility: Existing configurations work unchanged

Usage Examples:

Important Limitations:

This approach works best with public projects or projects that share the same authentication. For multiple private projects with different access credentials, use Method 2 below.

Method 2: Multiple MCP Server Instances (Recommended for Private Projects)

For best user experience with multiple private projects, run separate MCP server instances for each project:

Key Configuration Points:

• COSENSE_PROJECT_NAME: The actual project name used in API calls (e.g., scrapbox.io/main-project)

• SERVICE_LABEL: Display name shown in tool descriptions (e.g., "Create page on Main Scrapbox")

• COSENSE_TOOL_SUFFIX: Creates unique tool names like get_page_main and get_page_team

• Different service names: Using "Scrapbox" and "Cosense" helps distinguish between projects

This creates tools like get_page_main, list_pages_main, get_page_team, list_pages_team, allowing LLMs to automatically select the appropriate project.

Development

Install dependencies:

Build the server:

Auto-rebuild during development:

Run tests:

Run linting:

Quality Management

This project includes automated quality checks to ensure code reliability:

• ESLint: TypeScript-aware linting with console.log warnings

• GitHub Actions: Automated CI/CD pipeline for pull requests

• Branch Protection: Main branch requires PR and passing checks

• Test Suite: 142+ tests covering all functionality

Contributing Guidelines

1. Create a feature branch from main

2. Make your changes with appropriate tests

3. Run npm run lint and npm test locally

4. Create a pull request

5. CI will automatically run quality checks

6. Merge only after all checks pass

The quality management system prevents debug logs and broken code from reaching production.

Debugging

Since MCP servers communicate via stdio, debugging can be challenging. This server includes comprehensive debug logging to help troubleshoot issues.

Debug Logs

The server outputs detailed debug information to help identify configuration and API issues:

• Server Configuration: Project name, tool suffix, SID presence, limits

• Tool Generation: List of generated tools with their names

• Tool Calls: Requested vs normalized tool names, arguments

• API Requests: URLs, project names, authentication status

• API Errors: Detailed error information with context

Using MCP Inspector

Using MCP Inspector is recommended for interactive debugging:

The Inspector provides a URL to access debugging tools in the browser.

Troubleshooting Multiple Servers

When running multiple server instances, check the debug logs for:

1. Tool Name Conflicts: Ensure COSENSE_TOOL_SUFFIX is set differently for each server

2. API Access: Verify SID authentication works for each project

3. Project Names: Confirm project names are correctly configured

Related MCP server: MCP File System Server

日本語

cosense/scrapbox 用のMCPサーバーです。

機能

• get_page

  • cosense/Scrapboxからページコンテンツを取得

    • 入力: ページタイトル、オプションのプロジェクト名

    • 出力: ページコンテンツ、メタデータ、リンク、編集者の情報

• list_pages

  • 柔軟なソートとページネーションによるページ一覧の閲覧

    • 用途: 最新性、人気度、アルファベット順でページを発見

    • 入力: ソートオプション、ページネーション、オプションのプロジェクト名

    • 出力: ページのメタデータと冒頭5行の内容

    • 最大: 1リクエスト当たり1000件

    • ソート: updated, created, accessed, linked, views, title

• search_pages

  • キーワードやフレーズを使用したページ内コンテンツの検索

    • 用途: 特定のキーワードやフレーズを含むページを発見

    • 入力: 検索クエリ、オプションのプロジェクト名

    • 出力: マッチしたページとハイライトされた検索語句、コンテンツスニペット

    • 最大: 100件（API制限）

    • サポート: 基本検索、AND検索、除外検索、完全一致フレーズ

• create_page

  • WebSocket APIを使ってプロジェクトに新しいページを作成

    • 入力: ページタイトル、オプションのマークダウン本文テキスト、オプションのプロジェクト名、オプションのcreateActuallyフラグ

    • 出力: ページを即座に作成し、成功確認とURLを返す

    • 注意: マークダウンコンテンツはScrapbox形式に変換されます

    • 機能: 数字付きリストを自動的に箇条書きに変換（設定可能）

    • 認証: 実際のページ作成にはCOSENSE_SIDが必要

• get_page_url

  • プロジェクト内のページのURLを生成

    • 入力: ページタイトル、オプションのプロジェクト名

    • 出力: 指定されたページへの直接URL

• insert_lines

  • ページの指定した行の後にテキストを挿入

    • 入力: ページタイトル、対象行のテキスト、挿入するテキスト、オプションのプロジェクト名

    • 出力: 挿入の詳細を含む成功メッセージ

    • 動作: 対象行が見つからない場合は、ページの末尾にテキストが追加されます

インストール方法

基本設定

Claude Desktopで使用するには、以下のようにサーバー設定を追加してください:

MacOSの場合: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windowsの場合: %APPDATA%/Claude/claude_desktop_config.json

単一プロジェクト設定:

使用例

設定完了後、Claudeで以下のようにツールを使用できます：

環境変数

このサーバーは以下の環境変数を使用します：

必須の環境変数

• COSENSE_PROJECT_NAME: プロジェクト名

• COSENSE_SID: Scrapbox/Cosenseの認証用セッションID（プライベートプロジェクトの場合は必須） - Cookieの取得方法

オプションの環境変数

• API_DOMAIN: APIドメイン（デフォルト: "scrapbox.io"）

• SERVICE_LABEL: サービスの識別名（デフォルト: "cosense (scrapbox)"）

• COSENSE_PAGE_LIMIT: 初期取得時のページ数（1-1000、デフォルト: 100）

• COSENSE_SORT_METHOD: 初期取得時の取得ページ順（updated/created/accessed/linked/views/title、デフォルト: updated）

• COSENSE_TOOL_SUFFIX: 複数サーバーインスタンス用のツール名サフィックス（例："main"で"get_page_main"が作成されます）

環境変数の挙動について

• COSENSE_PROJECT_NAME: 必須の環境変数です。未設定の場合、サーバーは起動時にエラーで終了します。

• COSENSE_SID: プライベートプロジェクトへのアクセスに必要です。未設定の場合、パブリックプロジェクトのみアクセス可能です。詳細な取得手順をご確認ください。

• API_DOMAIN:

  • 未設定時は"scrapbox.io"を使用

  • 作者の環境では"scrapbox.io"以外の値は未検証ですが、"cosen.se"でないと動作しない環境が存在する可能性があるため念のためのオプションです。

• COSENSE_PAGE_LIMIT:

  • 未設定時は100を使用

  • 無効な値（数値以外や範囲外）の場合は100を使用

  • 有効範囲: 1-1000

• COSENSE_SORT_METHOD:

  • 未設定時は'updated'を使用

  • 無効な値の場合は'updated'を使用

  • list_pagesツールの動作には影響しません（初期リソース取得時のみ使用）

COSENSE_SID Cookieの取得方法

プライベートなScrapboxプロジェクトにアクセスするには、ブラウザから connect.sid Cookieを取得する必要があります。以下の手順に従ってください：

1. Scrapboxプロジェクトにアクセス

   • ブラウザで https://scrapbox.io/あなたのプロジェクト名 を開きます

   • あなたのプロジェクト名 を実際のプロジェクト名に置き換えてください

2. Scrapboxにログイン

   • Scrapboxアカウントにログインしていることを確認してください

   • プライベートプロジェクトにアクセスできることを確認してください

3. 開発者ツールを開く

   • Windows/Linux: F12 キーまたは Ctrl+Shift+I を押します

   • macOS: Cmd+Option+I を押します

   • 別の方法: ページ上で右クリックして「検証」または「要素を調査」を選択

4. Cookieを確認

   • 開発者ツールで 「Application」 タブ（Chrome/Edge）または 「ストレージ」 タブ（Firefox）を探します

   • 左側のサイドバーで 「Cookies」 を展開します

   • https://scrapbox.io をクリックします

5. connect.sid Cookieを見つけてコピー

   • connect.sid という名前のCookieを探します

   • それをクリックして値を確認します

   • 重要: ブラウザはURLエンコードされた値を表示しますが、実際にはデコードされた値を使用する必要があります

   • ブラウザ表示: s%3Axxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

   • 使用すべき値: s:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx（sの後は:です）

6. 環境変数に設定

   • デコードされた値（%3Aの代わりに:）を COSENSE_SID 環境変数として使用します

   • 正しい形式: COSENSE_SID=s:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

   • 間違った形式: COSENSE_SID=s%3Axxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

重要な注意事項:

• connect.sid Cookieの値は機密情報のため、安全に管理し、公開しないでください

• Cookieは時間が経つと期限切れになる場合があります。認証エラーが発生した場合は新しいCookieを取得してください

• このCookieはプライベートプロジェクトへのアクセス権を提供するため、パスワードと同様に扱ってください

複数プロジェクト対応（高度な機能）

方法1: オプショナルパラメータを使用した単一サーバー

すべてのツールで、単一サーバーから異なるプロジェクトを対象とするオプションのprojectNameパラメータをサポートしています：

• デフォルト動作: プロジェクトが指定されていない場合はCOSENSE_PROJECT_NAME環境変数を使用

• 複数プロジェクト使用: projectNameパラメータを指定して異なるプロジェクトにアクセス

• 後方互換性: 既存の設定は変更なしで動作

使用例:

重要な制限事項:

この方法は、パブリックプロジェクトや同じ認証情報を共有するプロジェクトで最も効果的です。異なるアクセス認証情報を持つ複数のプライベートプロジェクトには、以下の方法2をご利用ください。

方法2: 複数MCPサーバーインスタンス（プライベートプロジェクト推奨）

複数のプライベートプロジェクトで最良のユーザー体験を得るには、プロジェクトごとに別々のMCPサーバーインスタンスを実行します：

設定のポイント:

• COSENSE_PROJECT_NAME: API呼び出しで使用される実際のプロジェクト名（例: scrapbox.io/main-project）

• SERVICE_LABEL: ツール説明で表示される名前（例: 「Main Scrapboxでページを作成」）

• COSENSE_TOOL_SUFFIX: get_page_main や get_page_team のような固有のツール名を作成

• サービス名の使い分け: 「Scrapbox」と「Cosense」を使い分けることでプロジェクトを区別

これにより get_page_main、list_pages_main、get_page_team、list_pages_team のようなツールが作成され、LLMが自動的に適切なプロジェクトを選択できるようになります。

開発方法

依存関係のインストール:

サーバーのビルド:

開発時の自動リビルド:

テストの実行:

リンティングの実行:

品質管理

このプロジェクトでは、コードの信頼性を確保するための自動品質チェックが導入されています：

• ESLint: TypeScript対応のリンティング、console.log使用時の警告

• GitHub Actions: プルリクエスト用の自動CI/CDパイプライン

• ブランチ保護: mainブランチへはPRとチェック通過が必須

• テストスイート: 142+のテストで全機能をカバー

貢献ガイドライン

1. mainから機能ブランチを作成

2. 適切なテストと共に変更を実装

3. ローカルで npm run lint と npm test を実行

4. プルリクエストを作成

5. CIが自動的に品質チェックを実行

6. 全チェック通過後にマージ

この品質管理システムにより、デバッグログや壊れたコードの本番環境への混入を防げます。

デバッグ方法

MCPサーバーはstdioを介して通信を行うため、デバッグが難しい場合があります。MCP Inspectorの使用を推奨します。以下のコマンドで実行できます：

InspectorはブラウザでデバッグツールにアクセスするためのURLを提供します。