Merge pull request #8 from railsware/CPL-19831/get-dataflow

[CPL-19831] `get-dataflow` tool

Author: oshchyhol

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "coupler-io-mcp-server",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "main": "index.js",
   "license": "MIT",
   "homepage": "https://coupler.io",
@@ -14,30 +14,30 @@
   },
   "description": "Coupler.io MCP server",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.11.4",
+    "@modelcontextprotocol/sdk": "1.12.1",
     "better-sqlite3": "11.10.0",
     "json-schema-to-zod": "2.6.1",
     "lodash": "4.17.21",
     "pino": "9.7.0",
     "tsx": "4.19.4",
     "url-template": "3.1.1",
     "znv": "0.5.0",
-    "zod": "3.24.4",
+    "zod": "3.25.46",
     "zod-to-json-schema": "3.24.5",
     "zod-validation-error": "3.4.1"
   },
   "devDependencies": {
-    "@eslint/js": "9.27.0",
-    "@modelcontextprotocol/inspector": "0.12.0",
+    "@eslint/js": "9.28.0",
+    "@modelcontextprotocol/inspector": "0.13.0",
     "@types/better-sqlite3": "7.6.13",
-    "@types/lodash": "4.17.16",
-    "@types/node": "22.15.19",
-    "eslint": "9.27.0",
+    "@types/lodash": "4.17.17",
+    "@types/node": "22.15.29",
+    "eslint": "9.28.0",
     "lefthook": "1.11.13",
     "pino-pretty": "13.0.0",
     "typescript": "5.8.3",
-    "typescript-eslint": "8.32.1",
+    "typescript-eslint": "8.33.0",
     "vite-tsconfig-paths": "5.1.4",
-    "vitest": "3.1.3"
+    "vitest": "3.1.4"
   }
 }

package.json

@@ -5,16 +5,18 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import * as getData from '@/tools/get-data'
 import * as getSchema from '@/tools/get-schema'
 import * as listDataflows from '@/tools/list-dataflows'
+import * as getDataflow from '@/tools/get-dataflow'
 
 const TOOL_MAP = {
-  [getData.name]: getData.toolMapEntry,
-  [getSchema.name]: getSchema.toolMapEntry,
-  [listDataflows.name]: listDataflows.toolMapEntry,
+  [getData.name]: getData.handler,
+  [getSchema.name]: getSchema.handler,
+  [listDataflows.name]: listDataflows.handler,
+  [getDataflow.name]: getDataflow.handler,
 }
 
 export const server = new Server({
   name: 'Coupler.io MCP server',
-  version: '0.0.1',
+  version: '0.0.3',
 }, {
   capabilities: {
     tools: {},
@@ -24,12 +26,12 @@ export const server = new Server({
 
 // Look up the tool by name in TOOL_MAP and call its handler
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const tool = TOOL_MAP[request.params.name as keyof typeof TOOL_MAP]
-  if (!tool) {
-    throw new Error(`Tool ${request.params.name} not found`)
+  const handler = TOOL_MAP[request.params.name as keyof typeof TOOL_MAP]
+  if (!handler) {
+    throw new Error(`Handler for tool "${request.params.name}" not found`)
   }
 
-  return await tool.handler(request.params.arguments)
+  return await handler(request.params.arguments)
 })
 
 // List all tools
@@ -40,6 +42,7 @@ server.setRequestHandler(
       getData.toolListEntry,
       getSchema.toolListEntry,
       listDataflows.toolListEntry,
+      getDataflow.toolListEntry,
     ]
   })
 )

src/server/index.ts

@@ -58,8 +58,11 @@ describe('getData', () => {
       isError: false,
       content: [{
         type: 'text',
-        text: JSON.stringify([{ col_0: 1, col_1: 'Test' }])
-      }]
+        text: JSON.stringify([{ col_0: 1, col_1: 'Test' }], null, 2)
+      }],
+      structuredContent: {
+        data: [{ col_0: 1, col_1: 'Test' }]
+      }
     })
   })
 

src/tools/get-data/handler.test.ts

@@ -6,10 +6,10 @@ import { logger } from '@/logger'
 import { textResponse } from '@/util/tool-response'
 import { FileManager } from '@/tools/shared/file-manager'
 
-import { zodSchema } from './input-schema'
+import { zodInputSchema } from './schema'
 
 export const handler = async (params?: Record<string, unknown>): Promise<CallToolResult> => {
-  const validationResult = zodSchema.safeParse(params)
+  const validationResult = zodInputSchema.safeParse(params)
 
   if (!validationResult.success) {
     const error = fromError(validationResult.error)
@@ -41,5 +41,8 @@ export const handler = async (params?: Record<string, unknown>): Promise<CallToo
     db.close()
   }
 
-  return textResponse({ text: JSON.stringify(queryResult) })
+  return textResponse({
+    text: JSON.stringify(queryResult, null, 2),
+    structuredContent: { data: queryResult }
+  })
 }

src/tools/get-data/handler.ts

@@ -1,7 +1,7 @@
-import { inputSchema } from './input-schema'
-import { handler } from './handler'
+import { inputSchema, outputSchema } from './schema'
+
+export { handler } from './handler'
 
-export { inputSchema } from './input-schema'
 export const name = 'get-data'
 export const description = 'Get data from a Coupler.io data flow run. Make sure to first query a sample of 5 rows from `data` table, e.g. `SELECT * from data LIMIT 5`, and then run the `get-schema` tool, to better understand the structure. The `get-schema` tool will return the JSON-encoded schema of the `data` table. When visualizing the data, do not try to read any files or fetch any URLs, just generate a static page and use the data you get from the tools.'
 
@@ -10,16 +10,10 @@ const annotations = {
   idempotentHint: true,
 }
 
-export const toolMapEntry = {
-  name,
-  description,
-  inputSchema,
-  handler,
-}
-
 export const toolListEntry = {
   name,
   description,
   inputSchema,
+  outputSchema,
   annotations,
 }

src/tools/get-data/index.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 import { zodToJsonSchema } from 'zod-to-json-schema'
 
-export const zodSchema = z.object({
+export const zodInputSchema = z.object({
   dataflowId: z.string()
     .min(1, 'dataflowId is required')
     .regex(/^\S+$/, 'dataflowId must not contain whitespace')
@@ -16,4 +16,12 @@ export const zodSchema = z.object({
     .describe('The SQL query to run on the data flow sqlite file.'),
 }).strict()
 
-export const inputSchema = zodToJsonSchema(zodSchema)
+export const inputSchema = zodToJsonSchema(zodInputSchema)
+
+const zodOutputSchema = z.object({
+  data: z.array(
+    z.record(z.unknown())
+  ).describe('The data returned from the query.'),
+}).strict()
+
+export const outputSchema = zodToJsonSchema(zodOutputSchema)

src/tools/get-data/input-schema.ts renamed to src/tools/get-data/schema.ts

@@ -0,0 +1,109 @@
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { handler } from './handler'
+
+const createMockResponse = (responseFn: () => Promise<Response>): typeof fetch => {
+  return responseFn
+}
+
+const mockResponse = {
+  id: 'gsheet_dataflow',
+  name: 'GSheet data flow',
+  last_successful_execution_id: '11'
+}
+
+// Response mocks
+const mockGetDataflow = createMockResponse(
+  async () => new Response(
+    JSON.stringify(mockResponse)
+  )
+)
+
+const mockGetDataflowError = createMockResponse(
+  async () => new Response('Error when getting dataflow', { status: 500 })
+)
+
+const mockFetch = vi.spyOn(globalThis, 'fetch')
+
+describe('get-dataflow', () => {
+  beforeEach(async () => {
+    mockFetch.mockReset()
+  })
+
+  afterAll(async () => {
+    mockFetch.mockRestore()
+  })
+
+  it('returns data flow', async () => {
+    mockFetch
+      .mockImplementationOnce(mockGetDataflow)
+
+    const toolResult = await handler({ dataflowId: 'gsheet_dataflow' })
+
+    expect(toolResult).toEqual({
+      isError: false,
+      content: [{
+        type: 'text',
+        text: JSON.stringify(mockResponse, null, 2),
+      }],
+      structuredContent: {
+        dataflow: mockResponse
+      },
+    })
+  })
+
+  describe('with any error', () => {
+    it('returns error message', async () => {
+      mockFetch
+        .mockImplementationOnce(mockGetDataflowError)
+
+      const toolResult = await handler({ dataflowId: 'gsheet_dataflow' })
+
+      expect(toolResult).toEqual({
+        isError: true,
+        content: [{
+          type: 'text',
+          text: 'Failed to get data flow gsheet_dataflow. Response status: 500',
+        }]
+      })
+    })
+  })
+})
+
+describe('with invalid params', () => {
+  it('returns errors on missing parameters', async () => {
+    const toolResult = await handler()
+
+    expect(toolResult).toEqual({
+      isError: true,
+      content: [{
+        type: 'text',
+        text: 'Invalid parameters for get-dataflow tool. Validation error: Required',
+      }]
+    })
+  })
+
+  it('returns error on missing dataflowId', async () => {
+    const toolResult = await handler({})
+
+    expect(toolResult).toEqual({
+      isError: true,
+      content: [{
+        type: 'text',
+        text: 'Invalid parameters for get-dataflow tool. Validation error: Required at "dataflowId"',
+      }]
+    })
+  })
+
+  it('returns error on invalid dataflowId or extraneous parameters', async () => {
+    const toolResult = await handler({ dataflowId: 123, executionId: true })
+
+    expect(toolResult).toEqual({
+      isError: true,
+      content: [{
+        type: 'text',
+        text: "Invalid parameters for get-dataflow tool. Validation error: Expected string, received number at \"dataflowId\"; Unrecognized key(s) in object: 'executionId'"
+      }]
+    })
+  })
+})

src/tools/get-dataflow/handler.test.ts

@@ -0,0 +1,46 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+
+import { zodInputSchema } from './schema'
+
+import { logger } from '@/logger'
+import { textResponse } from '@/util/tool-response'
+import { COUPLER_ACCESS_TOKEN } from '@/env'
+import { CouplerioClient } from '@/lib/couplerio-client'
+import { fromError } from 'zod-validation-error'
+
+export const handler = async (params?: Record<string, unknown>): Promise<CallToolResult> => {
+  const validationResult = zodInputSchema.safeParse(params)
+
+  if (!validationResult.success) {
+    const error = fromError(validationResult.error)
+    logger.error(`Invalid parameters for get-dataflow tool: ${error.toString()}`)
+
+    return textResponse({
+      text: `Invalid parameters for get-dataflow tool. ${error.toString()}`,
+      isError: true,
+    })
+  }
+
+  const coupler = new CouplerioClient({ auth: COUPLER_ACCESS_TOKEN })
+  const response = await coupler.request('/dataflows/{dataflowId}{?type}', {
+    expand: {
+      dataflowId: validationResult.data.dataflowId,
+      type: 'from_template'
+    },
+    request: {
+      method: 'GET'
+    }
+  })
+
+  if (!response.ok) {
+    logger.error(`Failed to get data flow ${validationResult.data.dataflowId}. Response status: ${response.status}`)
+    return textResponse({
+      isError: true,
+      text: `Failed to get data flow ${validationResult.data.dataflowId}. Response status: ${response.status}`
+    })
+  }
+
+  const dataflow = await response.json()
+
+  return textResponse({ text: JSON.stringify(dataflow, null, 2), structuredContent: { dataflow } })
+}

src/tools/get-dataflow/handler.ts

@@ -0,0 +1,18 @@
+import { inputSchema, outputSchema } from './schema'
+
+export { handler } from './handler'
+
+export const name = 'get-dataflow'
+export const description = 'Get a Coupler.io data flow by ID.'
+
+const annotations = {
+  title: 'Get a Coupler.io data flow by ID.'
+}
+
+export const toolListEntry = {
+  name,
+  description,
+  inputSchema,
+  outputSchema,
+  annotations,
+}

src/tools/get-dataflow/index.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+
+export const zodInputSchema = z.object({
+  dataflowId: z.string()
+    .min(1, 'dataflowId is required.')
+    .regex(/^\S+$/, 'dataflowId must not be empty.')
+    .describe('The ID of the data flow with a successful run.')
+}).strict()
+
+export const inputSchema = zodToJsonSchema(zodInputSchema)
+
+const zodOutputSchema = z.object({
+  dataflow: z.object({
+    id: z.string().describe('The ID of the data flow.'),
+    name: z.string().describe('The name of the data flow.'),
+    last_successful_execution_id: z.string().describe('The ID of the last successful run (execution) of the data flow.'),
+    schedule: z.string().describe('The schedule of the data flow. Crontab format.'),
+    sources: z.array(z.object({
+      id: z.string().describe('The ID of the source.'),
+      name: z.string().describe('The name of the source.'),
+      type: z.string().describe('The type of the source.'),
+      params_configured: z.boolean().describe('Whether the source params are configured.'),
+      enabled: z.boolean().describe('Whether the source is enabled.'),
+      data_connections_count: z.number().int().nonnegative().describe('The number of data connections for the source.'),
+      last_success_run_at: z.string().describe('The date and time of the last successful run of the source. ISO 8601 format.'),
+      error_details: z.string().describe('The error details of the source.'),
+    })).describe('The sources of the data flow.'),
+  }).strict()
+})
+
+export const outputSchema = zodToJsonSchema(zodOutputSchema)