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 🔍

(Compliance updated until commit d50fd1e)

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Non-applicable Scope: The PR adds documentation and static configuration examples without implementing runtime actions or logging, so audit trail requirements cannot be verified from the diff. Referred Code import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" import Prerequisites from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_helm_prerequisites_block.mdx" import AdvancedConfig from '/docs/generalTemplates/_ocean_advanced_configuration_note.md' import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md" # Cursor Port's Cursor integration allows you to ingest Cursor usage metrics into your software catalog using the [Ocean Custom Integration](/build-your-software-catalog/custom-integration/ocean-custom-integration/overview) framework. After installing this integration, you would be able to visualize your Cursor usage metrics using Port's dashboards. <img src="/img/ai-agents/cursorDashboard.png" border="1px" width="100%" /> ## Supported metrics The Cursor integration can ingest usage metrics into Port. Available metrics depend on your Cursor subscription tier: **Available for all Cursor teams:** - `cursor_usage_record` - Organization-level daily usage metrics from `/teams/daily-usage-data`. ... (clipped 1451 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: No runtime errors: The changes are documentation and configuration snippets; there is no executable error handling to assess, though examples mention possible 401 responses without prescribing handling in code. Referred Code <summary><b>Enterprise: Individual commit tracking (Click to expand)</b></summary> :::warning Requires Cursor Enterprise This endpoint requires a Cursor Enterprise subscription. You'll receive a `401` error if your API key doesn't have enterprise access. ::: ```yaml showLineNumbers resources: - kind: /analytics/ai-code/commits selector: query: 'true' query_params: startDate: "30d" endDate: "0d" page: "1" pageSize: "100" data_path: '.items' port: entity: mappings: identifier: .commitHash ... (clipped 35 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Docs only change: No user-facing error messages are implemented in this PR; secure error handling cannot be evaluated from documentation-only changes. Referred Code import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" import Prerequisites from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_helm_prerequisites_block.mdx" import AdvancedConfig from '/docs/generalTemplates/_ocean_advanced_configuration_note.md' import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md" # Cursor Port's Cursor integration allows you to ingest Cursor usage metrics into your software catalog using the [Ocean Custom Integration](/build-your-software-catalog/custom-integration/ocean-custom-integration/overview) framework. After installing this integration, you would be able to visualize your Cursor usage metrics using Port's dashboards. <img src="/img/ai-agents/cursorDashboard.png" border="1px" width="100%" /> ## Supported metrics The Cursor integration can ingest usage metrics into Port. Available metrics depend on your Cursor subscription tier: **Available for all Cursor teams:** - `cursor_usage_record` - Organization-level daily usage metrics from `/teams/daily-usage-data`. ... (clipped 1451 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Secrets Exposure Risk: Documentation includes commands using plain placeholders for API keys in environment variables and Helm values without guidance on using secrets managers or Kubernetes secrets, which may encourage insecure practices. Referred Code ```bash showLineNumbers 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="https://api.cursor.com" \ --set integration.config.authType="basic" \ --set integration.config.paginationType="none" \ --set integration.secrets.username="YOUR_CURSOR_API_KEY" \ --set integration.secrets.password="" </details> > Learn more about managing compliance <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/#configuration-options'>generic rules</a> or creating your own <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/#custom-compliance'>custom rules</a> </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:** <br><a href='https://github.com/port-labs/port-docs/pull/2986/files#diff-eb4b3c00dc992b4f1d9b8001f6adf169271592e7b7950e74ce2f680b7a369e07R986-R1167'><strong>Security Guidance</strong></a>: The PR provides API usage and mapping examples but does not address validation or <br>sanitization of external API responses or secure handling of user emails/org identifiers <br>in mappings, which cannot be validated from docs alone.<br> <details open><summary>Referred Code</summary> ```markdown <details> <summary><b>Organization usage metrics mapping (Click to expand)</b></summary> ```yaml showLineNumbers - kind: /teams/daily-usage-data selector: query: 'true' method: POST body: '{"startDate": ((now | floor) - (86400 * 30)) * 1000, "endDate": (now | floor) * 1000}' data_path: '.data' port: entity: mappings: identifier: .org + "@" + .date title: .org + " usage " + .date blueprint: '"cursor_usage_record"' properties: record_date: .date + "T00:00:00Z" org: .org total_accepts: .totals.total_accepts total_rejects: .totals.total_rejects ... (clipped 161 lines) Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

---

Previous compliance checks

Compliance check up to commit deccfbf

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"> <!-- /compliance --update_compliance=true --> </td></tr></tbody></table> </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