diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 3489b7ec9..ec11240db 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -235,10 +235,14 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/single-tenant-data-models[Single-tenant data models with Orgs] *** link:{{navprefix}}/orgs-api-op[Org administration] ** link:{{navprefix}}/tse-cluster[Cluster maintenance and upgrade] + +* MCP Servers +** link:{{navprefix}}/SpotterCode[SpotterCode for IDEs] +** link:{{navprefix}}/mcp-integration[ThoughtSpot MCP server] + * Integration with external tools ** link:{{navprefix}}/external-tool-script-integration[External tools and scripts] ** link:{{navprefix}}/pendo-integration[Pendo integration with embed] -** link:{{navprefix}}/mcp-integration[MCP server integration] ** link:{{navprefix}}/sf-integration[Integration with Salesforce] ** link:{{navprefix}}/vercel-integration[Vercel integration] * Additional references diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index 8fb5f3670..b3ac1cc1f 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -14,6 +14,13 @@ The Visual Embed SDK provides several controls to customize the embedded view, i The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience. -- + +[div announcementBlock] +-- +[IMPORTANT] +The V1 classic experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends that you start upgrading your full app embedding implementation to the V3 UI experience. +-- + == UI experience modes ThoughtSpot application supports the following UI experience modes: @@ -27,6 +34,7 @@ The key differences between these UI experience modes are listed in the followin -- [width="100%", cols="2,4,4,5"] [options='header'] + |===== |Feature component |Classic (V1) experience | V2 experience | V3 experience |**UI experience**| Classic layout + diff --git a/modules/ROOT/pages/spottercode.adoc b/modules/ROOT/pages/spottercode.adoc new file mode 100644 index 000000000..5ca9ddf1a --- /dev/null +++ b/modules/ROOT/pages/spottercode.adoc @@ -0,0 +1,296 @@ += SpotterCode for IDEs +:toc: true +:toclevels: 2 + +:page-title: SpotterCode integration gude +:page-pageid: SpotterCode +:page-description: This document provides a comprehensive, step-by-step approach to integrating SpotterCode with your IDE and use its tools and skills to get help with embedding a ThoughtSpot object. + +ThoughtSpot SpotterCode enables AI agents in your integrated development environments (IDEs) to discover documentation lookup skills and assist developers in embedding ThoughtSpot content in their applications. Using the SpotterCode extension, developers can rapidly generate and build deployment-ready code in their applications. + +[IMPORTANT] +==== +SpotterCode is an add-on feature available with the link:https://www.thoughtspot.com/pricing[ThoughtSpot Analytics and ThoughtSpot Embedded offerings, window=_blank]. + +//// +To enable the SpotterCode in your environment, you must have an active subscription to one of the following ThoughtSpot license plans: + +* Enterprise Edition of ThoughtSpot Analytics +* ThoughtSpot Embedded subscription +//// +If you have an active subscription, and you want to enable SpotterCode integration on your IDE, contact your ThoughtSpot Sales representative or ThoughtSpot Support. +==== + +== Overview +SpotterCode is a server-side integration layer that connects IDEs to a ThoughtSpot-hosted MCP server. It exposes a set of tools and documentation lookup skills to the agentic systems and provides access to ThoughtSpot SDK, API documentation, and code samples within the IDE. Developers can leverage these capabilities to obtain relevant guidance and let the agent in their IDE scaffold code that fits their project’s context and structure. + +=== Key features +When SpotterCode is integrated with your IDE, it offers the following advantages: + +* Empowers your IDE with documentation lookup skills and provides direct access to the information and guidance required to embed ThoughtSpot and integrate ThoughtSpot REST API workflows in your projects. +* Accelerate embedding and integration of ThoughtSpot analytics into applications by providing code generation, SDK skills, and custom styling directly in the IDE. +- Enables developers to build context-aware and deployment-ready code tailored to their project structure, thereby reducing manual effort and errors. +- Reduces operational strain on development teams by providing boilerplate code, agentic tools for embedding ThoughtSpot in your application. + +=== Supported tools and skills +When the SpotterCode MCP server is integrated with your IDE, it exposes the following tools and skills to the AI agent on your IDE: + +* `get-visual-embed-sdk-reference` + +A documentation lookup skill that enables your IDE's AI agent to access ThoughtSpot Visual Embed SDK documentation and generate code samples for embedding ThoughtSpot content. This skill is used when responding to user prompts related to embedding and the Visual Embed SDK; for example, supported embedded types, authentication options, configuration schemas, customization settings, event hooks, and code samples. + +* `get-rest-api-reference` + +The REST API lookup skill that enables access to REST API specification and SDKs, endpoints, request and response formats, authentication flows, assistance with CRUD operations on ThoughtSpot objects and metadata, API documentation, and REST API TypeScript and Java SDK. + +* `get-developer-docs-reference` + +A documentation lookup skill to find information about embedding, UI customization and theming, deployment guidelines, security settings, best practices, and more. + + +//// +* `get-sdk-docs` + +Searches and retrieves documentation for ThoughtSpot SDKs, including Visual Embed SDK and REST API SDK. The agent on your IDE uses this skill to get responses for user questions related to embedding, authentication options, customization settings, and REST APIs. For example, when a user sends a natural language question about embedding ThoughtSpot, the AI agent on your IDE programmatically determines the `query` string and documentation `type`, invokes the `get-sdk-docs` skill, and returns responses from the Visual Embed SDK documentation. + +* `get-code-example` + +Retrieves code example from ThoughtSpot SDKs. For example, when a user asks question on embedding Liveboard, the AI agent on your IDE determines the context programmatically and invokes `get-code-example` skill to retrieve code examples for embedding a Liveboard. + +* `get-style-customization` + +Provides theming, styling, and customization guidance for ThoughtSpot UI and embeds. Supports changing colors, fonts, backgrounds, branding, and other visual elements using CSS variables, theme JSON, or the Visual Embed SDK. The skill can generate official `CustomVariables` code and styling examples for LiveBoard, Search, and Visualization embeds. This skill supports text queries, branding guidelines in PDF, and design mockup image and PDF. ++ +For example, when a user sends instructions to change the button or background color of the embedded page, the AI agent on your IDE invokes this `get-style-customization` skill to generate the code with variables supported in the ThoughtSpot's CSS customization framework. If the user's instruction is match your host app's style, the theme properties and values are extracted from your codebase and applied to your embed. +//// +==== Input schema of the SpotterCode skills + +The input schema for the SpotterCode skills consists of the following parameters. Note that the values for these parameters are context-driven and are programmatically added by the AI agent orchestrating the workflows in your IDE. + +* `query` + +A free-form string describing the user's request or question. This is used to determine the context and intent of the skill invocation. For example, "How do I listen for filter events in a Liveboard embed?" +* `version` + +The SDK version. By default, the latest version is used for generating responses. +* `topK` + +Number of relevant documents to return. Default is 5. +* `symbolName` + +Symbol name, such as `CustomCssInterface`, to set the scope of search. +* `apiName` + +API node to return in response. Used when the API node is known. Gets the fastest path to the request/response schema. +* `additionalDocs` + +Additional documentation to use in response. Used when you also want the client SDK guidance for Java or TypeScript alongside the REST API information. + +Your IDE’s AI agent leverages these parameters to retrieve accurate information and fine-tune responses. When results are too noisy or verbose, the agent can refine the query, reduce topK values, or specify a symbolName or apiName for more targeted retrieval. In cases of version conflicts, the agent can explicitly define the required version. + +//// +* `appThemeContext` + +This parameter in the `get-style-customization` input schema is used when a user sends the instruction to match the app's theme. It is an optional object containing extracted theme values such as `computedStyles`, `cssVariables`, `designTokens`, and `additionalContext`. +//// + +=== How it works + +. A user starts a chat session with the IDE and asks a question seeking information or help with a specific action related to ThoughtSpot embedding, REST APIs, or the SDKs. +. The AI agent in your IDE processes the natural language input, determines the intent, and finds the appropriate skills required to generate a response. +. The AI agent sends a structured MCP request, setting the context and input parameters to fetch the relevant information. +. Using the MCP skill, the AI agent retrieves information and examples for generating the response and provides them to the model. +. The model generates and returns a final response to the user. + +=== Supported IDEs + +The initial version of SpotterCode supports the following IDEs: + +* Cursor AI +* Visual Studio Code with GitHub Copilot +* Claude Code + +=== Limitations + +* SpotterCode’s capabilities are limited to the features and parameters exposed by the current Visual Embed SDK, REST API, and ThoughtSpot Developer documentation. +* SpotterCode helps in generating code samples for the most common use cases. Development scenarios that require deeper customization and have highly specialized use cases may require manual intervention or additional coding. + +== Integrate SpotterCode with your IDE +Before getting started with SpotterCode integration, ensure your environment meets the following prerequisites: + +* Ensure that your IDE supports AI agentic workflows and chats. Ensure that your environment has the latest version of the IDE installed, and the AI models are enabled for use in chat sessions. +* Access to the MCP server configuration settings with the ability to add or modify server URL and other relevant properties. +* Access to the ThoughtSpot MCP Server that enables SpotterCode integration. To obtain the SpotterCode MCP Server URL for integration with your IDE, contact your ThoughtSpot Sales representative or ThoughtSpot Support. +* Node.js is required to run the MCP server and enable communication between Cursor and SpotterCode. Ensure that Node.js is installed in your environment. +* Access to the ThoughtSpot instance and its resources that you want to embed or access via the REST API. + +=== Integrate SpotterCode with Cursor + +. To add the MCP server URL to your Cursor settings, go to **Cursor Settings** > **Tools and MCP**. Cursor opens the `mcp.json` file. +. Add the SpotterCode MCP Server URL as a remote MCP server. For information about MCP server configuration and setup, refer to the link:https://cursor.com/docs/context/mcp[Cursor Documentation, window=_blank]. ++ +[source,JSON] +---- +{ + "mcpServers": { + "SpotterCode": { + "url": "{SpotterCode-MCP_Server URL}" + } + } +} +---- +. Click *Save* and close the `mcp.json` file. This will install the SpotterCode MCP server and tools for the AI models on Cursor to execute. ++ +If the configuration is valid and successful, you'll see the SpotterCode MCP server in the list of **Installed MCP Servers** on the **Tools & MCP** page. + +. To view the MCP tools, on the **Tools & MCP** page, click **Installed MCP Servers**. As you hover over each skill, you can view the description of the skill and supported parameters for agentic queries. You can also disable the MCP skills that you don't want the AI model to use. + ++ +[div videoContainer] +-- +video::./images/cursor_mcp-skills.mp4[width=100%,options="autoplay,loop"] +-- + +=== Integrate SpotterCode with Visual Studio Code + +Although you can configure the MCP server in Visual Studio Code, to start a chat session with the AI agent, you'll need GitHub Copilot or a similar extension. + +To add an MCP Server to Visual Studio Code, you can use the Extensions view, the `MCP: Add Server` command via command palette, or directly edit the `mcp.json` file in your workspace configuration. + +[source,JSON] +---- +{ + "servers": { + "SpotterCode": { + "url": "{SpotterCode-MCP_Server URL}", + "type": "http" + } + } +} +---- + +After you add the MCP server URL, the SpotterCode MCP server will be available in the Extensions view. For more information about MCP server configuration in Visual Studio Code, see link:https://code.visualstudio.com/docs/copilot/customization/mcp-servers[Visual Studio Code Documentation, window=_blank]. + +=== Integrate SpotterCode with Claude Code +To enable SpotterCode in Claude Code, you can add the SpotterCode MCP server URL using the `claude mcp add` command via Claude CLI. If you are using Claude Desktop, you can add the URL directly to the Claude configuration JSON file: + +[source,JSON] +---- +{ + "mcpServers": { + "SpotterCode": { + "url": "{SpotterCode-MCP_Server URL}", + } + } +} +---- + +For more information about adding MCP servers to Claude Code, see link:https://code.claude.com/docs/en/mcp[Claude Code Documentation, window=_blank]. + +== Verify the integration + +To verify the integration: + +. Open your application project in your IDE. +. Initiate a chat session by selecting the AI model. In your prompt, send a request for getting information about REST APIs or embedding. ++ +In the following example, a chat session with Cursor AI is initiated using the instruction, "I want to embed a ThoughtSpot Liveboard in my React application. Use the available tools to get this information and generate the embed code". Notice how the AI agent uses the SpotterCode skills to get the required information: ++ +[div videoContainer] +-- +video::./images/cursor-chat-session.mp4[width=100%,options="autoplay,loop"] +-- +. Analyze the chat response and review the code. If the responses are not accurate, check for errors and verify whether the Spotter MCP server is accessible and the MCP tools and skills are available to the AI agent in your IDE. ++ +The following example shows how Cursor AI scaffolds the embed code using the SpotterCode skills. Notice that the AI agent identifies and lists the minimum configuration settings, such as the ThoughtSpot host URL, Liveboard ID, and authentication attributes, required to complete the embedding. + ++ +[div videoContainer] +-- +video::./images/cursor-chat-session2.mp4[width=100%,options="autoplay,loop"] +-- +. If you are prompted to provide additional information, specify these details to continue with the embedding as shown in the following example: + ++ +[div videoContainer] +-- +video::./images/cursor-lb-embed.mp4[width=100%,options="autoplay,loop"] +-- +. Notice how the embedding view is produced in a few seconds. +. Try additional prompts to customize and style your embed view. +. Iterate until the integration meets your requirements. + +== Best practices and recommendations + +SpotterCode enriches your development environment with documentation lookup skills and integrates them into your coding experience and agentic workflows. For best results, ThoughtSpot recommends the following guidelines: + +* Provide clear, direct, and specific instructions. If you want a code sample as the output and nothing else, specify this in your prompt. +* Avoid multiple task requests in a single prompt. Break down your questions and precisely explain what you want. +* For best results, use ThoughtSpot terminology such as Liveboards, Spotter, and so on. To receive specific answers and narrow down your request, mention the SpotterCode skill in instructions. For example, "How do I embed a ThoughtSpot page in my app? Use the available SpotterCode tools and skills to get this information". +* Provide contextual information when asking for information or help with a specific action. For example, describe the end goal of the task. If an action must be performed sequentially, use numbered lists or bullet points to ensure the AI agent completes the task as intended. +* Thoroughly review each response. For better results, use the advanced AI models. +* Do not expose sensitive data to AI models. +* Provide additional details and clarifications in the next prompt if you are not getting the desired response. +* Do not rely on SpotterCode to infer business logic that isn’t explicitly defined in the documentation or the SDK. + +== Prompt examples + +For accurate and consistent responses, improve your prompts. + +=== Embedding +The following table shows a list of vague and clear prompt examples for embedding-related questions and tasks. + +[width="100%" cols="4,4"] +[options='header'] +|===== +|Vague prompt|Clear prompt +|How do I embed ThoughtSpot?| I want to embed full ThoughtSpot application in my app. Use the available tools to get this information and generate the embed code. +|I want to use ThoughtSpot in my app.| I want to embed a ThoughtSpot Liveboard in my React application. Use the available tools to get this information and generate the embed code. +|Show me how to use the SDK. | I want to embed ThoughtSpot Spotter Search and AI analytics in my application. Use the 'get-visual-embed-sdk-reference' and 'get-developer-docs-reference' tools to get the information and code samples. +|Give me code for embedding analytics. | Provide an example of embedding the full ThoughtSpot application using AppEmbed. +|How do I add Search? | How do I use the SearchEmbed component to embed a search page with a pre-selected data source? +a| +Tell me how to start the SDK in my app. + +Show me how to use the SDK | How do I initialize the ThoughtSpot Visual Embed SDK in a React application? +|What is the embed code for Liveboard? a| Use the SpotterCode tools and generate the embed code for a Liveboard in a React application + +Give me a code sample for embedding a ThoughtSpot Liveboard using the Visual Embed SDK. +|How do I add a chart in my app?| How do I embed a single chart or table from a ThoughtSpot Liveboard in my application? +|How do I use runtime filters? | Show a code example for embedding a Liveboard with two runtime filters: one for 'Region' set to 'Midwest' and one for 'item type' set to 'Jackets', using the Visual Embed SDK. +|Add an event hook to Liveboard. | Generate a React component that uses the ThoughtSpot embed SDK to display a Liveboard and add an event to trigger filter updates. +|Can I customize the embed?| Fetch the documentation for the LiveboardEmbed class and summarize the available customization options. +a|How do I update my code? + + +Update to new version +|Update my embed code using the latest Visual Embed SDK version and highlight any breaking changes from the documentation. +a| Show me an example with filters + + +Add filters to my embed +a| +* List all supported runtime filter operators and provide code examples for each using the SDK. +* Show how to apply an OR condition in runtime filters for product names containing 'bag' or 'jackets' in the embed code. +* Explain how to embed a Liveboard with a date filter using epoch time format, and show a code sample. +|Give me code for embedding analytics | Provide a code snippet to embed Spotter and pass a search query string as a prop +a| Change the Liveboard layout + +Make my embed dynamic +a| Show how to customize the Liveboard breakpoint width and explain the impact. + +Show me how to customize the layout of charts in the embedded Liveboard. +|Add custom styles to buttons| Change the background color of the Call To Action (CTA) buttons in the embed view to Cerulean blue (#2A52BE). +|===== + +=== REST APIs +The following table shows a list of vague and clear prompt examples for REST APIs. + +[width="100%" cols="4,4"] +[options='header'] +|===== +|Vague prompt|Clear prompt +|How do I get the dashboards via API| How do I get a list of my Liveboards via ThoughtSpot REST API? +a| Show me how to connect to the API + + +Show me how to use the API a| +Show a cURL example for authenticating to ThoughtSpot REST API v2.0 using OAuth + + +Generate a POST request to /api/rest/2.0/metadata/search, including required headers and body. +|How do I add a user using API? a| +How do I create a new user with admin privileges via REST API? Provide the endpoint, method, and sample payload. +|Get data from a chart via API| Generate a REST API request example to fetch data from a specific chart in a Liveboard. +|What do I need to include in my API request? | What headers are required for a REST API call to ThoughtSpot? List and explain each. +|How do I see new actions in my app? | How do get a list of custom actions added in my embed via REST API? +|===== + + + + + + + + + diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 783645484..c74de781a 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -35,35 +35,10 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '10.15.0.cl', + label: '26.2.0.cl', link: ' ', subLabel: 'Cloud (Latest)', }, - { - label: '10.14.0.cl', - link: '10.14.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-10-14-0-cl.vercel.app/docs/', - }, - { - label: '10.13.0.cl', - link: '10.13.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-10-13-0-cl.vercel.app/docs/', - }, - { - label: '10.10.0.sw', - link: '10.10.0.sw', - subLabel: 'Software (Latest)', - iframeUrl: 'https://visual-embed-sdk-10-10.vercel.app/docs/', - }, - { - label: '10.1.0.sw', - link: '10.1.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-1.vercel.app/docs/', - }, - ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', diff --git a/static/doc-images/images/cursor-chat-response.mp4 b/static/doc-images/images/cursor-chat-response.mp4 new file mode 100644 index 000000000..dcfe07340 Binary files /dev/null and b/static/doc-images/images/cursor-chat-response.mp4 differ diff --git a/static/doc-images/images/cursor-chat-session.mp4 b/static/doc-images/images/cursor-chat-session.mp4 new file mode 100644 index 000000000..89224a63b Binary files /dev/null and b/static/doc-images/images/cursor-chat-session.mp4 differ diff --git a/static/doc-images/images/cursor-chat-session2.mp4 b/static/doc-images/images/cursor-chat-session2.mp4 new file mode 100644 index 000000000..059fd226b Binary files /dev/null and b/static/doc-images/images/cursor-chat-session2.mp4 differ diff --git a/static/doc-images/images/cursor-chat.mp4 b/static/doc-images/images/cursor-chat.mp4 new file mode 100644 index 000000000..059fd226b Binary files /dev/null and b/static/doc-images/images/cursor-chat.mp4 differ diff --git a/static/doc-images/images/cursor-lb-embed.mp4 b/static/doc-images/images/cursor-lb-embed.mp4 new file mode 100644 index 000000000..3ff19ae31 Binary files /dev/null and b/static/doc-images/images/cursor-lb-embed.mp4 differ diff --git a/static/doc-images/images/cursor_mcp-skills.mp4 b/static/doc-images/images/cursor_mcp-skills.mp4 new file mode 100644 index 000000000..a79d95c9b Binary files /dev/null and b/static/doc-images/images/cursor_mcp-skills.mp4 differ diff --git a/static/doc-images/images/mcp-skills.png b/static/doc-images/images/mcp-skills.png new file mode 100644 index 000000000..e9dabc46c Binary files /dev/null and b/static/doc-images/images/mcp-skills.png differ diff --git a/static/doc-images/images/spottercode-embed.png b/static/doc-images/images/spottercode-embed.png new file mode 100644 index 000000000..746765437 Binary files /dev/null and b/static/doc-images/images/spottercode-embed.png differ diff --git a/static/doc-images/images/spottercode-prompt-response.png b/static/doc-images/images/spottercode-prompt-response.png new file mode 100644 index 000000000..ef7fab6a8 Binary files /dev/null and b/static/doc-images/images/spottercode-prompt-response.png differ diff --git a/static/doc-images/images/spottercode-response-2.png b/static/doc-images/images/spottercode-response-2.png new file mode 100644 index 000000000..925061ce0 Binary files /dev/null and b/static/doc-images/images/spottercode-response-2.png differ diff --git a/static/doc-images/images/spottercode-response.png b/static/doc-images/images/spottercode-response.png new file mode 100644 index 000000000..205a7da7e Binary files /dev/null and b/static/doc-images/images/spottercode-response.png differ diff --git a/static/doc-images/images/spottercode-response3.png b/static/doc-images/images/spottercode-response3.png new file mode 100644 index 000000000..f9ffc704a Binary files /dev/null and b/static/doc-images/images/spottercode-response3.png differ diff --git a/static/doc-images/images/spottercode-response4.png b/static/doc-images/images/spottercode-response4.png new file mode 100644 index 000000000..6c34fca98 Binary files /dev/null and b/static/doc-images/images/spottercode-response4.png differ diff --git a/static/doc-images/images/spottercode-skill-selection.png b/static/doc-images/images/spottercode-skill-selection.png new file mode 100644 index 000000000..c16a1d8f2 Binary files /dev/null and b/static/doc-images/images/spottercode-skill-selection.png differ