render-question-mcp

An MCP (Model Context Protocol) server that enables AI agents to collect structured, validated user input through native UI forms using elicitation.

Features

6 Question Types: text, number, boolean, radio, dropdown, checkbox (with true multi-select support!)
Multi-Select Checkboxes: Native array support for selecting multiple options
Comprehensive Validation: required fields, min/max values, patterns, email/URI formats
Type-Safe: Built with TypeScript and Zod for runtime validation
Native UI: Renders forms in the MCP client's native interface
Zero Ambiguity: Eliminates conversational back-and-forth for data collection

Installation

Prerequisites

Node.js >= 20.0.0
An MCP-compatible client (Cursor, Claude Desktop, VS Code, etc.)

Getting Started

First, install the render-question-mcp server with your client.

Standard config works in most tools:

{
  "mcpServers": {
    "render-question": {
      "command": "npx",
      "args": [
        "render-question-mcp@latest"
      ]
    }
  }
}

Claude Code

Use the Claude Code CLI to add the server:

claude mcp add render-question npx render-question-mcp@latest

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "render-question": {
      "command": "npx",
      "args": ["render-question-mcp@latest"]
    }
  }
}

Cursor

Click the button to install:

Or install manually:

Go to Cursor Settings → MCP → Add new MCP Server. Name to your liking, use command type with the command npx render-question-mcp@latest. You can also verify config or add command arguments via clicking Edit.

Project-Specific Configuration

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "render-question": {
      "command": "npx",
      "args": ["render-question-mcp@latest"]
    }
  }
}

VS Code

Follow the MCP install guide, use the standard config above.

Alternatively, install using the VS Code CLI:

code --add-mcp '{"name":"render-question","command":"npx","args":["render-question-mcp@latest"]}'

Cline

Add via the Cline VS Code extension settings or by updating your cline_mcp_settings.json file:

{
  "mcpServers": {
    "render-question": {
      "command": "npx",
      "args": [
        "render-question-mcp@latest"
      ]
    }
  }
}

Zed

Follow the MCP Servers documentation. Use the standard config above.

Local Development

For local development and testing:

{
  "mcpServers": {
    "render-question": {
      "command": "node",
      "args": ["/absolute/path/to/render-question-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Verify Installation

After installation, verify render-question-mcp is working:

Restart your MCP client completely
Check connection status:
- Cursor: Look for green dot in Settings → Tools & Integrations → MCP Tools
- Claude Desktop: Check for "render_question" in available tools
- VS Code: Verify in GitHub Copilot settings
Test with a simple query:
```
Ask me for my name and email address
```

If you see the AI agent use the render_question tool and display a native form, you're all set! 🎉

Usage

The server provides a single tool: render_question

Basic Example: Single Text Field

{
  "questions": [
    {
      "id": "email",
      "type": "text",
      "label": "What is your email address?",
      "validation": {
        "required": true,
        "format": "email"
      },
      "helpText": "We'll use this for project notifications",
      "placeholder": "developer@example.com"
    }
  ]
}

Example: Multiple Questions Form

{
  "title": "Developer Onboarding",
  "description": "Help us set up your development environment",
  "questions": [
    {
      "id": "name",
      "type": "text",
      "label": "Your full name",
      "validation": {
        "required": true,
        "minLength": 2
      },
      "placeholder": "Jane Doe"
    },
    {
      "id": "experience",
      "type": "number",
      "label": "Years of experience with TypeScript",
      "validation": {
        "required": true,
        "min": 0,
        "max": 50
      }
    },
    {
      "id": "role",
      "type": "dropdown",
      "label": "What's your primary role?",
      "options": [
        { "value": "frontend", "label": "Frontend Developer" },
        { "value": "backend", "label": "Backend Developer" },
        { "value": "fullstack", "label": "Full-Stack Developer" },
        { "value": "devops", "label": "DevOps Engineer" }
      ],
      "validation": { "required": true }
    },
    {
      "id": "remote",
      "type": "boolean",
      "label": "Are you working remotely?",
      "default": true
    }
  ]
}

Question Types

Text Input

{
  "id": "username",
  "type": "text",
  "label": "Username",
  "validation": {
    "required": true,
    "minLength": 3,
    "maxLength": 20,
    "pattern": "^[a-zA-Z0-9_]+$"
  },
  "placeholder": "john_doe"
}

Number Input

{
  "id": "port",
  "type": "number",
  "label": "Port Number",
  "validation": {
    "required": true,
    "min": 1,
    "max": 65535
  },
  "default": 3000
}

Boolean (Single Checkbox)

{
  "id": "agree",
  "type": "boolean",
  "label": "I agree to the terms and conditions",
  "validation": {
    "required": true
  }
}

Radio Buttons (Single Choice)

{
  "id": "theme",
  "type": "radio",
  "label": "Select a theme",
  "options": [
    { "value": "light", "label": "Light Mode" },
    { "value": "dark", "label": "Dark Mode" },
    { "value": "auto", "label": "Auto (System)" }
  ],
  "validation": {
    "required": true
  }
}

Dropdown (Single Choice)

{
  "id": "framework",
  "type": "dropdown",
  "label": "Choose a framework",
  "options": [
    { "value": "react", "label": "React" },
    { "value": "vue", "label": "Vue.js" },
    { "value": "angular", "label": "Angular" },
    { "value": "svelte", "label": "Svelte" }
  ]
}

Checkbox (Multi-Select) ✨ NEW!

{
  "id": "features",
  "type": "checkbox",
  "label": "Select features to enable",
  "options": [
    { "value": "auth", "label": "Authentication" },
    { "value": "db", "label": "Database Integration" },
    { "value": "api", "label": "REST API" },
    { "value": "websocket", "label": "WebSocket Support" }
  ],
  "validation": {
    "min": 1,  // Require at least 1 selection
    "max": 3   // Allow maximum 3 selections
  },
  "helpText": "Choose all features you want to include"
}

Response format for multi-select:

{
  "features": ["auth", "db", "api"]  // Array of selected values
}

Validation Options

required: boolean - Field must be filled
min / max: number - Min/max value for numbers, or min/max items for checkbox arrays
minLength / maxLength: number - Min/max length for strings
pattern: string - Regular expression pattern
format: "email" | "uri" | "url" | "date" | "date-time" - Format validation
errorMessage: string - Custom error message

Response Format

The tool returns a structured response:

{
  "answers": {
    "name": "Jane Doe",
    "experience": 5,
    "role": "fullstack",
    "remote": true,
    "features": ["auth", "db", "api"]
  },
  "metadata": {
    "completedAt": "2025-11-13T10:30:00Z",
    "duration": 15000,
    "action": "submit"
  }
}

Possible actions:

submit - User submitted the form
cancel - User canceled the dialog
decline - User declined to answer

Development

Setup

pnpm install
pnpm build

Testing

pnpm test
pnpm test:coverage

Local Testing

Build the project:
```
pnpm build
```
Link locally:
```
npm link
```
Configure your MCP client to use the local build
Test with an MCP Inspector or client

Examples

See the examples directory for real-world use cases:

Architecture

src/
├── index.ts              # CLI entry point
├── server.ts             # MCP server setup
├── stdio.ts              # Stdio transport
├── types.ts              # TypeScript type definitions
├── elicitation/
│   ├── core.ts           # Core elicitation logic
│   └── schemas.ts        # Schema builders
└── tools/
    ├── index.ts          # Tool registry
    └── render_question.ts # Main tool implementation

For AI Agents

See AGENTS.md for detailed guidance on using this tool effectively in AI workflows.

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines and submit a PR.

Related Projects

MCP Specification
MCP TypeScript SDK
mcp-elicit - Reference implementation

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.cursor		.cursor
examples		examples
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.setup.ts		vitest.setup.ts

License

vltansky/render-question-mcp

Folders and files

Latest commit

History

Repository files navigation

render-question-mcp

Features

Installation

Prerequisites

Getting Started

Click the button to install:

Or install manually:

Project-Specific Configuration

Local Development

Verify Installation

Usage

Basic Example: Single Text Field

Example: Multiple Questions Form

Question Types

Text Input

Number Input

Boolean (Single Checkbox)

Radio Buttons (Single Choice)

Dropdown (Single Choice)

Checkbox (Multi-Select) ✨ NEW!

Validation Options

Response Format

Development

Setup

Testing

Local Testing

Examples

Architecture

For AI Agents

License

Contributing

Related Projects

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages