Use the OSS documentation in Cursor

Integrate the OSS documentation with Cursor

Cursor removed the @Docs external documentation source feature in version 3.14.2. The Settings > Indexing & Docs > Add Docs entry, including the NAME, PREFIX, and ENTRYPOINT fields, the Confirm button, and the Indexed N pages status, is no longer available. Do not configure an @Docs data source for the OSS Help Center. Use one of the following methods instead.

Before you choose a method, make sure that the following conditions are met:

• Method 1 requires the Cursor Agent to fetch pages over the network. Your environment must be able to access the OSS Help Center.

• Method 2 requires you to save excerpts of the relevant OSS topics as local Markdown files in your repository.

• To allow Cursor to run ossutil commands directly, you must configure your OSS access credentials in advance.

  Choose a method based on your scenario:

• For one-off questions and quick answers, use Method 1. Paste a documentation link into the chat. No extra preparation is required.

• For key topics that you consult repeatedly, such as presigned PUT URLs, Content-Type settings, the V4 signature algorithm, and multipart upload, use Method 2. The Cursor Agent reads the local excerpts directly without fetching the pages each time.

• To codify the OSS conventions of your project, use Method 3. The Cursor Agent automatically follows the conventions that you define in Rules or Skills when it generates code.

• To index the entire OSS Help Center, evaluate the third-party MCP services in Method 4. Methods 1 to 3 do not support this scenario.

Use the OSS documentation for Q&A

After you integrate the OSS documentation with Cursor, you can ask the Cursor Agent questions that are grounded in the official documentation.

1. Open the Cursor Agent chat window.

2. Provide the relevant OSS documentation: paste the topic link (Method 1), or reference a local copy by typing @ followed by the file name (Method 2).

3. Ask your question. For example: How do I use the OSS Java SDK to create a client and configure access credentials?

   The Cursor Agent answers based on the OSS documentation that you provided. The answers include code examples and configuration steps.

For the preceding example question, the Cursor Agent can return the following answer.

Maven dependency configuration:

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.4</version>
</dependency>

Complete Java code example for creating an OSSClient with environment variable credentials (recommended):

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;

public class OSSClientExample {
    public static void main(String[] args) throws Exception {
        // Obtain credentials from environment variables
        EnvironmentVariableCredentialsProvider credentialsProvider =
            CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        // Configure the client
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // Use V4 signature algorithm
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);

        // Create an OSSClient instance
        OSS ossClient = OSSClientBuilder.create()
                .endpoint("your-endpoint") // For example: https://oss-cn-hangzhou.aliyuncs.com
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region("your-region") // For example: cn-hangzhou
                .build();

        // Use ossClient to perform operations...

        // Shut down the OSSClient instance when it is no longer needed
        ossClient.shutdown();
    }
}

Set the following environment variables: OSS_ACCESS_KEY_ID (your AccessKey ID) and OSS_ACCESS_KEY_SECRET (your AccessKey secret). Both this Java example and the Python example in the error resolution section read credentials from environment variables. Configure your access credentials before you run either example.

Optimize query results

Regardless of the method that you use, the following practices help you get more precise answers:

• Be specific: Avoid broad questions. Ask about a specific feature or scenario.

• Include keywords: Include OSS-related keywords in your question, such as "bucket", "object", and "permission".

• Ask in steps: For complex operations, ask questions in multiple steps.

# Good query examples
How do I use the Java SDK to upload a file to OSS?
How do I configure cross-origin resource sharing (CORS) for OSS?
How do I set permissions by using a Resource Access Management (RAM) policy in OSS?
I need to upload a file to OSS in my Node.js project. Provide a complete code example.
Provide best practices for multipart uploads of large files to OSS.
Provide detailed troubleshooting steps for OSS CDN cache configuration issues.

# Queries to avoid
How do I use OSS? (Too broad)
Upload file (Lacks context)

Use the OSS documentation to resolve errors

If you encounter an error when you use the Alibaba Cloud OSS SDK to upload or download files or perform other operations, you can provide the relevant OSS documentation and let the Cursor Agent help you fix the error. The following example uses a CRC-64 error that occurs when the Python SDK uploads an object from a local file. This example uses the alibabacloud_oss_v2 package, which is different from the aliyun-sdk-oss package in the Java example in the Q&A section. The sample code contains the defect that triggers the error: it opens the file in text mode 'r'. The root cause analysis and the fix are described later in this section.

import alibabacloud_oss_v2 as oss

def main():
    # Load credentials from environment variables for authentication
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configuration and set the credentials provider
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region
    cfg.region = "cn-hangzhou"

    # Create an OSS client with the configured settings
    client = oss.Client(cfg)

    # Upload an object directly from a local file
    # Specify the bucket name, object name, and local file path
    with open('your-test-file.md', 'r') as f:
        result = client.put_object(
            oss.PutObjectRequest(
                bucket="xxx",  # Bucket name
                key="xxx",        # Object name
                body=f.read()     # Read file content
            )
        )

    # Print the result: status code, request ID, content MD5, ETag, CRC64 checksum, version ID, server response time
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
          f' server time: {result.headers.get("x-oss-server-time")},'
    )

if __name__ == "__main__":
    main()

File "/Users/xxx/xxx/py_proj/myenv/lib/python3.12/site-packages/alibabacloud_oss_v2/client.py", line 275, in put_ob...
    return operations.put_object(self._client, request, **kwargs)
File "/Users/xxx/xxx/py_proj/myenv/lib/python3.12/site-packages/alibabacloud_oss_v2/operations/object_basic.py", line 44, in put_object
    op_output = client.invoke_operation(op_input, **kwargs)
File "/Users/xxx/xxx/py_proj/myenv/lib/python3.12/site-packages/alibabacloud_oss_v2/_client.py", line 327, in invoke_operation
    raise exceptions.OperationError(
alibabacloud_oss_v2.exceptions.OperationError: operation error PutObject: crc is inconsistent, client 12522791075485846984, server 16472007160000755729.

To resolve the error, perform the following steps:

1. Open the Cursor Agent chat window.

2. Provide the relevant OSS documentation by pasting the topic link (Method 1) or by referencing a local copy (Method 2), and then describe your specific problem.

   The Cursor Agent uses the official OSS documentation to provide a precise troubleshooting procedure and solution, which helps you optimize your code and resolve the error.

In the Cursor Agent chat window, describe the error. The chat context is automatically associated with the code file that is currently open, put_object_with_file.py (the Python example in this section). The Cursor Agent analyzes the error based on the documentation and the code context and provides a fix suggestion.

For example, when the CRC-64 error alibabacloud_oss_v2.exceptions.OperationError: operation error PutObject: crc is inconsistent occurs during a file upload, the Cursor Agent automatically analyzes the error type (a CRC-64 data integrity check failure, where the client and server CRC-64 values are inconsistent) and the affected scope (PutObject, AppendObject, and UploadPart), and identifies the root cause: the file is read in text mode 'r'. The solution is to change open('your-test-file.md', 'r') to open('your-test-file.md', 'rb') to read the file in binary mode. Cursor also provides a one-click fix button.

The Cursor Agent provides two solutions for the OSS SDK file upload error:

1. Recommended solution: open the file in binary mode 'rb'. This solution ensures data integrity, works for all file types, and follows best practices.

2. Temporary solution: create put_object_with_file_disable_crc.py to disable CRC-64 verification. This solution loses data integrity protection, applies only to trusted environments, and is not recommended for production environments.

The OSS SDK enables CRC-64 verification by default. The client and the server each compute a checksum and compare the values. Opening a file in text mode may convert line feeds, which leads to checksum inconsistencies. Always read files in binary mode.

Use the OSS documentation to generate ossutil commands

You can describe an operation in natural language and let the Cursor Agent generate command line operations for tasks such as uploads, downloads, and canonical name (CNAME) configurations. Provide the relevant ossutil documentation by pasting the topic link (Method 1) or referencing a local copy (Method 2). The Cursor Agent references the documentation and the current directory to generate commands that you can run directly.

1. Open the Cursor Agent chat window. Provide the ossutil documentation, and then describe the operation that you want to perform.

   For example: Use ossutil to upload the cname-configuration.xml file to the bucket named examplebucket

2. The Cursor Agent analyzes whether the cname-configuration.xml file exists in the current directory. In the following example analysis, the Cursor Agent checks the files in the current directory and views the file content before it generates the command:

   Let me first check the files in the current directory:
   
   Listed current directory
   
   I can see the cname-configuration.xml file. Let me view the file content to understand its structure:
   
   Read cname-configuration.xml

3. Based on the key elements in your description, such as "upload", the file name, and the bucket name, the Cursor Agent generates the corresponding ossutil command from the official OSS documentation. If you have configured your access credentials, Cursor can also run the command for you.

   For example, run the following ossutil command to upload the cname-configuration.xml file to the specified bucket:

ossutil cp cname-configuration.xml oss://examplebucket/

If the command runs successfully, the terminal returns the upload result and the elapsed time:

Success: Total 1 file, size 3882 B, Upload done:(1 objects, 3882 B), avg 14.731 KiB/s

0.260099(s) elapsed

After the Cursor Agent generates a command, you can refer to the ossutil 2.0 documentation (https://help.aliyun.com/zh/oss/developer-reference/ossutil-overview) to verify the meaning of each parameter or to find command examples for more scenarios, such as uploads, downloads, and CNAME configurations.