add open api spec for tools (#57)

* add open api spec for tools

* address comments -  export tool schemas from respective servers

* fix conflicts

* update README with instructions to connect to glean actions

* add annotations for datasource discovery tool

* return tool definition directly for open ai mcp server

* add glean integration info to public docs

* rename doc file from .txt to .md

Author: shikharbsar

README.md

@@ -157,6 +157,7 @@ For API usage, you would the token endpoints with a `secret_key` to generate the
   - `getRelevantQuestions`: Get relevant data questions from ThoughtSpot analytics based on a user query.
   - `getAnswer`: Get the answer to a specific question from ThoughtSpot analytics.
   - `createLiveboard`: Create a liveboard from a list of answers.
+  - `getDataSourceSuggestions`: Get datasource suggestions for a given query.
 - **MCP Resources**:
    - `datasources`: List of ThoughtSpot Data models the user has access to.
 

package-lock.json

@@ -43,6 +43,7 @@
   },
   "dependencies": {
     "@cloudflare/workers-oauth-provider": "^0.0.5",
+    "@hono/zod-validator": "^0.7.2",
     "@microlabs/otel-cf-workers": "^1.0.0-rc.52",
     "@modelcontextprotocol/sdk": "^1.15.1",
     "@thoughtspot/rest-api-sdk": "^2.13.1",

package.json

@@ -0,0 +1,19 @@
+- Glean actions
+
+To configure the MCP server to be used via glean actions follow these steps:
+
+1. Create a separate action for each the tools exposed through the MCP server
+2. Add open api spec for the tool that you are adding in the functionality section. The openapi spec for each tool is available on this url : https://agent.thoughtspot.app/openapi-spec/tools/{tool_name}. Tool name here would be the name given in the tool set below in [Features](#features). For example, Get relevant data questions tool has name getRelevantQuestions. Note: getDataSourceSuggestions is not yet available as openapi-spec as the feature is not yet Generally Available in ThoughtSpot for all customers. We will add this once it is available.
+3. Select authentication type as Oauth User while configuring the action
+4. Register the glean oauth server with TS MCP server
+
+```bash
+ curl 'https://agent.thoughtspot.app/register' \
+  -H 'accept: */*' \
+  -H 'accept-language: en-US,en;q=0.9' \
+  --data-raw '{"redirect_uris":["${glean_callback_url}"],"token_endpoint_auth_method":"client_secret_basic","grant_types":["authorization_code","refresh_token"],"response_types":["code"],"client_name":"{company_glean_name}","client_uri":"${company_glean_uri}"}'
+```
+5. Add the client_id and client secret obtained from to the glean action auth section. Along with this add https://agent.thoughtspot.app/authorize in client url and https://agent.thoughtspot.app/token in authorize url.
+6. Save the spec and reload the action.
+7. Once the action is saved, we will get an option to run API test. It is recommended to run it one time to make sure everything is setup.
+

public/docs/glean-actions.md

@@ -0,0 +1,170 @@
+import { Hono } from 'hono';
+import { toolDefinitionsMCPServer } from '../servers/mcp-server';
+import { capitalize } from '../utils';
+
+export const openApiSpecHandler = new Hono();
+
+// Helper function to generate tool schema
+const generateToolSchema = (tool: typeof toolDefinitionsMCPServer[0]) => {
+    const schemaName = `${capitalize(tool.name)}Request`;
+    const generatedSchema = { ...tool.inputSchema } as any;
+    generatedSchema.$schema = undefined;
+    return { schemaName, schema: generatedSchema };
+};
+
+// Helper function to generate response schema
+const generateResponseSchema = () => {
+    return {
+        type: 'object',
+        description: 'Response from the API endpoint'
+    };
+};
+
+// Create individual endpoints for each tool
+for (const tool of toolDefinitionsMCPServer) {
+    const { schemaName, schema } = generateToolSchema(tool);
+    const responseSchema = generateResponseSchema();
+
+    openApiSpecHandler.get(`/tools/${tool.name}`, async (c) => {
+        const toolSpec = {
+            openapi: '3.0.0',
+            info: {
+                title: 'ThoughtSpot API',
+                version: '1.0.0',
+                description: 'API for interacting with ThoughtSpot services'
+            },
+            servers: [
+                {
+                    url: '<TS_AGENT_URL>',
+                    description: 'ThoughtSpot agent url'
+                }
+            ],
+            paths: {
+                [`/api/tools/${tool.name}`]: {
+                    post: {
+                        summary: tool.description,
+                        description: tool.description,
+                        operationId: tool.name,
+                        tags: ['Tools'],
+                        requestBody: {
+                            required: true,
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        $ref: `#/components/schemas/${schemaName}`
+                                    }
+                                }
+                            }
+                        },
+                        responses: {
+                            '200': {
+                                description: 'Successful response',
+                                content: {
+                                    'application/json': {
+                                        schema: {
+                                            $ref: `#/components/schemas/${capitalize(tool.name)}Response`
+                                        }
+                                    }
+                                }
+                            },
+                            '400': {
+                                description: 'Bad request - Invalid input parameters'
+                            },
+                            '401': {
+                                description: 'Unauthorized - Invalid or missing authentication'
+                            },
+                            '500': {
+                                description: 'Internal server error'
+                            }
+                        }
+                    }
+                }
+            },
+            components: {
+                schemas: {
+                    [schemaName]: schema,
+                    [`${capitalize(tool.name)}Response`]: responseSchema
+                }
+            }
+        };
+
+        return c.json(toolSpec);
+    });
+}
+
+// Main OpenAPI spec endpoint that combines all tools
+openApiSpecHandler.get('/', async (c) => {
+    const paths: Record<string, any> = {};
+    const schemas: Record<string, any> = {};
+
+    // any tool added to the toolDefinitionsMCPServer will be added to the openapi spec automatically
+    // the api server path should be /api/tools/<tool-name>
+    for (const tool of toolDefinitionsMCPServer) {
+        const { schemaName, schema } = generateToolSchema(tool);
+        const responseSchema = generateResponseSchema();
+
+        schemas[schemaName] = schema;
+        schemas[`${capitalize(tool.name)}Response`] = responseSchema;
+        
+        paths[`/api/tools/${tool.name}`] = {
+            post: {
+                summary: tool.description,
+                description: tool.description,
+                operationId: tool.name,
+                tags: ['Tools'],
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: {
+                                $ref: `#/components/schemas/${schemaName}`
+                            }
+                        }
+                    }
+                },
+                responses: {
+                    '200': {
+                        description: 'Successful response',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    $ref: `#/components/schemas/${capitalize(tool.name)}Response`
+                                }
+                            }
+                        }
+                    },
+                    '400': {
+                        description: 'Bad request - Invalid input parameters'
+                    },
+                    '401': {
+                        description: 'Unauthorized - Invalid or missing authentication'
+                    },
+                    '500': {
+                        description: 'Internal server error'
+                    }
+                }
+            }
+        };
+    }
+
+    const openApiDocument = {
+        openapi: '3.0.0',
+        info: {
+            title: 'ThoughtSpot API',
+            version: '1.0.0',
+            description: 'API for interacting with ThoughtSpot services'
+        },
+        servers: [
+            {
+                url: '<TS_AGENT_URL>',
+                description: 'ThoughtSpot agent url'
+            }
+        ],
+        paths: paths,
+        components: {
+            schemas: schemas
+        }
+    };
+
+    return c.json(openApiDocument);
+}); 

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

@@ -8,6 +8,7 @@ import { any } from 'zod';
 import { encodeBase64Url, decodeBase64Url } from 'hono/utils/encode';
 import { getActiveSpan, WithSpan } from './metrics/tracing/tracing-utils';
 import { context, type Span, SpanStatusCode, trace } from "@opentelemetry/api";
+import { openApiSpecHandler } from './api-schemas/open-api-spec';
 
 const app = new Hono<{ Bindings: Env & { OAUTH_PROVIDER: OAuthHelpers } }>()
 
@@ -263,4 +264,6 @@ app.post("/store-token", async (c) => {
     }
 });
 
+app.route('/openapi-spec', openApiSpecHandler);
+
 export default app;

src/handlers.ts

@@ -1,10 +1,10 @@
 import { Hono } from 'hono'
+import { zValidator } from '@hono/zod-validator'
 import type { Props } from '../utils';
-import { McpServerError } from '../utils';
-import { getDataSources, ThoughtSpotService } from '../thoughtspot/thoughtspot-service';
+import { ThoughtSpotService } from '../thoughtspot/thoughtspot-service';
 import { getThoughtSpotClient } from '../thoughtspot/thoughtspot-client';
 import { getActiveSpan, WithSpan } from '../metrics/tracing/tracing-utils';
-import { context, type Span, SpanStatusCode, trace } from "@opentelemetry/api";
+import { CreateLiveboardSchema, GetAnswerSchema, GetRelevantQuestionsSchema } from './mcp-server';
 
 const apiServer = new Hono<{ Bindings: Env & { props: Props } }>()
 
@@ -35,9 +35,9 @@ class ApiHandler {
     }
 
     @WithSpan('api-create-liveboard')
-    async createLiveboard(props: Props, name: string, answers: any[]) {
+    async createLiveboard(props: Props, name: string, answers: any[], noteTileParsedHtml: string) {
         const service = this.getThoughtSpotService(props);
-        const result = await service.fetchTMLAndCreateLiveboard(name, answers);
+        const result = await service.fetchTMLAndCreateLiveboard(name, answers, noteTileParsedHtml);
         return result.url || '';
     }
 
@@ -88,25 +88,51 @@ class ApiHandler {
 
 const handler = new ApiHandler();
 
-apiServer.post("/api/tools/relevant-questions", async (c) => {
-    const { props } = c.executionCtx;
-    const { query, datasourceIds, additionalContext } = await c.req.json();
-    const questions = await handler.getRelevantQuestions(props, query, datasourceIds, additionalContext);
-    return c.json(questions);
-});
-
-apiServer.post("/api/tools/get-answer", async (c) => {
-    const { props } = c.executionCtx;
-    const { question, datasourceId } = await c.req.json();
-    const answer = await handler.getAnswer(props, question, datasourceId);
-    return c.json(answer);
-});
+apiServer.post(
+    "/api/tools/relevant-questions",
+    zValidator('json', GetRelevantQuestionsSchema),
+    async (c) => {
+        const { props } = c.executionCtx;
+        const { query, datasourceIds, additionalContext } = c.req.valid('json');
+        const questions = await handler.getRelevantQuestions(props, query, datasourceIds, additionalContext);
+        return c.json(questions);
+    }
+);
+
+apiServer.post(
+    "/api/tools/get-answer",
+    zValidator('json', GetAnswerSchema),
+    async (c) => {
+        const { props } = c.executionCtx;
+        const { question, datasourceId } = c.req.valid('json');
+        const answer = await handler.getAnswer(props, question, datasourceId);
+        return c.json(answer);
+    }
+);
+
+apiServer.post(
+    "/api/tools/create-liveboard",
+    zValidator('json', CreateLiveboardSchema),
+    async (c) => {
+        const { props } = c.executionCtx;
+        const { name, answers, noteTile } = c.req.valid('json');
+        const liveboardUrl = await handler.createLiveboard(props, name, answers, noteTile);
+        return c.text(liveboardUrl);
+    }
+);
 
-apiServer.post("/api/tools/create-liveboard", async (c) => {
+apiServer.get("/api/tools/ping", async (c) => {
     const { props } = c.executionCtx;
-    const { name, answers } = await c.req.json();
-    const liveboardUrl = await handler.createLiveboard(props, name, answers);
-    return c.text(liveboardUrl);
+    console.log("Received Ping request");
+    if (props.accessToken && props.instanceUrl) {
+        return c.json({
+            content: [{ type: "text", text: "Pong" }],
+        });
+    }
+    return c.json({
+        isError: true,
+        content: [{ type: "text", text: "ERROR: Not authenticated" }],
+    });
 });
 
 apiServer.get("/api/resources/datasources", async (c) => {