scrapbox-cosense-mcp-editable: Instructions file for Claude Code

CLAUDE.md

MCP server for Cosense (Scrapbox). Also works as a CLI.

Commands

npm run build        # TypeScript → JavaScript (uses tsconfig.build.json)
npm run watch        # Auto-rebuild during development
npm run test         # Run Jest tests
npm run lint         # ESLint (console.log triggers warning)
npm run inspector    # Debug with MCP Inspector

Architecture

Tools (7)

Tool	Description	Auth
get_page	Retrieve page content, metadata, and links	-
list_pages	List pages with sorting and pagination (max 1000)	-
search_pages	Keyword search (API limit: 100 results)	-
create_page	Create new page. Rejects if page already exists	SID
get_page_url	Generate URL from page title	-
insert_lines	Insert text after a target line (exact match). Appends to end if not found	SID
get_smart_context	Get page + linked pages (1-hop/2-hop) in AI-optimized format	SID

CLI

All tools are also available as CLI subcommands (get, list, search, create, url, insert, context). Run scrapbox-cosense-mcp <command> --help for usage. Key flags:

• --compact — Token-efficient output (85% smaller for list)
• --json — JSON output
• --project=NAME — Override project name

Skill (SKILL.md)

skills/scrapbox/SKILL.md defines a Claude Code skill that wraps the CLI. When users invoke /cosense, Claude Code reads SKILL.md and executes CLI commands via Bash. Keep SKILL.md concise — details should be discoverable via --help.

Desktop Extensions (.mcpb)

manifest.json + .mcpbignore enable Claude Desktop Extensions packaging. The .mcpb file is auto-built and attached to GitHub Releases by release-mcpb.yml. To build locally: npm install --omit=dev && npx @anthropic-ai/mcpb pack.

Directory Structure

• src/cosense.ts — Scrapbox REST API client
• src/routes/handlers/ — One handler module per tool
• src/utils/format.ts — Response formatting, stringifyError, formatError
• src/utils/sort.ts — Sorting with pinned page filtering
• src/utils/markdown-converter.ts — Markdown → Scrapbox conversion (uses md2sb)
• src/types/ — API response and MCP request/response type definitions
• src/cli.ts — CLI entry point (args → CLI mode, no args → MCP server)
• src/index.ts — Server entry point