Tally MCP

<!-- Generated by SpecStory --> # Create PRD for Tally.so API server (2025-06-05 10:04:31) _**User**_ I want to create a cloud-hosted model context protocol server to interact with Tally.so's API. The primary goal is helping the user create and modify forms through natural language. The server should be deployable in the cloud. I've included a complete reference guide that you can investigate here: @/Building and Deploying Cloud-Based MCP Servers Here's Tally's API documentation: @https://developers.tally.so/api-reference/introduction Please help me create a complete PRD in `.taskmaster/docs/prd.txt` You can base it on the template here: @example_prd.txt --- _**Assistant**_ --- I'll create a comprehensive PRD for your Tally.so MCP server project. Let me analyze the requirements and create a detailed product requirements document. --- ```diff - + # Tally.so MCP Server - Product Requirements Document + + # Overview + The Tally.so MCP Server is a cloud-hosted Model Context Protocol server that enables AI assistants to interact with Tally.so's form builder platform through natural language. This server bridges the gap between conversational AI and form management, allowing users to create, modify, and manage Tally forms using simple natural language commands within AI applications like Cursor, Claude Desktop, or other MCP-compatible clients. + + The server solves the complexity of form creation by translating natural language requests into specific Tally API calls, making form building accessible to non-technical users while providing powerful automation capabilities for developers. Users can describe their form requirements in plain English and have complete, functional forms created automatically with proper validation, styling, and integration capabilities. + + # Core Features + + ## Natural Language Form Creation + - **Form Builder Tool**: Converts natural language descriptions into complete Tally forms with appropriate question types, validation rules, and logical flow + - **Question Generation**: Automatically generates appropriate question types (text, multiple choice, rating, file upload, etc.) based on user intent + - **Smart Field Mapping**: Intelligently maps user requirements to Tally's field types and validation options + - **Form Logic**: Implements conditional logic and branching based on natural language descriptions + + ## Form Management and Modification + - **Form Editor Tool**: Allows modification of existing forms through natural language commands ("add a phone number field", "make email required") + - **Bulk Operations**: Enables batch modifications across multiple forms or form elements + - **Form Templates**: Provides pre-built form templates for common use cases (contact forms, surveys, registration forms) + - **Version Control**: Maintains form versioning and allows rollback to previous configurations + + ## Data and Analytics Access + - **Submission Viewer**: Retrieves and formats form submissions in readable formats for AI analysis + - **Analytics Tool**: Provides form performance metrics, completion rates, and submission analytics + - **Export Functionality**: Exports form data in various formats (CSV, JSON) for further processing + - **Real-time Monitoring**: Tracks form activity and provides live submission notifications + + ## Workspace and Organization Management + - **Workspace Tools**: Manages Tally workspaces, user permissions, and organizational structure + - **Collaboration Features**: Handles team member invitations, role assignments, and access control + - **Form Sharing**: Manages form publication, sharing settings, and embed code generation + - **Webhook Management**: Configures and manages webhooks for form submissions and events + + # User Experience + + ## Primary User Personas + - **Business Users**: Non-technical professionals who need to create forms quickly for surveys, lead generation, event registration, or feedback collection + - **Developers**: Technical users who want to integrate form creation into automated workflows or applications + - **Marketing Teams**: Teams that need to rapidly deploy landing page forms, campaign forms, and conversion tracking + - **Customer Success**: Teams managing customer onboarding, feedback collection, and support ticket creation + + ## Key User Flows + + ### Form Creation Flow + 1. User describes form requirements in natural language: "Create a customer feedback form with rating questions for service quality, delivery speed, and overall satisfaction, plus a comment field" + 2. MCP server analyzes the request and identifies required form elements + 3. Server creates form structure using Tally API with appropriate question types + 4. User receives confirmation with form URL and embed options + 5. Optional: User requests modifications through follow-up natural language commands + + ### Form Modification Flow + 1. User references existing form: "Modify the customer feedback form to add a phone number field before the comments" + 2. Server retrieves current form structure from Tally API + 3. Server applies requested modifications while preserving existing data and logic + 4. User receives updated form confirmation with change summary + + ### Data Analysis Flow + 1. User requests form data: "Show me all submissions from the customer feedback form from last week" + 2. Server retrieves submissions using Tally API with appropriate filters + 3. Server formats data for AI analysis and presents summary insights + 4. User can request specific analytics or export options + + ## UI/UX Considerations + - **Natural Language Interface**: All interactions use conversational language rather than technical form builder terminology + - **Context Awareness**: Server maintains context about previously created or modified forms within conversation sessions + - **Error Handling**: Provides clear, actionable error messages when API limits are reached or invalid configurations are requested + - **Progressive Enhancement**: Supports both simple and complex form creation scenarios with appropriate guidance + + # Technical Architecture + + ## System Components + + ### MCP Server Core + - **Node.js/TypeScript** runtime with MCP SDK integration + - **Express.js** middleware for HTTP transport (SSE) support + - **Zod** validation for input schemas and API response validation + - **Axios** HTTP client for Tally API communication with retry logic + - **JWT** handling for Tally API authentication and token refresh + + ### Tool Implementations + - **Form Creation Tool**: Parses natural language, maps to Tally form schema, validates requirements + - **Form Modification Tool**: Retrieves existing forms, applies incremental changes, handles field dependencies + - **Submission Analysis Tool**: Fetches submission data, applies filtering, formats for AI consumption + - **Workspace Management Tool**: Handles organizational operations, user management, permission controls + + ### Authentication & Security + - **OAuth 2.0** integration with Tally's authentication system + - **API Key Management** for secure storage and rotation of Tally API credentials + - **Rate Limiting** to respect Tally's API limits and prevent abuse + - **Input Sanitization** for all user inputs to prevent injection attacks + + ## Data Models + + ### Form Configuration Schema + ```typescript + interface FormConfig { + title: string; + description?: string; + questions: QuestionConfig[]; + settings: FormSettings; + branding?: BrandingConfig; + } + + interface QuestionConfig { + type: 'text' | 'email' | 'number' | 'choice' | 'rating' | 'file' | 'date'; + label: string; + required: boolean; + validation?: ValidationRules; + options?: string[]; // for choice questions + logic?: ConditionalLogic; + } + ``` + + ### API Response Models + - Tally API response schemas for forms, submissions, workspaces + - Error handling schemas for API failures and validation errors + - Webhook payload schemas for real-time event processing + + ## APIs and Integrations + + ### Tally.so API Integration + - **Base URL**: `https://api.tally.so` + - **Authentication**: Bearer token authentication with automatic refresh + - **Rate Limits**: Respect Tally's rate limiting (specific limits TBD from API documentation) + - **Endpoints**: Forms, Questions, Submissions, Workspaces, Organizations, Webhooks + + ### MCP Protocol Implementation + - **Transport**: Server-Sent Events (SSE) for cloud deployment compatibility + - **Tools**: Expose all form management capabilities as MCP tools + - **Resources**: Provide access to form templates, submission data, and analytics + - **Prompts**: Pre-defined prompt templates for common form creation scenarios + + ## Infrastructure Requirements + + ### Hosting Platform Options + - **Primary**: Cloudflare Workers for global edge deployment and enterprise scalability + - **Alternative 1**: Glama.ai for MCP-focused hosting with community features + - **Alternative 2**: Smithery for registry-based deployment and developer tools + + ### Environmental Configuration + - Production environment variables for API keys, database connections, logging + - Docker containerization for consistent deployment across platforms + - CI/CD pipeline integration for automated testing and deployment + - Monitoring and alerting for API usage, error rates, and performance metrics + + # Development Roadmap + + ## Phase 1: MVP Core Functionality (Foundation) + - Basic MCP server setup with Tally API authentication + - Simple form creation tool that converts basic natural language to Tally forms + - Support for common question types (text, email, multiple choice) + - Basic error handling and input validation + - Local testing environment with MCP Inspector + - Documentation for setup and basic usage + + ## Phase 2: Enhanced Form Management + - Advanced form modification capabilities (add/remove/reorder questions) + - Support for all Tally question types and validation options + - Form template system with pre-built common forms + - Conditional logic implementation for dynamic forms + - Form styling and branding options + - Workspace and organization management tools + + ## Phase 3: Data and Analytics Integration + - Submission retrieval and analysis tools + - Form performance analytics and metrics + - Data export functionality in multiple formats + - Real-time submission monitoring via webhooks + - Advanced filtering and search capabilities for submissions + - Integration with external analytics platforms + + ## Phase 4: Production Deployment and Scaling + - Cloud deployment to chosen hosting platform (Cloudflare Workers) + - Production-grade authentication and security implementation + - Rate limiting and abuse prevention mechanisms + - Comprehensive monitoring, logging, and alerting + - API documentation and developer resources + - Performance optimization and caching strategies + + ## Phase 5: Advanced Features and Integrations + - Bulk form operations and batch processing + - Integration with other popular form platforms for migration + - Advanced AI-powered form optimization suggestions + - Multi-language support for international forms + - A/B testing capabilities for form variations + - Enterprise features (SSO, advanced permissions, audit logs) + + # Logical Dependency Chain + + ## Foundation Layer (Phase 1) + 1. **Environment Setup**: Project initialization, dependency management, development environment + 2. **MCP Server Core**: Basic server structure, transport configuration, health checks + 3. **Tally API Client**: Authentication, basic API wrapper, error handling + 4. **Simple Form Tool**: MVP form creation with basic question types + 5. **Local Testing**: MCP Inspector integration, basic validation + + ## Core Features Layer (Phase 2) + 6. **Advanced Form Tools**: Depends on foundation - form modification, templates, all question types + 7. **Form Logic Engine**: Depends on form tools - conditional logic, validation rules + 8. **Workspace Management**: Depends on API client - organization and user management + 9. **Security Enhancement**: Depends on core features - input validation, rate limiting + + ## Data Layer (Phase 3) + 10. **Submission Tools**: Depends on core features - data retrieval and analysis + 11. **Analytics Engine**: Depends on submission tools - metrics and reporting + 12. **Webhook Integration**: Depends on submission tools - real-time monitoring + 13. **Export Functionality**: Depends on analytics - data formatting and delivery + + ## Production Layer (Phase 4) + 14. **Cloud Deployment**: Depends on all previous layers - containerization, CI/CD + 15. **Production Security**: Depends on deployment - OAuth, API key management + 16. **Monitoring System**: Depends on production deployment - logging, alerting, metrics + 17. **Documentation**: Depends on stable features - API docs, user guides + + ## Enhancement Layer (Phase 5) + 18. **Advanced Features**: Depends on production system - bulk operations, integrations + 19. **Enterprise Features**: Depends on advanced features - SSO, audit logs, permissions + 20. **Optimization**: Depends on monitoring data - performance tuning, caching + + # Risks and Mitigations + + ## Technical Challenges + - **API Rate Limiting**: Tally's API may have strict rate limits that could impact user experience + - *Mitigation*: Implement intelligent caching, request queuing, and user communication about delays + - **Natural Language Processing**: Converting complex form requirements into accurate API calls + - *Mitigation*: Start with simple patterns, build comprehensive test cases, implement fallback to manual specification + - **Form Complexity**: Tally's advanced features may not map cleanly to natural language descriptions + - *Mitigation*: Progressive feature rollout, clear documentation of capabilities and limitations + + ## Integration Risks + - **API Changes**: Tally may modify their API without notice, breaking integrations + - *Mitigation*: Version pinning, comprehensive error handling, monitoring for API changes + - **Authentication Issues**: OAuth flows and token management complexity + - *Mitigation*: Robust token refresh logic, fallback authentication methods, clear error messages + + ## Deployment and Scaling Risks + - **Platform Dependencies**: Cloud hosting platforms may have limitations or outages + - *Mitigation*: Multi-platform deployment capability, monitoring and failover procedures + - **Performance Bottlenecks**: High user load could overwhelm server or hit API limits + - *Mitigation*: Load testing, horizontal scaling capabilities, usage analytics and alerting + + ## Business Risks + - **Tally API Access**: Changes to Tally's API availability or pricing + - *Mitigation*: Monitor Tally's developer program, maintain communication with Tally team + - **User Adoption**: Complex setup process could limit adoption + - *Mitigation*: Streamlined onboarding, comprehensive documentation, demo implementations + + # Appendix + + ## Research Findings + - Tally.so provides comprehensive REST API with form CRUD operations, submission management, and webhook support + - MCP ecosystem is rapidly growing with strong support from Anthropic and integration with major AI platforms + - Cloud deployment options (Cloudflare Workers, Glama, Smithery) provide different trade-offs for scalability, cost, and developer experience + + ## Technical Specifications + - **Minimum Node.js Version**: 18.x for modern JavaScript features and MCP SDK compatibility + - **TypeScript**: Latest stable version for type safety and developer experience + - **MCP SDK**: @modelcontextprotocol/sdk for server implementation + - **API Client**: Axios with retry logic and request/response interceptors + - **Validation**: Zod for runtime type checking and schema validation + - **Testing**: Jest for unit tests, MCP Inspector for integration testing + + ## Success Metrics + - **Technical**: API response times <500ms, 99.9% uptime, error rate <1% + - **User Experience**: Form creation time <2 minutes, natural language accuracy >90% + - **Adoption**: Active users, forms created per user, API call volume growth + - **Quality**: User satisfaction scores, support ticket volume, feature request patterns ``` --- I've created a comprehensive PRD for your Tally.so MCP server project. The document includes: ## Key Highlights: **Product Vision**: A cloud-hosted MCP server that enables natural language form creation and management with Tally.so's API, making form building accessible to non-technical users while providing automation for developers. **Core Features**: - Natural language form creation with smart field mapping - Form modification and template system - Data analytics and submission management - Workspace and organization tools **Technical Architecture**: - Node.js/TypeScript with MCP SDK - SSE transport for cloud deployment - Tally.so API integration with OAuth - Support for Cloudflare Workers, Glama, or Smithery deployment **5-Phase Development Roadmap**: 1. **MVP Foundation** - Basic form creation with common question types 2. **Enhanced Management** - Advanced editing, templates, conditional logic 3. **Data Integration** - Analytics, exports, webhooks 4. **Production Deployment** - Cloud hosting, security, monitoring 5. **Advanced Features** - Enterprise capabilities, optimizations **Risk Mitigation**: Addresses API rate limiting, natural language processing challenges, deployment risks, and business continuity concerns. The PRD is now ready for you to initialize your Taskmaster project and begin development. Based on the [reference documentation](https://developers.tally.so/api-reference/introduction), this server will integrate with Tally's comprehensive REST API covering forms, submissions, workspaces, and webhooks. Would you like me to help you initialize the Taskmaster project and start generating tasks from this PRD? --- _**User**_ Please update the @prd.txt with the same xml tag formatting found in @example_prd.txt --- _**Assistant**_ --- I'll update the PRD to match the XML tag formatting structure from the example template. --- --- --- Perfect! I've updated the PRD to match the XML tag formatting structure from the example template: - **`<context>` section**: Contains the Overview, Core Features, and User Experience sections - **`<PRD>` section**: Contains the Technical Architecture, Development Roadmap, Logical Dependency Chain, Risks and Mitigations, and Appendix sections The PRD now follows the proper structure that Taskmaster expects for parsing and task generation. The `<context>` section provides the high-level product understanding, while the `<PRD>` section contains the detailed technical implementation and planning information. Your PRD is now ready for initializing the Taskmaster project and generating development tasks from this comprehensive specification! --- _**User**_ Can you explain the error here? --- _**Assistant**_ --- Looking at this error, there are actually two issues happening: ## Primary Issue: OpenAI Schema Validation Error The main error is with OpenAI's strict JSON schema validation: ``` Invalid schema for function 'json': In context=('properties', 'tasks', 'items'), 'required' is required to be supplied and to be an array including every key in properties. Missing 'details'. ``` **What's happening:** - The Taskmaster tool is trying to generate tasks using OpenAI's structured output (function calling) - OpenAI's API is rejecting the schema because it defines a `details` property in the task object but doesn't include it in the `required` array - Even though `details` has a default value of `""`, OpenAI's strict mode requires ALL properties to be explicitly marked as required or not **The Schema Issue:** ```typescript // Current schema has this structure: { properties: { details: { type: "string", default: "" }, // ... other properties }, required: ["id", "title", "description"] // Missing "details" here } ``` OpenAI's strict mode wants either: 1. `details` removed from properties entirely, OR 2. `details` added to the required array: `["id", "title", "description", "details"]` ## Secondary Issue: Missing Fallback API Keys The error also shows: ``` [WARN] Skipping role 'fallback' (Provider: anthropic): API key not set or invalid. [WARN] Skipping role 'research' (Provider: perplexity): API key not set or invalid. ``` This means when OpenAI fails, Taskmaster can't fall back to other providers because those API keys aren't configured. ## Solutions: 1. **Fix the Schema** (likely requires a Taskmaster update) 2. **Configure Fallback API Keys** in your MCP environment: - Add `ANTHROPIC_API_KEY` to your `.cursor/mcp.json` env section - Add `PERPLEXITY_API_KEY` if you want research capabilities 3. **Temporary Workaround**: Try using a different model that might be less strict with schema validation This appears to be a compatibility issue between Taskmaster's schema definition and OpenAI's newer, stricter validation rules. ---