Added Docs for Cursor Metric Custom Ocean Integration

[kodjomiles]

User description

Description

Added a new documentation on how to setup cursor metrics

Added docs pages

Please also include the path for the added docs

• Cursor (/build-your-software-catalog/sync-data-to-catalog/ai-agents/cursor/)

Updated docs pages

Please also include the path for the updated docs

• None

---

PR Type

Documentation

---

Description

• Added comprehensive Cursor integration documentation

• Documented six supported metric types for usage and AI tracking

• Provided installation instructions for Helm and Docker deployments

• Included six complete blueprint definitions with properties and calculations

• Added resource mapping configurations for all metric endpoints

---

Diagram Walkthrough

flowchart LR
  A["Cursor API"] -- "Daily Usage Metrics" --> B["Organization/User/Team Records"]
  A -- "AI Code Tracking" --> C["Commit & Code Change Records"]
  B --> D["Port Blueprints"]
  C --> D
  D --> E["Resource Mappings"]
  E --> F["Port Catalog"]

Loading

File Walkthrough

Relevant files

Documentation

_category_.json Cursor documentation category configuration                            docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/cursor/category.json Created new category configuration file for Cursor documentation section Set label to "Cursor" and position to 18 in navigation hierarchy +5/-0      cursor.md Complete Cursor metrics integration documentation                docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/cursor/cursor.md Comprehensive guide for Cursor integration with Ocean Custom Integration framework Documented six metric types: organization, user, and team usage records plus commit tracking Provided Helm and Docker installation methods with complete configuration parameters Included six detailed blueprint definitions with schema properties, calculations, and relations Added resource mapping configurations with JQ expressions for all API endpoints Included customization guidance and interactive builder recommendations +1167/-0

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance

🔴

Credentials in command history Description: The documentation instructs users to pass sensitive credentials (CURSOR_API_TOKEN, YOUR_PORT_CLIENT_ID, YOUR_PORT_CLIENT_SECRET) directly as command-line arguments in the Helm installation command, which may expose these secrets in shell history, process listings, and CI/CD logs. cursor.md [56-70] Referred Code helm repo add --force-update port-labs https://port-labs.github.io/helm-charts helm upgrade --install my-ocean-cursor-integration port-labs/port-ocean \ --set port.clientId="YOUR_PORT_CLIENT_ID" \ --set port.clientSecret="YOUR_PORT_CLIENT_SECRET" \ --set port.baseUrl="https://api.getport.io" \ --set initializePortResources=true \ --set scheduledResyncInterval=120 \ --set integration.identifier="my-ocean-cursor-integration" \ --set integration.type="custom" \ --set integration.eventListener.type="POLLING" \ --set integration.config.baseUrl="CURSOR_API_BASE_URL" \ --set integration.config.authType="bearer_token" \ --set integration.config.paginationType="none" \ --set integration.secrets.authValue="CURSOR_API_TOKEN" </details></details></td></tr> <tr><td><details><summary><strong>Exposed secrets in Docker </strong></summary><br> <b>Description:</b> The Docker run command includes sensitive credentials as environment variables in plain <br>text on the command line, which exposes them in process listings, shell history, and <br>container inspection outputs accessible to other users on the system.<br> <strong><a href='https://github.com/port-labs/port-docs/pull/2986/files#diff-eb4b3c00dc992b4f1d9b8001f6adf169271592e7b7950e74ce2f680b7a369e07R109-R121'>cursor.md [109-121]</a></strong><br> <details open><summary>Referred Code</summary> ```markdown docker run -i --rm --platform=linux/amd64 \ -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \ -e OCEAN__INITIALIZE_PORT_RESOURCES=true \ -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ -e OCEAN__INTEGRATION__CONFIG__BASE_URL="CURSOR_API_BASE_URL" \ -e OCEAN__INTEGRATION__CONFIG__AUTH_TYPE="bearer_token" \ -e OCEAN__INTEGRATION__CONFIG__PAGINATION_TYPE="none" \ -e OCEAN__INTEGRATION__SECRETS__AUTH_VALUE="CURSOR_API_TOKEN" \ -e OCEAN__PORT__CLIENT_ID="YOUR_PORT_CLIENT_ID" \ -e OCEAN__PORT__CLIENT_SECRET="YOUR_PORT_CLIENT_SECRET" \ -e OCEAN__PORT__BASE_URL="https://api.getport.io" \ ghcr.io/port-labs/port-ocean-custom:latest </details></details></td></tr> <tr><td colspan='2'><strong>Ticket Compliance</strong></td></tr> <tr><td>⚪</td><td><details><summary>🎫 <strong>No ticket provided </summary></strong> - [ ] Create ticket/issue <!-- /create_ticket --create_ticket=true --> </details></td></tr> <tr><td colspan='2'><strong>Codebase Duplication Compliance</strong></td></tr> <tr><td>⚪</td><td><details><summary><strong>Codebase context is not defined </strong></summary> Follow the <a href='https://qodo-merge-docs.qodo.ai/core-abilities/rag_context_enrichment/'>guide</a> to enable codebase context checks. </details></td></tr> <tr><td colspan='2'><strong>Custom Compliance</strong></td></tr> <tr><td rowspan=6>🟢</td><td> <details><summary><strong>Generic: Comprehensive Audit Trails</strong></summary><br> **Objective:** To create a detailed and reliable record of critical system actions for security analysis <br>and compliance.<br> **Status:** Passed<br> </details></td></tr> <tr><td> <details><summary><strong>Generic: Meaningful Naming and Self-Documenting Code</strong></summary><br> **Objective:** Ensure all identifiers clearly express their purpose and intent, making code <br>self-documenting<br> **Status:** Passed<br> </details></td></tr> <tr><td> <details><summary><strong>Generic: Robust Error Handling and Edge Case Management</strong></summary><br> **Objective:** Ensure comprehensive error handling that provides meaningful context and graceful <br>degradation<br> **Status:** Passed<br> </details></td></tr> <tr><td> <details><summary><strong>Generic: Secure Error Handling</strong></summary><br> **Objective:** To prevent the leakage of sensitive system information through error messages while <br>providing sufficient detail for internal debugging.<br> **Status:** Passed<br> </details></td></tr> <tr><td> <details><summary><strong>Generic: Secure Logging Practices</strong></summary><br> **Objective:** To ensure logs are useful for debugging and auditing without exposing sensitive <br>information like PII, PHI, or cardholder data.<br> **Status:** Passed<br> </details></td></tr> <tr><td> <details><summary><strong>Generic: Security-First Input Validation and Data Handling</strong></summary><br> **Objective:** Ensure all data inputs are validated, sanitized, and handled securely to prevent <br>vulnerabilities<br> **Status:** Passed<br> </details></td></tr> <tr><td align="center" colspan="2"> - [ ] Update <!-- /compliance --update_compliance=true --> </td></tr></tbody></table> <details><summary>Compliance status legend</summary> 🟢 - Fully Compliant<br> 🟡 - Partial Compliant<br> 🔴 - Not Compliant<br> ⚪ - Requires Further Human Verification<br> 🏷️ - Compliance label<br> </details>

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Create a dedicated integration for Cursor Instead of providing extensive documentation for a manual setup, create a dedicated Ocean integration for Cursor. This would automate the creation of blueprints and mappings, simplifying the user experience and improving maintainability. Examples: docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/cursor/cursor.md [132-1150] ## Set up data model Before the integration can sync data, you need to create the required blueprints in Port. These blueprints define the data model for your Cursor metrics. **To create the blueprints:** 1. Go to your [Builder page](https://app.getport.io/settings/data-model). 2. Click on the `+ Blueprint` button. ... (clipped 1009 lines) Solution Walkthrough: Before: # Cursor Integration Documentation ## Set up data model To create the blueprints, copy and paste each blueprint JSON from the sections below. <details> <summary><b>Cursor Usage Record Blueprint (Click to expand)</b></summary> ```json { "identifier": "cursor_usage_record", ... // ~250 lines of JSON } ... (5 more large blueprint definitions) ... Configuration Add the resource mapping configurations below. Organization usage metrics mapping (Click to expand) ```yaml resources: - kind: /api/v1/usage/org ... // ~30 lines of YAML ``` ... (3 more large mapping definitions) ... #### After: ```markdown # Cursor Integration Documentation ## Installation The Cursor integration is a dedicated Ocean integration that simplifies setup. <Tabs> <TabItem value="helm" label="Helm"> ```bash # Install with a simple Helm command helm upgrade --install my-cursor-integration port-labs/port-ocean \ --set integration.type="cursor" \ --set integration.secrets.cursorApiToken="YOUR_CURSOR_TOKEN" \ --set port.clientId="..." \ --set port.clientSecret="..." \ --set initializePortResources=true ... (Docker tab would be similarly simple) ... The integration will automatically create all necessary blueprints and resource mappings. <details><summary>Suggestion importance[1-10]: 9</summary> __ Why: The suggestion addresses a major design issue by proposing a dedicated integration, which would vastly improve user experience and maintainability over the current error-prone manual setup. </details></details></td><td align=center>High </td></tr><tr><td rowspan=1>Possible bug</td> <td> <details><summary>Correct an inconsistent JQ expression<!-- not_implemented --></summary> ___ **In the user usage metrics mapping, correct the JQ expressions for <code>identifier</code> and <br><code>title</code> to use <code>.totals.email</code> instead of <code>.email</code> for consistency and to prevent <br>potential errors.** [docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/cursor/cursor.md [1026-1041]](https://github.com/port-labs/port-docs/pull/2986/files#diff-eb4b3c00dc992b4f1d9b8001f6adf169271592e7b7950e74ce2f680b7a369e07R1026-R1041) ```diff resources: - kind: /api/v1/usage/users selector: query: 'true' data_path: '.data' # Adjust based on your API response structure port: entity: mappings: - identifier: .email + "@" + .date - title: .email + " usage " + .date + identifier: .totals.email + "@" + .date + title: .totals.email + " usage " + .date blueprint: '"cursor_user_usage_record"' properties: record_date: .date + "T00:00:00Z" org: .org email: .totals.email is_active: .totals.is_active Apply / Chat Suggestion importance[1-10]: 8 __ Why: This suggestion correctly identifies a potential bug in the JQ mapping where identifier and title use an incorrect path (.email) instead of the correct one (.totals.email), preventing a likely data ingestion error.	Medium
Enhancement	Improve clarity of table descriptions Rephrase the descriptions for initializePortResources and sendRawDataExamples to improve grammar, capitalization, and clarity. docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/cursor/cursor.md [91-92] -| `initializePortResources` | Default true, When set to true the integration will create default blueprints and the port App config Mapping. Read more about [initializePortResources](https://ocean.getport.io/develop-an-integration/integration-configuration/#initializeportresources---initialize-port-resources) | true | ❌ | -| `sendRawDataExamples` | Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true | true | ❌ | +| `initializePortResources` | Defaults to `true`. When set to `true`, the integration will create default blueprints and the Port App Config mapping. Read more about [initializePortResources](https://ocean.getport.io/develop-an-integration/integration-configuration/#initializeportresources---initialize-port-resources) | true | ❌ | +| `sendRawDataExamples` | Enables sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Defaults to `true`. | true | ❌ | Apply / Chat Suggestion importance[1-10]: 3 __ Why: The suggestion correctly identifies and fixes minor grammatical and capitalization issues in the documentation, improving its overall quality and professionalism.	Low
best practice	Fix heading formatting by removing space Remove the trailing space from the ## Configuration heading to fix markdown formatting. docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/cursor/cursor.md [955-957] -## Configuration +## Configuration After installation, define which endpoints to sync in your integration configuration. Each resource maps an API endpoint to Port entities using [JQ expressions](https://stedolan.github.io/jq/manual/) to transform the data. Apply / Chat Suggestion importance[1-10]: 2 __ Why: The suggestion correctly points out a trailing whitespace in a markdown heading and proposes removing it, which is a good practice for code cleanliness.	Low
Update

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2986.d2ngvl90zqbob8.amplifyapp.com