Scrapbox Cosense MCP

🚀 Scrapbox and Cosense MCP Server Documentation

This documentation provides a detailed guide on the Scrapbox and Cosense MCP server, including its features, API usage, deployment steps, configuration in Claude Desktop, and troubleshooting tips.

✨ Features

get Operations

• Retrieve a Single Entry: You can retrieve the content of a specific entry by specifying its unique identifier.
• Retrieve All Entries: You can retrieve all entries stored in Scrapbox.

post Operations

• Create a New Entry: Users can send new entry data, including a title and optional content text, to the server and obtain a unique identifier for the entry.
• Update an Existing Entry: You can update the content of an existing entry by specifying its unique identifier.
• Delete a Specific Entry: You can delete a specific entry by specifying its unique identifier.

search Operations

• Basic Search: Supports keyword search based on titles or content, returning the unique identifiers of all matching entries.
• Advanced Search: Supports complex queries by combining multiple keywords using logical operators (e.g., AND, OR, NOT) to further narrow down the results.

📚 Documentation

Environment Variable Configuration

To ensure the normal operation of the server, the following environment variables need to be set at runtime:

API Request Format

All API requests are in JSON format:

Retrieve a Single Entry

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

Example Request:

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

Create a New Entry

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

Example Request:

{
  "operation": "post",
  "title": "My New Note",
  "content": "It's a nice day today."
}

Update an Existing Entry

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

Example Request:

{
  "operation": "update",
  "id": "12345",
  "new_title": "Updated Note Title"
}

Delete a Specific Entry

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

Example Request:

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

Search Entries

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

Example Request:

{
  "operation": "search",
  "query": "Note AND Weather",
  "logic": "advanced"
}

Response Format

The server returns responses in a unified JSON format:

Successful Operation

{
  "status": "success",
  "data": {
    // Specific data depends on the operation type
  }
}

Failed Operation

{
  "status": "error",
  "message": "string" // Error message description
}

📦 Installation

Install Dependencies

Run the following command to install the required npm packages:

npm install

Build the Server

Build the server for the production environment:

npm run build

Automatic Reload in Development Mode

During development, you can enable the automatic reload feature to improve efficiency:

npm run watch

📚 Claude Desktop Configuration

To use this MCP server in Claude Desktop, follow these steps to configure it:

1. Open Claude's configuration file:

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

2. Add the following configuration to the mcpServers object:

{
  "mcp_servers": {
    "scrapbox_cosense_server": {
      "type": "custom",
      "uri": "http://localhost:3000", // Modify the address and port according to the actual situation
      "env_vars": {
        "COSENSE_PROJECT_NAME": "my_project",
        "COSENSE_SID": "abc123-def456-ghi789"
      }
    }
  }
}

🔧 Troubleshooting

Common Issues

1. Unable to Connect to the Server

   • Ensure that the server is running.
   • Check the network connection and make sure there are no firewalls blocking the communication.

2. Authentication Failure

   • Verify that the COSENSE_SID is correct.
   • Ensure that the COSENSE_PROJECT_NAME matches the target project name.

3. Search Function Not Working Properly

   • Confirm that the logical operators are used as expected.
   • Check the keyword spelling to avoid matching failures due to case or symbol errors.

Contact Support

If you encounter issues that cannot be resolved, please contact our technical support team:

• Email: support@scrapbox.com
• Phone: +86-123-456789