Add Native MCP Elicitation Support to eSheet

[horner]

Summary

Add first-class support for Model Context Protocol (MCP) elicitation as both:

1. A source format (import/render MCP elicitation requests)
2. A target format (export eSheet questionnaires as MCP elicitation schemas)

This enables eSheet to act as a universal form engine for LLM-driven workflows, bridging:

• MCP servers (structured input requests)
• FHIR Questionnaires (existing model)
• Dynamic UI rendering (existing eSheet capability)

---

🎯 Goals

• Render MCP elicitation requests directly in eSheet UI

• Convert MCP elicitation schema ⇄ FHIR Questionnaire

• Support validation, required fields, and typed answers

• Enable round-trip flow:

  • MCP → eSheet form → answers → MCP response

---

📦 Scope

1. New Data Adapter: MCP Elicitation

Create a new adapter module:

/adapters/mcpElicitation.ts

Responsibilities:

• Parse MCP elicitation request payload
• Normalize into internal eSheet model
• Serialize responses back to MCP format

---

🔄 Data Mapping

MCP → eSheet (FHIR Questionnaire-like)

MCP Concept	eSheet / FHIR Equivalent
questions[]	Questionnaire.item[]
id	linkId
label / prompt	text
type	type
required	required
options	answerOption
validation	extension or constraints
description	helpText / extension

---

Example Mapping

MCP Input

{
  "message": "We need more information",
  "questions": [
    {
      "id": "email",
      "type": "string",
      "label": "Email address",
      "required": true,
      "validation": {
        "format": "email"
      }
    }
  ]
}

Internal eSheet Representation (FHIR-like)

{
  "resourceType": "Questionnaire",
  "item": [
    {
      "linkId": "email",
      "text": "Email address",
      "type": "string",
      "required": true,
      "extension": [
        {
          "url": "validation:format",
          "valueString": "email"
        }
      ]
    }
  ]
}

---

🧠 Validation Support

Support MCP validation rules:

• minLength

• maxLength

• minimum

• maximum

• format:

  • email
  • uri
  • date
  • date-time

• integer

Implementation

• Map to:

  • FHIR constraint
  • or eSheet validation engine

• Ensure UI displays validation errors inline

---

🧾 Answer Handling

MCP Expected Output

{
  "answers": {
    "email": "user@example.com"
  }
}

eSheet → MCP Serializer

Create:

serializeToMcpAnswers(response: QuestionnaireResponse): McpAnswers

Handle:

• string
• number
• boolean
• single-select
• multi-select

---

🎨 UI Enhancements

1. Elicitation Message Support

• Render message at top of form
• Styled as system prompt / banner

2. Question Descriptions

• Support description field under labels

3. Validation States

• Inline errors
• Required indicators

4. Submission Summary (optional)

• Show collected answers before submit

---

🔌 API Additions

New Input Type

type InputFormat = 'fhir' | 'mcp-elicitation'

New Methods

renderMcpElicitation(elicitation: McpElicitationRequest): FormInstance

serializeMcpAnswers(formState): McpElicitationResponse

---

🔐 Security Considerations

• Block or flag:

  • passwords
  • secrets
  • tokens

• Add config:

allowSensitiveFields?: boolean

---

🧪 Test Cases

1. Basic Text Input

• Required string field

2. Validation

• Email format rejection

3. Select প্রশ্ন

• Single-select + multi-select

4. Round Trip

• MCP → eSheet → MCP response

5. Invalid Schema Handling

• Missing id
• Unsupported types

---

🚧 Non-Goals (for this ticket)

• URL-based elicitation (OAuth-style flows)
• Streaming / partial responses
• Nested/recursive elicitation flows

---

🚀 Future Extensions

• MCP → FHIR Questionnaire export endpoint
• Persist elicitation sessions
• Multi-step elicitation (wizard mode)
• Integration with LLM tool calling systems
• OpenAPI/JSON Schema alignment layer

---

💡 Why This Matters

This turns eSheet into:

A universal human-in-the-loop input engine for LLM systems

Instead of:

• Hardcoding prompts
• Building custom UIs per tool

You get:

• Schema-driven UI
• Strong typing
• Reusable form infrastructure

---

✅ Acceptance Criteria

• Can render MCP elicitation JSON as a form
• Validation rules enforced in UI
• Answers serialize back to MCP format
• Round-trip test passes
• Works alongside existing FHIR mode

[horner]

• Here is how VSCode implemented it: https://github.com/microsoft/vscode/pull/300294/changes

• Here is the spec: https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation