Memory Box MCP Server

Instructions

Implementation Reference

• src/index.ts:378-400 (handler)

  Core handler function in MemoryBoxClient that executes the bucket creation via API POST to /api/v2/buckets with bucket_name parameter.
  async createBucket(bucketName: string): Promise<any> { try { const response = await axios.post( `${this.baseUrl}/api/v2/buckets`, {}, { params: { bucket_name: bucketName }, headers: { "Authorization": `Bearer ${this.token}` } } ); return response.data; } catch (error) { if (axios.isAxiosError(error)) { throw new McpError( ErrorCode.InternalError, `Failed to create bucket: ${error.response?.data?.detail || error.message}` ); } throw error; } }
• src/index.ts:1168-1184 (handler)

  MCP CallToolRequest handler case that validates input, invokes the client.createBucket method, and returns formatted success response.
  case "create_bucket": { const bucketName = String(request.params.arguments?.bucket_name || ""); if (!bucketName) { throw new McpError(ErrorCode.InvalidParams, "Bucket name is required"); } // Create the bucket const result = await memoryBoxClient.createBucket(bucketName); return { content: [{ type: "text", text: `Bucket "${bucketName}" created successfully!\n\n${result.message || "The bucket is now available for storing memories."}` }] }; }
• src/index.ts:785-796 (schema)

  Tool schema definition including name, description, and inputSchema for validation (requires bucket_name string). This is returned by ListToolsRequest.
  name: "create_bucket", description: "Create a new bucket for organizing memories", inputSchema: { type: "object", properties: { bucket_name: { type: "string", description: "Name of the bucket to create" } }, required: ["bucket_name"] }
• src/index.ts:543-866 (registration)

  Registration of all tools via setRequestHandler for ListToolsRequestSchema, including the create_bucket tool in the tools array.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "save_memory", description: "Save a memory to Memory Box", inputSchema: { type: "object", properties: { text: { type: "string", description: "The memory content to save (either text OR raw_content required)" }, raw_content: { type: "string", description: "Raw content for processing (alternative to text)" }, bucket_id: { type: "string", description: `The bucket to save the memory to (default: "${DEFAULT_BUCKET}")` }, source_type: { type: "string", description: "Type of memory source (default: 'llm_plugin')" }, reference_data: { type: "object", description: "Structured metadata for memory storage", properties: { source: { type: "object", required: ["platform"], properties: { platform: { type: "string", description: "Platform identifier (required)" }, type: { type: "string", description: "Source type" }, version: { type: "string", description: "Version info" }, url: { type: "string", description: "Source URL" }, title: { type: "string", description: "Source title" }, additional_metadata: { type: "object", description: "Extra metadata" } } }, context: { type: "object", properties: { related_memories: { type: "array", items: { type: "object" }, description: "Related memory references" }, conversation_id: { type: "string", description: "Conversation identifier" }, message_id: { type: "string", description: "Message identifier" } } }, content_context: { type: "object", properties: { url: { type: "string", description: "Content URL" }, title: { type: "string", description: "Content title" }, surrounding_text: { type: "string", description: "Context around selection" }, selected_text: { type: "string", description: "Selected text" }, additional_context: { type: "object", description: "Extra context" } } } } } }, required: ["text"] } }, { name: "search_memories", description: "Search for memories using semantic search", inputSchema: { type: "object", properties: { query: { type: "string", description: "The search query (semantic search)" }, bucket_id: { type: "string", description: "Filter to specific bucket" }, source_type: { type: "string", description: "Filter by source type" }, limit: { type: "integer", description: "Maximum number of results to return (1-100, default: 10)", minimum: 1, maximum: 100 }, offset: { type: "integer", description: "Number of results to skip for pagination (default: 0)", minimum: 0 }, debug: { type: "boolean", description: "Include debug information in results (default: false)" }, include_reference_data: { type: "boolean", description: "Include reference data in response (default: false)" }, date_sort: { type: "boolean", description: "Sort semantic search results by date after similarity filtering (default: false)" }, sort_order: { type: "string", description: "Sort order when date_sort is enabled (default: 'desc')", enum: ["asc", "desc"] } }, required: ["query"] } }, { name: "get_all_memories", description: "Retrieve all memories with pagination support", inputSchema: { type: "object", properties: { all: { type: "boolean", description: "Get all memories (overrides pagination, default: false)" }, bucket_id: { type: "string", description: "Filter to specific bucket" }, source_type: { type: "string", description: "Filter by source type" }, limit: { type: "integer", description: "Maximum number of results to return (1-100, default: 10)", minimum: 1, maximum: 100 }, offset: { type: "integer", description: "Number of results to skip for pagination (default: 0)", minimum: 0 }, include_reference_data: { type: "boolean", description: "Include reference data in response (default: false)" }, date_sort: { type: "boolean", description: "Sort results by date (default: false)" }, sort_order: { type: "string", description: "Sort order (default: 'desc')", enum: ["asc", "desc"] } } } }, { name: "get_bucket_memories", description: "Get memories from a specific bucket", inputSchema: { type: "object", properties: { bucket_id: { type: "string", description: "The bucket to retrieve memories from" }, limit: { type: "integer", description: "Maximum number of results to return (1-100, default: 10)", minimum: 1, maximum: 100 }, offset: { type: "integer", description: "Number of results to skip for pagination (default: 0)", minimum: 0 }, include_reference_data: { type: "boolean", description: "Include reference data in response (default: false)" } }, required: ["bucket_id"] } }, { name: "get_related_memories", description: "Find semantically similar memories to a specific memory", inputSchema: { type: "object", properties: { memory_id: { type: "integer", description: "The ID of the memory to find related memories for" }, min_similarity: { type: "number", description: "Minimum similarity threshold (0.0-1.0) for related memories (default: 0.7)" } }, required: ["memory_id"] } }, { name: "check_memory_status", description: "Check the processing status of a memory", inputSchema: { type: "object", properties: { memory_id: { type: "integer", description: "The ID of the memory to check status for" } }, required: ["memory_id"] } }, { name: "get_usage_stats", description: "Retrieve user usage statistics and plan information", inputSchema: { type: "object", properties: { // No specific parameters needed for this operation } } }, { name: "get_buckets", description: "Retrieve a list of all available buckets", inputSchema: { type: "object", properties: { // No specific parameters needed for this operation } } }, { name: "create_bucket", description: "Create a new bucket for organizing memories", inputSchema: { type: "object", properties: { bucket_name: { type: "string", description: "Name of the bucket to create" } }, required: ["bucket_name"] } }, { name: "delete_bucket", description: "Delete a bucket (empty by default, use force to delete with content)", inputSchema: { type: "object", properties: { bucket_name: { type: "string", description: "Name of the bucket to delete" }, force: { type: "boolean", description: "Force deletion even if bucket contains memories (default: false)" } }, required: ["bucket_name"] } }, { name: "update_memory", description: "Update an existing memory including text, bucket, and relationships", inputSchema: { type: "object", properties: { memory_id: { type: "integer", description: "The ID of the memory to update" }, text: { type: "string", description: "New text content for the memory" }, raw_content: { type: "string", description: "New raw content for the memory" }, bucket_id: { type: "string", description: "Move memory to different bucket" }, source_type: { type: "string", description: "Update source type" }, reference_data: { type: "object", description: "Updated reference data (same structure as save_memory)" } }, required: ["memory_id"] } }, { name: "delete_memory", description: "Delete a specific memory", inputSchema: { type: "object", properties: { memory_id: { type: "integer", description: "The ID of the memory to delete" } }, required: ["memory_id"] } } ] }; });