Memory Box MCP Server

Instructions

Implementation Reference

• src/index.ts:987-1020 (handler)

  MCP tool handler for 'get_bucket_memories': validates bucket_id, calls MemoryBoxClient.getBucketMemories with options, formats and returns the list of memories from the bucket.

  case "get_bucket_memories": {
    const bucketId = String(request.params.arguments?.bucket_id || "");
  
    if (!bucketId) {
      throw new McpError(ErrorCode.InvalidParams, "Bucket ID is required");
    }
  
    const options = {
      limit: request.params.arguments?.limit ? Number(request.params.arguments.limit) : undefined,
      offset: request.params.arguments?.offset ? Number(request.params.arguments.offset) : undefined,
      includeReferenceData: Boolean(request.params.arguments?.include_reference_data || false)
    };
  
    // Get memories from the specified bucket
    const result = await memoryBoxClient.getBucketMemories(bucketId, options);
  
    // Format the results
    let responseText = `Memories in bucket "${bucketId}":\n\n`;
    
    if (result.items && result.items.length > 0) {
      result.items.forEach((memory: any, index: number) => {
        responseText += `${index + 1}. ${memory.text}\n\n`;
      });
    } else {
      responseText += "No memories found in this bucket.";
    }
  
    return {
      content: [{
        type: "text",
        text: responseText
      }]
    };
  }

• src/index.ts:704-730 (schema)

  Input schema for get_bucket_memories tool: requires bucket_id, optional limit (1-100), offset (>=0), include_reference_data (boolean).

  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"]
  }

• src/index.ts:261-297 (helper)

  MemoryBoxClient.getBucketMemories helper method: performs API GET request to /api/v2/memory with bucketId and optional pagination/reference params, handles errors.

  async getBucketMemories(
    bucketId: string,
    options?: {
      limit?: number;
      offset?: number;
      includeReferenceData?: boolean;
    }
  ): Promise<any> {
    try {
      const params: any = { bucketId };
      
      if (options) {
        if (options.limit !== undefined) params.limit = options.limit;
        if (options.offset !== undefined) params.offset = options.offset;
        if (options.includeReferenceData !== undefined) params.include_reference_data = options.includeReferenceData;
      }
  
      const response = await axios.get(
        `${this.baseUrl}/api/v2/memory`,
        {
          params,
          headers: {
            "Authorization": `Bearer ${this.token}`
          }
        }
      );
      return response.data;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new McpError(
          ErrorCode.InternalError,
          `Failed to get bucket memories: ${error.response?.data?.detail || error.message}`
        );
      }
      throw error;
    }
  }