Use Spotter3 apis for beta api version

Author: shikharbsar

README.md

@@ -321,25 +321,66 @@ Make sure to add the following entries in your ThoughtSpot instance:
    npm run dev
    ```
 
+### Adding New Tools
+
+When adding new MCP tools to the server:
+
+1. **Define schemas and tools** in `src/servers/tool-definitions.ts`
+2. **Implement handlers** in `src/servers/mcp-server.ts`
+3. **Update version registry** in `src/servers/version-registry.ts`:
+   - Add new tools to appropriate version(s) in `VERSION_REGISTRY`
+   - For new stable features, update `DEFAULT_VERSION`
+   - For beta features, add to the `beta` version entry
+4. **Add tests** for new tools and version configurations
+5. **Update documentation** in README.md
+
+**Important:** The version registry controls which tools are available in each API version. Make sure to add new tools to the correct version configuration to ensure they're accessible to users.
+
 ### Endpoints
 
 **OAuth-based endpoints:**
-- `/mcp`: MCP HTTP Streaming endpoint (supports `?api-version=beta`)
-- `/sse`: Server-sent events for MCP (supports `?api-version=beta`)
+- `/mcp`: MCP HTTP Streaming endpoint (supports `?api-version`)
+- `/sse`: Server-sent events for MCP (supports `?api-version`)
 - `/api`: MCP tools exposed as HTTP endpoints
 - `/authorize`, `/token`, `/register`: OAuth endpoints
 
 **Token-based endpoints (Recommended for APIs):**
-- `/token/mcp`: MCP HTTP Streaming with bearer auth (supports `?api-version=beta`)
-- `/token/sse`: Server-sent events with bearer auth (supports `?api-version=beta`)
+- `/token/mcp`: MCP HTTP Streaming with bearer auth (supports `?api-version`)
+- `/token/sse`: Server-sent events with bearer auth (supports `?api-version`)
 
 **Deprecated endpoints:**
 - `/bearer/mcp`, `/bearer/sse`: Legacy MCP endpoints with bearer auth (**deprecated**, no `api-version` support). Use `/token/*` endpoints instead.
 
-**Beta Tools Access:**
+**API Versioning:**
+
+The ThoughtSpot MCP Server supports API versioning to access different tool sets. You can specify the version using the `api-version` query parameter on OAuth and `/token/*` endpoints (not supported on deprecated `/bearer/*` endpoints).
+
+**Version Formats:**
+- **Beta version**: `?api-version=beta` - Access the latest beta features
+- **Date-based version**: `?api-version=YYYY-MM-DD` - Access tools from a specific release date or the latest version on or before that date
+- **Default** (no parameter): Returns the stable default tool set
+
+**Examples:**
+```bash
+# Beta version (latest experimental features)
+https://agent.thoughtspot.app/token/mcp?api-version=beta
+
+# Specific date version (Spotter3 agent tools)
+https://agent.thoughtspot.app/token/mcp?api-version=2025-03-01
+
+# Date range resolution (returns latest version ≤ specified date)
+https://agent.thoughtspot.app/token/mcp?api-version=2025-03-15
+
+# Default version (stable tools)
+https://agent.thoughtspot.app/token/mcp
+```
+
+**Available Versions:**
+- `beta`: Latest beta features with Spotter3 agent conversation tools
+- `2025-03-01`: Spotter3 agent conversation tools (`createConversation`, `sendConversationMessage`, `getConversationUpdates`)
+- `2024-12-01`: Base MCP tools (`getRelevantQuestions`, `getAnswer`, `getDataSourceSuggestions`)
+- `default`: Stable base tools (same as `2024-12-01`)
 
-To access beta tools, append `?api-version=beta` to any MCP endpoint (except deprecated `/bearer/*` endpoints):
-- Example: `https://agent.thoughtspot.app/token/mcp?api-version=beta`
-- Beta tools include experimental features
+**Note:** The `/bearer/*` endpoints always return the default stable tool set and ignore the `api-version` parameter for backward compatibility.
 
 MCP Server, © ThoughtSpot, Inc. 2025

package-lock.json

@@ -54,7 +54,6 @@
     "@modelcontextprotocol/sdk": "^1.20.1",
     "@thoughtspot/rest-api-sdk": "^2.22.0",
     "agents": "^0.2.14",
-    "ai": "^6.0.138",
     "hono": "^4.10.3",
     "rxjs": "^7.8.2",
     "yaml": "^2.7.1",

package.json

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { toolDefinitionsMCPServer } from "../servers/mcp-server";
+import { toolDefinitionsMCPServer } from "../servers/tool-definitions";
 import { capitalize } from "../utils";
 
 export const openApiSpecHandler = new Hono();

src/api-schemas/open-api-spec.ts

@@ -41,30 +41,32 @@ function handleTokenAuth(
 	const clientName =
 		req.headers.get("x-ts-client-name") || "Bearer Token client";
 
+	const url = new URL(req.url);
+
 	// Build props object
 	const props: any = {
 		accessToken: accessToken,
 		instanceUrl: validateAndSanitizeUrl(tsHost),
 		clientName,
 	};
 
-	// Add api-version support only for /token endpoints
+	// Add api-version support only for /token endpoints (supports "beta" or "YYYY-MM-DD" format)
 	if (supportApiVersion) {
-		const url = new URL(req.url);
 		const apiVersion = url.searchParams.get("api-version");
-		if (apiVersion === "beta") {
-			props.apiVersion = "beta" as const;
+		if (apiVersion) {
+			props.apiVersion = apiVersion;
 		}
 	}
 
 	(ctx as any).props = props;
 
 	// Route to appropriate handler
-	if (req.url.endsWith("/mcp") || req.url.includes("/mcp?")) {
+	const pathname = url.pathname;
+	if (pathname.endsWith("/mcp")) {
 		return MCPServer.serve("/mcp").fetch(req, env, ctx);
 	}
 
-	if (req.url.endsWith("/sse") || req.url.includes("/sse?")) {
+	if (pathname.endsWith("/sse")) {
 		return MCPServer.serveSSE("/sse").fetch(req, env, ctx);
 	}
 

src/bearer.ts

@@ -38,6 +38,7 @@ export const ThoughtSpotOpenAIDeepResearchMCP = instrumentedMCPServer(
 function createMCPRouter(
 	path: string,
 	serverClass: typeof ThoughtSpotMCP,
+	serveMethod: "serve" | "serveSSE",
 	options?: { binding?: string },
 ) {
 	return {
@@ -49,64 +50,33 @@ function createMCPRouter(
 			const url = new URL(request.url);
 			const apiVersion = url.searchParams.get("api-version");
 
-			// Inject apiVersion into props if it's "beta"
-			if (apiVersion === "beta") {
+			// Inject apiVersion into props if provided (supports "beta" or "YYYY-MM-DD" format)
+			if (apiVersion) {
 				const originalProps = (ctx as any).props || {};
 				(ctx as any).props = {
 					...originalProps,
-					apiVersion: "beta" as const,
+					apiVersion,
 				};
 			}
 
 			// Route to the appropriate serve method
-			return serverClass.serve(path, options).fetch(request, env, ctx);
-		},
-	};
-}
-
-// Router function for SSE endpoints
-function createMCPRouterSSE(
-	path: string,
-	serverClass: typeof ThoughtSpotMCP,
-	options?: { binding?: string },
-) {
-	return {
-		async fetch(
-			request: Request,
-			env: Env,
-			ctx: ExecutionContext,
-		): Promise<Response> {
-			const url = new URL(request.url);
-			const apiVersion = url.searchParams.get("api-version");
-
-			// Inject apiVersion into props if it's "beta"
-			if (apiVersion === "beta") {
-				const originalProps = (ctx as any).props || {};
-				(ctx as any).props = {
-					...originalProps,
-					apiVersion: "beta" as const,
-				};
-			}
-
-			// Route to the appropriate serveSSE method
-			return serverClass.serveSSE(path, options).fetch(request, env, ctx);
+			return serverClass[serveMethod](path, options).fetch(request, env, ctx);
 		},
 	};
 }
 
 // Create the OAuth provider instance
 const oauthProvider = new OAuthProvider({
 	apiHandlers: {
-		"/mcp": createMCPRouter("/mcp", ThoughtSpotMCP) as any,
-		"/sse": createMCPRouterSSE("/sse", ThoughtSpotMCP) as any,
+		"/mcp": createMCPRouter("/mcp", ThoughtSpotMCP, "serve") as any,
+		"/sse": createMCPRouter("/sse", ThoughtSpotMCP, "serveSSE") as any,
 		"/openai/mcp": ThoughtSpotOpenAIDeepResearchMCP.serve("/openai/mcp", {
 			binding: "OPENAI_DEEP_RESEARCH_MCP_OBJECT",
 		}) as any, // TODO: Remove 'any'
 		"/openai/sse": ThoughtSpotOpenAIDeepResearchMCP.serveSSE("/openai/sse", {
 			binding: "OPENAI_DEEP_RESEARCH_MCP_OBJECT",
 		}) as any, // TODO: Remove 'any'
 		"/api": apiServer as any, // TODO: Remove 'any'
-		"/bearer/mcp": withBearerHandler(handler, ThoughtSpotMCP) as any,
 	},
 	defaultHandler: withBearerHandler(handler, ThoughtSpotMCP) as any, // TODO: Remove 'any'
 	authorizeEndpoint: "/authorize",

src/index.ts

@@ -8,7 +8,7 @@ import {
 	CreateLiveboardSchema,
 	GetAnswerSchema,
 	GetRelevantQuestionsSchema,
-} from "./mcp-server";
+} from "./tool-definitions";
 
 const apiServer = new Hono<{ Bindings: Env & { props: Props } }>();