Tally MCP

Instructions

Implementation Reference

• src/server.ts:1446-1458 (registration)

  Registers the MCP tool 'get_submissions' with name, description, and input schema specifying formId (required), limit, offset, since parameters.
  name: 'get_submissions', description: 'Retrieve submissions for a specific Tally form', inputSchema: { type: 'object', properties: { formId: { type: 'string', description: 'ID of the form to get submissions for' }, limit: { type: 'number', description: 'Maximum number of submissions to return', minimum: 1, maximum: 100 }, offset: { type: 'number', description: 'Number of submissions to skip for pagination', minimum: 0 }, since: { type: 'string', description: 'Only return submissions created after this ISO 8601 timestamp' } }, required: ['formId'] } },
• src/services/TallyApiClient.ts:409-431 (handler)

  Core handler function that executes the API call to retrieve form submissions from Tally.so API endpoint `/forms/{formId}/submissions` with support for pagination (page, limit) and status filtering. Handles mock mode and response validation.
  public async getSubmissions( formId: string, options: { page?: number; limit?: number; status?: 'all' | 'completed' | 'partial'; } = {} ): Promise<TallySubmissionsResponse> { if (this.isMockEnabled()) { const mockRes = await tallyApiMock.getSubmissions(formId, options); return mockRes.data; } const params = new URLSearchParams(); if (options.page) params.append('page', options.page.toString()); if (options.limit) params.append('limit', options.limit.toString()); if (options.status) params.append('status', options.status); const query = params.toString(); const url = `/forms/${formId}/submissions${query ? `?${query}` : ''}`; const response = await this.get(url); return validateTallyResponse(TallySubmissionsResponseSchema, response.data); }
• src/services/submission-service.ts:21-43 (helper)

  Helper service method wrapping TallyApiClient to fetch form submissions with SubmissionFilters (status, dates, afterId) and pagination.
  public async getFormSubmissions( formId: string, options: SubmissionFilters & { page?: number; limit?: number } = {} ): Promise<TallySubmissionsResponse> { const endpoint = `/forms/${formId}/submissions`; const params: Record<string, any> = { page: options.page, limit: options.limit, filter: options.status, startDate: options.startDate, endDate: options.endDate, afterId: options.afterId, }; return this.apiClient.requestWithValidation( 'GET', endpoint, TallySubmissionsResponseSchema, undefined, params, ); }
• src/validation/validate-project-tools.ts:109-121 (schema)

  Validation schema definition for the 'get_submissions' tool input, matching the registration schema.
  name: 'get_submissions', description: 'Retrieve submissions for a specific Tally form', inputSchema: { type: 'object', properties: { formId: { type: 'string', description: 'ID of the form to get submissions for' }, limit: { type: 'number', description: 'Maximum number of submissions to return', minimum: 1, maximum: 100 }, offset: { type: 'number', description: 'Number of submissions to skip for pagination', minimum: 0 }, since: { type: 'string', description: 'Only return submissions created after this ISO 8601 timestamp' } }, required: ['formId'] } },
• src/tools/submission-tool.ts:45-356 (helper)

  Supporting method in SubmissionAnalysisTool to list submissions by calling SubmissionService.getFormSubmissions.
  public async list(formId: string, filters: SubmissionFilters = {}): Promise<TallySubmission[]> { const response = await this.submissionService.getFormSubmissions(formId, filters); return response.submissions; } public async filterByDateRange(formId: string, startDate: string, endDate: string): Promise<TallySubmission[]> { return this.list(formId, { startDate, endDate }); } public async filterByStatus(formId: string, status: SubmissionStatusFilter): Promise<TallySubmission[]> { return this.list(formId, { status }); } public async formatForAnalysis(formId: string, filters: SubmissionFilters = {}): Promise<FormattedSubmission[]> { const response = await this.submissionService.getFormSubmissions(formId, filters); const questions = response.questions; const submissions = response.submissions; const questionMap = new Map<string, string>(questions.map(q => [q.id, q.title])); return submissions.map(sub => ({ submissionId: sub.id, submittedAt: sub.submittedAt, isCompleted: sub.isCompleted, responses: sub.responses.map(res => ({ questionTitle: questionMap.get(res.questionId) || 'Unknown Question', answer: res.value, })), })); } public async getAverageRating(formId: string, questionTitle: string, filters: SubmissionFilters = {}): Promise<number | null> { const formattedSubmissions = await this.formatForAnalysis(formId, filters); let totalRating = 0; let ratingCount = 0; for (const sub of formattedSubmissions) { for (const res of sub.responses) { if (res.questionTitle === questionTitle && typeof res.answer === 'number') { totalRating += res.answer; ratingCount++; } } } return ratingCount > 0 ? totalRating / ratingCount : null; } public async getResponseDistribution(formId: string, questionTitle: string, filters: SubmissionFilters = {}): Promise<Record<string, number>> { const formattedSubmissions = await this.formatForAnalysis(formId, filters); const distribution: Record<string, number> = {}; for (const sub of formattedSubmissions) { for (const res of sub.responses) { if (res.questionTitle === questionTitle) { const answer = String(res.answer); distribution[answer] = (distribution[answer] || 0) + 1; } } } return distribution; } public async exportToCSV(formId: string, filePath: string, filters: SubmissionFilters = {}): Promise<void> { const formattedSubmissions = await this.formatForAnalysis(formId, filters); if (formattedSubmissions.length === 0) { return; } // Flatten the data for CSV const flattenedData = formattedSubmissions.flatMap(sub => sub.responses.map(res => ({ submissionId: sub.submissionId, submittedAt: sub.submittedAt, isCompleted: sub.isCompleted, questionTitle: res.questionTitle, answer: res.answer })) ); const csv = Papa.unparse(flattenedData); // Ensure the directory exists const dir = path.dirname(filePath); if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true }); } fs.writeFileSync(filePath, csv); } public async exportToJSON(formId: string, filePath: string, filters: SubmissionFilters = {}): Promise<void> { const formattedSubmissions = await this.formatForAnalysis(formId, filters); // Ensure the directory exists const dir = path.dirname(filePath); if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true }); } fs.writeFileSync(filePath, JSON.stringify(formattedSubmissions, null, 2)); } public async search(formId: string, query: string, filters: SubmissionFilters = {}): Promise<FormattedSubmission[]> { const formattedSubmissions = await this.formatForAnalysis(formId, filters); const lowerCaseQuery = query.toLowerCase(); return formattedSubmissions.filter(sub => sub.responses.some(res => String(res.answer).toLowerCase().includes(lowerCaseQuery) ) ); } }