废料箱感知mcp服务器

Name: 废料箱感知mcp服务器
Author: worldnine

作者：worldnine33 星标更新：2025-07-12

安装使用来源：spider==github.com

项目介绍

scrapbox-cosense-mcp

English | 日语

英文

用于 cosense/scrapbox 的 MCP 服务器。

功能

get_page
- 从 cosense/Scrapbox 获取页面内容
  - 输入：页面标题，可选项目名称
  - 输出：页面内容、元数据、链接和编辑器信息
list_pages
- 浏览并列出页面，支持灵活排序和分页
  - 目的：按最近更新、受欢迎程度或字母顺序发现页面
  - 输入：排序选项、分页、可选项目名称
  - 输出：页面元数据和内容的前五行
  - 最大值：每次请求最多 1000 个页面
  - 排序：更新时间、创建时间、访问时间、链接数、浏览次数、标题
search_pages
- 使用关键词或短语搜索页面内容
  - 目的：查找包含特定关键词或短语的页面
  - 输入：搜索查询，可选项目名称
  - 输出：匹配的页面及其高亮显示的搜索词和内容片段
  - 最大值：100 条结果（API 限制）
  - 支持：基本搜索、AND 搜索、排除搜索、精确短语
create_page
- 使用 WebSocket API 在项目中创建新页面
  - 输入：页面标题，可选 Markdown 正文，可选项目名称，可选 createActually 标志
  - 输出：立即创建页面并返回成功确认及 URL
  - 注意：Markdown 内容转换为 Scrapbox 格式
  - 功能：自动将编号列表转换为项目符号列表（可配置）
  - 认证：实际创建页面需要 COSENSE_SID
get_page_url
- 生成项目中页面的 URL
  - 输入：页面标题，可选项目名称
  - 输出：指向指定页面的直接 URL
insert_lines
- 在页面指定行之后插入文本
  - 输入：页面标题，目标行文本，要插入的文本，可选项目名称
  - 输出：包含插入详情的成功消息
  - 行为：如果未找到目标行，则将文本追加到页面末尾

安装

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

基本设置

要在 Claude Desktop 中使用，请添加以下服务器配置：

对于 MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json 对于 Windows：%APPDATA%/Claude/claude_desktop_config.json

单个项目配置：

{
  "mcpServers": {
    "scrapbox-cosense-mcp": {
      "command": "npx",
      "args": ["github:worldnine/scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "your_project_name",
        "COSENSE_SID": "your_sid", // 私有项目时必需
        "COSENSE_PAGE_LIMIT": "25", // 可选（默认：100）
        "COSENSE_SORT_METHOD": "created", // 可选（默认："updated"）
        "SERVICE_LABEL": "scrapbox(cosense)" // 可选（默认："cosense(scrapbox)"）
      }
    }
  }
}

使用示例

配置完成后，您可以在 Claude 中使用这些工具：

# 获取特定页面
请使用 get_page 获取页面“会议记录”的内容。

# 列出最近的页面
请使用 list_pages 列出最近更新的 10 个页面。

# 搜索内容
请使用 search_pages 搜索包含“JavaScript 教程”的页面。

# 创建新页面
请使用 create_page 创建一个标题为“今天的学习”的新页面。

# 获取页面 URL
请使用 get_page_url 获取页面“项目计划”的 URL。

环境变量

此服务器使用以下环境变量：

必需的环境变量

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：初始页面获取顺序（更新时间/创建时间/访问时间/链接数/浏览次数/标题，默认：更新时间）
COSENSE_TOOL_SUFFIX：多服务器实例的工具名称后缀（例如，“main”创建“get_page_main”）
COSENSE_CONVERT_NUMBERED_LISTS：在 Markdown 中将编号列表转换为项目符号列表（真/假，默认：假）

环境变量行为

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。请按照以下步骤操作：

导航至您的 Scrapbox 项目
- 打开浏览器并前往 https://scrapbox.io/YOUR_PROJECT_NAME
- 将 YOUR_PROJECT_NAME 替换为您实际的项目名称
登录 Scrapbox
- 确保已登录您的 Scrapbox 账户
- 验证您可以访问您的私有项目
打开开发者工具
- Windows/Linux：按 F12 或 Ctrl+Shift+I
- macOS：按 Cmd+Option+I
- 另一种方式：右键点击页面并选择“检查”或“检查元素”
导航至 Cookies
- 在开发者工具中，查找 “Application” 标签（Chrome/Edge）或 “Storage” 标签（Firefox）
- 在左侧边栏中展开 “Cookies”
- 点击 https://scrapbox.io
找到并复制 connect.sid cookie
- 查找名为 connect.sid 的 cookie
- 点击它以查看其值
- 重要：浏览器显示的是 URL 编码值，但您需要使用 解码值
- 浏览器显示：s%3Axxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- 您应使用：s:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx（注意 s 后面的 :）
设置环境变量
- 使用 解码值（用 : 替代 %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 参数来访问不同项目
向后兼容性：现有配置无需更改即可继续工作

使用示例：

# 从默认项目获取页面
请使用 get_page 获取页面“会议记录”的内容。

# 从特定项目获取页面
请使用 get_page 从项目“help-ja”获取页面“使用指南”的内容。

# 在不同项目中搜索
请使用 search_pages 在项目“developer-docs”中搜索包含“API 文档”的页面。

# 在特定项目中创建页面
请使用 create_page 在项目“team-updates”中创建一个标题为“周报”的新页面。

重要限制：

这种方法最适合共享公共项目或具有相同认证信息的项目。对于多个具有不同访问认证信息的私有项目，请使用下面的方法 2。

方法 2：多个 MCP 服务器实例（推荐用于私有项目）

为了获得最佳用户体验，每个项目运行单独的 MCP 服务器实例：

{
  "mcpServers": {
    "main-scrapbox": {
      "command": "npx",
      "args": ["github:worldnine/scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "main-project",        // API 调用的实际项目名称
        "COSENSE_SID": "s:main_sid_here...",           // 该项目的会话 ID
        "COSENSE_TOOL_SUFFIX": "main",                 // 创建如 get_page_main 的工具名
        "SERVICE_LABEL": "Main Scrapbox"               // 工具描述中的人类可读标签
      }
    },
    "team-cosense": {
      "command": "npx",
      "args": ["github:worldnine/scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "team-workspace",      // API 调用的实际项目名称
        "COSENSE_SID": "s:team_sid_here...",           // 该项目的会话 ID
        "COSENSE_TOOL_SUFFIX": "team",                 // 创建如 get_page_team 的工具名
        "SERVICE_LABEL": "Team Cosense"                // 工具描述中的人类可读标签
      }
    }
  }
}

关键配置点：

COSENSE_PROJECT_NAME：API 调用的实际项目名称（例如 scrapbox.io/main-project）
SERVICE_LABEL：工具描述中显示的人类可读名称（例如“在主 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 自动选择适当的项目。

开发方法

安装依赖项：

npm install

构建服务器：

npm run build

开发期间自动重建：

npm run watch

运行测试：

npm test

运行代码检查：

npm run lint

质量管理

此项目引入了自动质量检查以确保代码可靠性：

ESLint：TypeScript 对应的代码检查，使用时警告 console.log
GitHub Actions：拉取请求的自动 CI/CD 管道
分支保护：主分支需要 PR 并且检查通过
测试套件：142+ 测试覆盖所有功能

贡献指南

从主分支创建功能分支
实现带有适当测试的更改
本地执行 npm run lint 和 npm test
创建拉取请求
CI 自动执行质量检查
在所有检查通过后合并

此质量控制系统防止调试和损坏的代码混入主环境。

调试方法

由于 MCP 服务器通过 stdio 进行通信，调试可能会很困难。此服务器包括全面的调试日志以帮助排查问题。

调试日志

服务器输出详细的调试信息以帮助识别配置和 API 问题：

服务器配置：项目名称、工具后缀、SID 存在情况、限制
工具生成：生成的工具及其名称列表
工具调用：请求与规范化工具名称、参数
API 请求：URL、项目名称、认证状态
API 错误：带上下文的详细错误信息

使用 MCP Inspector

建议使用 MCP Inspector 进行交互式调试：

npm run inspector

Inspector 提供一个 URL 以在浏览器中访问调试工具。

多服务器实例故障排除

当运行多个服务器实例时，请检查调试日志：

工具名称冲突：确保每个服务器的 COSENSE_TOOL_SUFFIX 设置不同
API 访问：验证每个项目的 SID 认证是否正常工作
项目名称：确认项目名称配置正确

日语

cosense/scrapbox 用 MCP 服务器。

功能

get_page
- 从 cosense/Scrapbox 获取页面内容
  - 输入：页面标题，可选项目名称
  - 输出：页面内容、元数据、链接和编辑器信息
list_pages
- 浏览并列出页面，支持灵活排序和分页
  - 使用目的：按最新更新、受欢迎程度和字母顺序发现页面
  - 输入：排序、分页和可选项目名称
  - 输出：页面元数据和内容的前五行
  - 最大值：每次请求 1
  - 排序：更新时间、创建时间、访问时间、链接数、浏览次数、标题
search_pages
- 使用关键词和短语搜索页面内容
  - 使用目的：查找包含特定关键词和短语的页面
  - 输入：搜索查询，可选项目名称
  - 输出：匹配的页面及其高亮显示的搜索词和内容片段
  - 最大值：100 条（API 限制）
  - 支持：基本搜索、AND 搜索、排除搜索、精确短语
create_page
- 使用 WebSocket API 在项目中创建新页面
  - 输入：页面标题，可选 Markdown 正文，可选项目名称，可选 createActually 标志
  - 输出：立即创建页面并返回成功确认及 URL
  - Markdown 内容转换为 Scrapbox 格式
  - 功能：自动将编号列表转换为项目符号列表（可配置）
  - 认证：实际创建页面需要 COSENSE_SID
get_page_url
- 生成项目中页面的 URL
  - 输入：页面标题，可选项目名称
  - 输出：指向指定页面的直接 URL
insert_lines
- 在页面指定行之后插入文本
  - 输入：页面标题，目标行文本，要插入的文本，可选项目名称
  - 输出：包含插入详情的成功消息
  - 行为：如果未找到目标行，则将文本追加到页面末尾

安装方法

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

基本设置

要在 Claude Desktop 中使用，请添加以下服务器配置：

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

单个项目配置：

{
  "mcpServers": {
    "scrapbox-cosense-mcp": {
      "command": "npx",
      "args": ["github:worldnine/scrapbox-cosense-mcp"],
      "env": {
        "COSENSE_PROJECT_NAME": "your_project_name",
        "COSENSE_SID": "your_sid", // 私有项目时必需
        "COSENSE_PAGE_LIMIT": "25", // 可选（默认：100）
        "COSENSE_SORT_METHOD": "created", // 可选（默认："updated"）
        "SERVICE_LABEL": "scrapbox(cosense)" // 可选（