List Surveys

Instructions

Implementation Reference

• packages/mcp-server/src/index.ts:421-491 (registration)

  Registration of the 'list_surveys' tool via server.registerTool(), defining its title, description, empty inputSchema, and the handler callback function.

  server.registerTool(
    'list_surveys',
    {
      title: 'List Surveys',
      description: 'List all surveys created with the current API key, ordered newest first. Use this to find a survey_id you need for get_results or close_survey, or to check which surveys are still open.',
      inputSchema: {},
    },
    async () => {
      const apiKeyError = requireApiKey()
      if (apiKeyError) {
        return apiKeyError
      }
  
      const response = await fetch(`${API_BASE_URL}/api/surveys`, {
        headers: {
          Authorization: `Bearer ${process.env.HUMANSURVEY_API_KEY}`,
        },
      })
      const payload = (await response.json().catch(() => null)) as
        | SurveyListItem[]
        | { error?: string }
        | null
  
      if (!response.ok || !Array.isArray(payload)) {
        const error = payload && !Array.isArray(payload) ? payload.error : response.statusText
        return {
          content: [
            {
              type: 'text',
              text: `Failed to list surveys: ${error ?? response.statusText}`,
            },
          ],
          isError: true,
        }
      }
  
      if (payload.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: 'No surveys found for this API key.',
            },
          ],
        }
      }
  
      const lines = ['ID          Title                    Status   Responses  Created']
  
      payload.forEach((survey) => {
        lines.push(
          [
            survey.id.padEnd(10),
            truncate(survey.title, 24).padEnd(24),
            (survey.status ?? 'open').padEnd(8),
            String(survey.response_count ?? 0).padEnd(10),
            (survey.created_at ?? '').slice(0, 10),
          ].join('  '),
        )
      })
  
      return {
        content: [
          {
            type: 'text',
            text: lines.join('\n'),
          },
        ],
      }
    },
  )

• packages/mcp-server/src/index.ts:428-490 (handler)

  Handler function for 'list_surveys' that validates API key with requireApiKey(), fetches surveys from the API, checks for errors, handles empty results, and formats the output as a text table with ID, title, status, responses, and created date.

  async () => {
    const apiKeyError = requireApiKey()
    if (apiKeyError) {
      return apiKeyError
    }
  
    const response = await fetch(`${API_BASE_URL}/api/surveys`, {
      headers: {
        Authorization: `Bearer ${process.env.HUMANSURVEY_API_KEY}`,
      },
    })
    const payload = (await response.json().catch(() => null)) as
      | SurveyListItem[]
      | { error?: string }
      | null
  
    if (!response.ok || !Array.isArray(payload)) {
      const error = payload && !Array.isArray(payload) ? payload.error : response.statusText
      return {
        content: [
          {
            type: 'text',
            text: `Failed to list surveys: ${error ?? response.statusText}`,
          },
        ],
        isError: true,
      }
    }
  
    if (payload.length === 0) {
      return {
        content: [
          {
            type: 'text',
            text: 'No surveys found for this API key.',
          },
        ],
      }
    }
  
    const lines = ['ID          Title                    Status   Responses  Created']
  
    payload.forEach((survey) => {
      lines.push(
        [
          survey.id.padEnd(10),
          truncate(survey.title, 24).padEnd(24),
          (survey.status ?? 'open').padEnd(8),
          String(survey.response_count ?? 0).padEnd(10),
          (survey.created_at ?? '').slice(0, 10),
        ].join('  '),
      )
    })
  
    return {
      content: [
        {
          type: 'text',
          text: lines.join('\n'),
        },
      ],
    }
  },

• packages/mcp-server/src/index.ts:13-19 (schema)

  Type definition for SurveyListItem used to type the response payload from the /api/surveys endpoint.

  type SurveyListItem = {
    id: string
    title: string
    status?: string
    response_count?: number
    created_at?: string
  }

• packages/mcp-server/src/index.ts:425-427 (schema)

  Input schema definition for list_surveys — an empty object (no parameters required).

    description: 'List all surveys created with the current API key, ordered newest first. Use this to find a survey_id you need for get_results or close_survey, or to check which surveys are still open.',
    inputSchema: {},
  },

• packages/mcp-server/src/index.ts:585-599 (helper)

  Helper function requireApiKey() that checks for the HUMANSURVEY_API_KEY environment variable and returns an error response if missing.

  function requireApiKey() {
    if (process.env.HUMANSURVEY_API_KEY) {
      return null
    }
  
    return {
      content: [
        {
          type: 'text' as const,
          text: 'No API key found. Call the create_key tool first — it takes no arguments and will provision a key immediately. The key will be active for this session and you can then proceed with create_survey.',
        },
      ],
      isError: true,
    }
  }