scrapbox-cosense-mcp

🚀 Scrapbox 和 Cosense 的 MCP 服务器文档

本项目提供了 Scrapbox 和 Cosense 的 MCP 服务器相关功能，可对条目进行获取、创建、更新、删除和搜索等操作，同时介绍了环境配置、API 请求格式、部署使用等内容。

🚀 快速开始

本服务器可实现对 Scrapbox 和 Cosense 条目的多种操作，如获取、创建、更新、删除和搜索等。使用前需进行环境变量配置和依赖安装。

✨ 主要特性

get 操作

• 获取单个条目：可通过指定条目的唯一标识符来检索特定条目的内容。
• 获取所有条目：能检索存储在 Scrapbox 中的所有条目。

post 操作

• 创建新条目：用户可向服务器发送新的条目数据，包括标题和可选的内容文本，并获得该条目的唯一标识符。
• 更新现有条目：支持通过指定条目的唯一标识符来更新其内容。
• 删除特定条目：可通过指定条目的唯一标识符来删除特定的条目。

search 操作

• 基本搜索：支持基于标题或内容的关键字搜索，返回匹配的所有条目的唯一标识符。
• 高级搜索：支持通过逻辑运算符（如 AND、OR、NOT）组合多个关键字进行复杂查询，进一步缩小结果范围。

📦 安装指南

安装依赖项

运行以下命令安装所需的 npm 包：

npm install

构建服务器

构建生产环境版本的服务器：

npm run build

开发模式下的自动重载

在开发过程中，可以启用自动重载功能以提高效率：

npm run watch

💻 使用示例

基础用法

获取单个条目

{
  "operation": "get",
  "id": "string"
}

示例请求：

{
  "operation": "get",
  "id": "12345"
}

创建新条目

{
  "operation": "post",
  "title": "string",
  "content": "string (optional)"
}

示例请求：

{
  "operation": "post",
  "title": "我的新笔记",
  "content": "今天是个好天气。"
}

更新现有条目

{
  "operation": "update",
  "id": "string",
  "new_title": "string (optional)",
  "new_content": "string (optional)"
}

示例请求：

{
  "operation": "update",
  "id": "12345",
  "new_title": "更新后的笔记标题"
}

删除特定条目

{
  "operation": "delete",
  "id": "string"
}

示例请求：

{
  "operation": "delete",
  "id": "12345"
}

搜索条目

{
  "operation": "search",
  "query": "string",
  "logic": "basic" 或 "advanced"
}

示例请求：

{
  "operation": "search",
  "query": "笔记 AND 天气",
  "logic": "advanced"
}

📚 详细文档

环境变量配置

为了确保服务器的正常运行，需要在运行时设置以下环境变量： | 属性 | 详情 | |------|------| | 类型 | 字符串 | | 描述 | 指定要连接的 Scrapbox 或 Cosense 项目名称 | | 示例 | my_project |

| 属性 | 详情 | |------|------| | 类型 | 字符串 | | 描述 | Scrapbox 或 Cosense 平台提供的唯一会话标识符，用于身份验证 | | 示例 | abc123-def456-ghi789 |

API 请求格式

所有 API 请求均采用 JSON 格式，具体请求示例见“使用示例”部分。

响应格式

服务器返回的响应统一采用 JSON 格式：

成功操作

{
  "status": "success",
  "data": {
    // 具体数据根据操作类型而定
  }
}

失败操作

{
  "status": "error",
  "message": "string" // 错误信息描述
}

Claude Desktop 配置

要在 Claude Desktop 中使用此 MCP 服务器，请按照以下步骤配置：

1. 打开 Claude 的设置文件：
   • MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%/Claude/claude_desktop_config.json
2. 添加以下配置到 mcpServers 对象中：

{
  "mcp_servers": {
    "scrapbox_cosense_server": {
      "type": "custom",
      "uri": "http://localhost:3000", // 根据实际情况修改地址和端口
      "env_vars": {
        "COSENSE_PROJECT_NAME": "my_project",
        "COSENSE_SID": "abc123-def456-ghi789"
      }
    }
  }
}

🔧 技术细节

本服务器基于相关技术实现了对 Scrapbox 和 Cosense 条目的各种操作。通过设置环境变量进行项目和身份验证配置，使用 JSON 格式进行 API 请求和响应。在部署方面，使用 npm 进行依赖安装和服务器构建，同时支持开发模式下的自动重载。在 Claude Desktop 中使用时，需在配置文件中添加相应的服务器配置。

📄 故障排除

常见问题

1. 无法连接到服务器
   • 确保服务器正在运行。
   • 检查网络连接，确保没有防火墙阻止通信。
2. 认证失败
   • 核对 COSENSE_SID 是否正确。
   • 确保 COSENSE_PROJECT_NAME 与目标项目名称一致。
3. 搜索功能不正常
   • 确认逻辑运算符的使用是否符合预期。
   • 检查关键字拼写，避免因大小写或符号错误导致匹配失败。

联系支持

如果遇到无法解决的问题，请联系我们的技术支持团队：

• 邮箱：support@scrapbox.com
• 电话：+86-123-456789