MCP 服务器

Convolut MCP Server

Enables seamless integration with Convolut Context Bank for AI-powered context management, search, consolidation, and export operations. Provides 11 powerful tools for creating, managing, and analyzing contexts with semantic search and automated planning capabilities.

README

Convolut MCP Server

Official Model Context Protocol (MCP) server for Convolut Context Bank, enabling seamless integration with Claude Desktop and other MCP clients.

Features

🚀 11 Powerful Tools for context management and AI-powered operations:

Context Management

list_contexts - Search and filter contexts with advanced options
get_context - Retrieve specific context by ID
create_context - Create new context with content and metadata
update_context - Update existing contexts
delete_context - Delete contexts by ID

AI-Powered Operations

search_contexts - Semantic search across your contexts
consolidate_contexts - AI-powered context consolidation and summarization
plan_from_contexts - Generate actionable plans from multiple contexts

Export & Integration

export_contexts - Export to JSON, XML, TXT, or Markdown formats
get_raw_url - Generate temporary shareable URLs
get_context_stats - Statistical analysis of your contexts

Quick Start

Installation

npm install -g @convolut/convolut-mcp

Claude Desktop Setup

Get your Convolut API key from https://convolut.app
Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "convolut": {
      "command": "npx",
      "args": ["@convolut/convolut-mcp"],
      "env": {
        "CONVOLUT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop
Start using Convolut tools in your conversations! 🎉

Usage Examples

Search Your Contexts

"Search for contexts about machine learning"

Claude will use the search_contexts tool to find relevant contexts in your Convolut library.

Create New Context

"Save this conversation as a new context titled 'API Integration Discussion'"

Claude will use create_context to save the conversation to your Convolut account.

Generate Plans

"Analyze these project contexts and create an actionable plan"

Claude will use consolidate_contexts and plan_from_contexts to analyze multiple contexts and generate structured plans.

Manual Installation

If you prefer to install locally:

# Clone or download the package
git clone https://github.com/expdal3/convolut-mcp.git
cd convolut-mcp

# Install dependencies (none required - pure Node.js!)
npm install

# Test the installation
CONVOLUT_API_KEY=your_key_here node stdio-client.cjs

Then use the full path in your Claude Desktop config:

{
  "mcpServers": {
    "convolut": {
      "command": "node", 
      "args": ["/full/path/to/convolut-mcp/stdio-client.cjs"],
      "env": {
        "CONVOLUT_API_KEY": "your_api_key_here"
      }
    }
  }
}

API Key Setup

Get Your API Key

Sign up at https://convolut.app
Navigate to Settings → API Keys
Generate a new API key
Copy the key (format: convolut_sk_...)

Environment Variables

You can also set the API key as an environment variable:

# Windows
set CONVOLUT_API_KEY=your_api_key_here

# macOS/Linux  
export CONVOLUT_API_KEY=your_api_key_here

Architecture

Claude Desktop (or other MCP Client) → stdio → convolut-mcp (MCP Server) → HTTPS → api.convolut.app

This MCP server provides a direct, efficient bridge between Claude Desktop and the Convolut API, with no intermediate servers required.

Requirements

Node.js 18.0.0 or higher
Convolut API key
Claude Desktop (or any MCP-compatible client)

Supported Platforms

✅ Windows 10/11
✅ macOS 12+
✅ Linux (Ubuntu 20.04+)

Troubleshooting

Claude Desktop Not Seeing Tools

Verify your claude_desktop_config.json syntax is correct
Check that your API key is valid
Restart Claude Desktop completely
Check Claude Desktop logs for errors

API Key Issues

Error: CONVOLUT_API_KEY environment variable is required

Ensure your API key is set in the Claude Desktop config
Verify the API key format starts with conair_sk_
Check for typos in the configuration file

Connection Issues

Verify internet connectivity
Check if your firewall blocks HTTPS requests
Ensure Node.js version is 18.0.0 or higher

Development

Project Structure

convolut-mcp/
├── stdio-client.cjs       # Main MCP server entry point
├── utils/
│   └── api-client.cjs     # Convolut API client
├── tools/
│   ├── contexts.cjs       # Context management tools
│   ├── ai-tools.cjs       # AI-powered operations  
│   └── export.cjs         # Export and statistics
├── types/
│   └── convolut.cjs       # Type definitions
└── README.md