README.md

metadata

title: Conversational Form Agent
emoji: 🐠
colorFrom: pink
colorTo: red
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
short_description: MCP-powered conversational agent that replaces traditional f
tags:
  - mcp
  - conversational-ai
  - form-filling
  - track-1

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

💬 Conversational Form Agent - MCP 1st Birthday Hackathon

Track 1: Building with MCP

A revolutionary approach to form filling powered by the Model Context Protocol (MCP). Say goodbye to traditional web forms and hello to intelligent, conversational data collection.

🎯 The Problem

Traditional web forms are:

• Overwhelming: Users face a wall of empty fields
• Inflexible: Fixed order and no guidance
• Error-prone: Validation happens after submission
• Frustrating: No context or help during filling

✨ The Solution

This MCP-powered agent transforms forms into natural conversations:

• Asks questions one at a time
• Validates input immediately
• Provides helpful feedback
• Remembers your progress
• Submits when complete

🏗️ Architecture

Built entirely with the Model Context Protocol (MCP), this project demonstrates how MCP tools can create intelligent, stateful conversational agents.

MCP Tools (5 Required Tools)

1. get_form_schema()

   • Returns the complete form definition as JSON
   • Defines fields, types, validation rules, and prompts

2. get_next_question(filled_data)

   • Intelligently determines which question to ask next
   • Takes already-filled data as input
   • Returns the next unanswered required field

3. validate_answer(field_name, value)

   • Validates user input against field rules
   • Checks data types (email, phone, text, choice)
   • Enforces required fields
   • Returns validation status and error messages

4. save_answer(field_name, value)

   • Stores validated answers in session state
   • Maintains conversation progress
   • Enables recovery from interruptions

5. submit_form(filled_data)

   • Submits the complete form data
   • Generates unique submission ID
   • Returns confirmation message

System Flow

User starts → Agent greets → get_form_schema() → get_next_question()
     ↓
  Ask question
     ↓
User responds → validate_answer()
     ↓
  Valid? → save_answer() → All done? → submit_form() → Success!
     ↓                          ↓
   No? → Show error → Ask again
                         ↓
                      No? → get_next_question() → Continue

🚀 Features

• Conversational Interface: Natural Q&A flow instead of form fields
• Real-time Validation: Immediate feedback on every answer
• Progress Tracking: Always knows where you are in the form
• Smart Navigation: Automatically moves to next question
• Error Handling: Clear, helpful error messages
• Session Management: Remembers your answers
• MCP-Powered: All functionality through MCP tool calls

📋 Current Form Schema

The agent currently handles a Job Application Form with:

• Full Name (text, required)
• Email Address (email format, required)
• Phone Number (phone format, required)
• Years of Experience (number, required)
• Desired Role (choice from list, required)
• Availability (choice from list, required)

🎮 How to Use

1. Launch the Space: This app runs automatically on Hugging Face Spaces
2. Start the conversation: Type "start" or "begin" in the chat
3. Answer questions: The agent asks one question at a time
4. Get validation: Receive immediate feedback on your answers
5. Complete the form: Submit when all questions are answered

Example Interaction

Agent: Welcome! I'll help you complete the job application form. 
       Let's get started!
Agent: What is your full name?

You: John Smith

Agent: Great! What is your email address?

You: john@email

Agent: Invalid email. Please enter a valid email address.

You: john.smith@email.com

Agent: Perfect! What is your phone number? (Format: XXX-XXX-XXXX)

You: 555-123-4567

Agent: Thanks! How many years of experience do you have?

[... continues until form is complete ...]

Agent: Form submitted successfully! Your submission ID is: sub_abc123xyz

🛠️ Technical Stack

• Framework: Gradio 4.0+ (for web interface)
• Protocol: Model Context Protocol (MCP)
• Language: Python 3.10+
• Deployment: Hugging Face Spaces
• Storage: In-memory session state

📁 Project Structure

Conversational-Form-Agent/
├── app.py              # Main Gradio application with MCP tools
├── requirements.txt    # Python dependencies
├── README.md          # This file
└── LICENSE            # MIT License

🏆 Hackathon Compliance (Track 1)

This project fully complies with the MCP 1st Birthday Hackathon requirements:

✅ Track 1: Building with MCP - All functionality implemented as MCP tools ✅ Public Repository - Open source on Hugging Face Spaces ✅ Complete Documentation - Comprehensive README with architecture ✅ Working Demo - Fully functional live application ✅ MCP Tool Specification - 5 required tools implemented and documented ✅ Open Source License - MIT Licensed ✅ Ready for Judging - Deployed and accessible

🔮 Future Enhancements

• Multi-form Support: Handle different form types dynamically
• Conditional Logic: Skip questions based on previous answers
• File Uploads: Support document and image uploads
• Multi-language: Support forms in multiple languages
• Analytics: Track completion rates and drop-off points
• Export Options: Download submissions as JSON/CSV
• Authentication: User accounts with saved progress
• API Integration: Submit to external systems
• Voice Input: Speak your answers instead of typing
• Accessibility: Enhanced screen reader support

📜 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Built for the MCP 1st Birthday Hackathon - Celebrating the Model Context Protocol's first year of enabling intelligent, tool-based AI agents.

---

Ready to try it? Click the "App" tab above to start filling forms the conversational way! 🚀