Close Survey

Instructions

Implementation Reference

• packages/mcp-server/src/index.ts:493-501 (registration)

  Registration of the close_survey tool with the MCP server, including its title, description, and input schema.

  server.registerTool(
    'close_survey',
    {
      title: 'Close Survey',
      description: 'Permanently close a survey so it no longer accepts new responses. Use this when you have enough responses or the data collection window has passed. Returns the final response count. Closing is irreversible via MCP — use PATCH /api/surveys/{id} to re-open.',
      inputSchema: {
        survey_id: z.string().min(1).describe('The survey ID to close'),
      },
    },

• packages/mcp-server/src/index.ts:502-581 (handler)

  Handler function that fetches the survey, PATCHes it to 'closed' status, then fetches response count and returns a confirmation message.

    async ({ survey_id: surveyId }) => {
      const apiKeyError = requireApiKey()
      if (apiKeyError) {
        return apiKeyError
      }
  
      const surveyResponse = await fetch(`${API_BASE_URL}/api/surveys/${encodeURIComponent(surveyId)}`)
      const surveyPayload = (await surveyResponse.json().catch(() => null)) as
        | { id?: string; title?: string; error?: string }
        | null
  
      if (!surveyResponse.ok || !surveyPayload?.id) {
        return {
          content: [
            {
              type: 'text',
              text: `Failed to fetch survey: ${surveyPayload?.error ?? surveyResponse.statusText}`,
            },
          ],
          isError: true,
        }
      }
  
      const closeResponse = await fetch(`${API_BASE_URL}/api/surveys/${encodeURIComponent(surveyId)}`, {
        method: 'PATCH',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${process.env.HUMANSURVEY_API_KEY}`,
        },
        body: JSON.stringify({ status: 'closed' }),
      })
      const closePayload = (await closeResponse.json().catch(() => null)) as
        | { id?: string; error?: string }
        | null
  
      if (!closeResponse.ok || !closePayload?.id) {
        return {
          content: [
            {
              type: 'text',
              text: `Failed to close survey: ${closePayload?.error ?? closeResponse.statusText}`,
            },
          ],
          isError: true,
        }
      }
  
      const resultsResponse = await fetch(
        `${API_BASE_URL}/api/surveys/${encodeURIComponent(surveyId)}/responses`,
        {
          headers: {
            Authorization: `Bearer ${process.env.HUMANSURVEY_API_KEY}`,
          },
        },
      )
      const resultsPayload = (await resultsResponse.json().catch(() => null)) as
        | { count?: number; error?: string }
        | null
  
      if (!resultsResponse.ok) {
        return {
          content: [
            {
              type: 'text',
              text: `Survey '${surveyPayload.title ?? surveyId}' closed.`,
            },
          ],
        }
      }
  
      return {
        content: [
          {
            type: 'text',
            text: `Survey '${surveyPayload.title ?? surveyId}' closed. Total responses received: ${resultsPayload?.count ?? 0}`,
          },
        ],
      }
    },
  )

• packages/mcp-server/src/index.ts:498-500 (schema)

  Input schema for close_survey: requires a non-empty survey_id string.

  inputSchema: {
    survey_id: z.string().min(1).describe('The survey ID to close'),
  },