@anri1214/dynamic-forms-mui-mcp 0.1.5

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 AI Hub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,214 @@
+# @ai-hub/dynamic-forms-mui-mcp
+
+MCP (Model Context Protocol) server for **@ai-hub/dynamic-forms-mui** — exposes the `FormSchema` structure as tools, resources, and prompts for AI assistants.
+
+## Why?
+
+Your backend can be written in **any language** (Python, Go, C#, Java, etc.) but it needs to return a JSON that matches the `FormSchema` type from `@ai-hub/dynamic-forms-mui`. This MCP server gives AI assistants full knowledge of the schema structure, so they can:
+
+- **Validate** form configuration JSON
+- **Generate** correct FormSchema JSON from natural language
+- **Help backend developers** produce correct API endpoints in any language
+- **Serve version-specific documentation** — different projects can use different library versions
+
+## Versioning
+
+The MCP server supports **multiple versions** of `@ai-hub/dynamic-forms-mui` simultaneously. Versions are tracked as `major.minor` (e.g. `0.1`, `0.2`, `1.0`) — patch versions are ignored since they don't change the schema API.
+
+Every tool (except `list_versions`) requires a mandatory `version` parameter. This ensures the AI always gets documentation matching the project's installed library version.
+
+```
+AI reads package.json → version "0.1.3" → calls tool with version: "0.1" → gets correct docs
+```
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @ai-hub/dynamic-forms-mui-mcp
+# or run directly
+npx @ai-hub/dynamic-forms-mui-mcp
+```
+
+### 2. Configure in your IDE
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "dynamic-forms": {
+      "command": "npx",
+      "args": ["@ai-hub/dynamic-forms-mui-mcp"]
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add dynamic-forms npx @ai-hub/dynamic-forms-mui-mcp
+```
+
+**VS Code:**
+
+```bash
+code --add-mcp '{"name":"dynamic-forms","type":"stdio","command":"npx","args":["@ai-hub/dynamic-forms-mui-mcp"]}'
+```
+
+### 3. Use it
+
+Ask your AI assistant:
+
+> "Generate a FormSchema for a user registration form with email, password, confirm password, first name, last name"
+
+The AI will use the MCP server to understand the exact structure and generate valid JSON.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_versions` | List available library versions this MCP has documentation for. |
+| `validate_form_schema` | Validate a JSON against the FormSchema spec. Returns errors if invalid. |
+| `list_field_types` | List all 14 supported field types with descriptions and applicable validations. |
+| `get_field_config` | Get detailed config for a specific field type (props, validations, example). |
+| `generate_form_schema` | Generate a FormSchema from a list of field definitions. Auto-validates output. |
+
+> All tools except `list_versions` require a `version` parameter (e.g. `"0.1"`).
+
+### Example: list_versions
+
+Output:
+```json
+{
+  "latest": "0.1",
+  "available": ["0.1"]
+}
+```
+
+### Example: validate_form_schema
+
+Input:
+```json
+{
+  "version": "0.1",
+  "schema": "{\"sections\":[{\"id\":\"main\",\"title\":\"Form\",\"fields\":[\"email\"]}],\"fields\":{\"email\":{\"type\":\"email\",\"label\":\"Email\"}}}"
+}
+```
+
+Output:
+```json
+{
+  "valid": true,
+  "errors": []
+}
+```
+
+### Example: get_field_config
+
+Input:
+```json
+{
+  "version": "0.1",
+  "fieldType": "password"
+}
+```
+
+Output:
+```json
+{
+  "type": "password",
+  "description": "Password input with masked characters",
+  "config": "TextFieldConfig",
+  "specificProps": ["autoComplete"],
+  "applicableValidations": ["required", "minLength", "maxLength", "hasUppercase", "hasLowercase", "hasNumber", "hasSpecialChar", "matchField"],
+  "example": {
+    "type": "password",
+    "label": "Password",
+    "validation": {
+      "required": true,
+      "minLength": 8,
+      "hasUppercase": true,
+      "hasLowercase": true,
+      "hasSpecialChar": true
+    }
+  }
+}
+```
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `schema://dynamic-forms/{version}/form-schema` | Complete JSON Schema for FormSchema |
+| `schema://dynamic-forms/{version}/field-types` | Markdown documentation for all field types |
+| `schema://dynamic-forms/{version}/examples/{name}` | Example schemas: `registration`, `crud`, `filters` |
+
+## Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `generate-backend-endpoint` | Generate backend API endpoint code in any language/framework |
+| `generate-form-config` | Generate a FormSchema JSON from a natural language description |
+
+### Example: generate-backend-endpoint
+
+```
+Language: Python
+Framework: FastAPI
+Description: User registration with email, password, name, and terms acceptance
+```
+
+The AI will generate a complete FastAPI endpoint returning a valid FormSchema JSON.
+
+## Supported Field Types
+
+| Type | Description |
+|------|-------------|
+| `text` | Single-line text input |
+| `password` | Password input with masking |
+| `email` | Email input with validation |
+| `number` | Numeric input with min/max/step |
+| `textarea` | Multi-line text input |
+| `select` | Single-value dropdown |
+| `multiselect` | Multi-value dropdown (chips) |
+| `autocomplete` | Single-value autocomplete with async search |
+| `checkbox` | Boolean checkbox |
+| `radio` | Radio button group |
+| `switch` | Toggle switch |
+| `date` | Date picker |
+| `dateRange` | Date range picker |
+| `file` | File upload |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Generate JSON Schema from types (writes to src/schema/{version}/)
+npm run build:schema
+
+# Build TypeScript + copy schemas to dist
+npm run build
+
+# Run in development mode
+npm run dev
+```
+
+### Adding a new schema version
+
+When `@ai-hub/dynamic-forms-mui` gets a new minor version:
+
+1. Update the library's `package.json` version (e.g. `0.1.x` → `0.2.0`)
+2. Run `npm run build:schema` — automatically creates `src/schema/0.2/` and updates `versions.json`
+3. Adjust `fieldTypes.json` and `examples/` in the new version folder if the schema changed
+4. Run `npm run build`
+
+Old version schemas are preserved — the MCP can serve docs for all versions simultaneously.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * @ai-hub/dynamic-forms-mui-mcp
+ *
+ * MCP server that exposes the FormSchema structure of @ai-hub/dynamic-forms-mui
+ * as tools, resources, and prompts for AI assistants.
+ *
+ * All tools (except list_versions) require a `version` parameter to ensure
+ * the AI gets documentation matching the project's installed library version.
+ *
+ * Transport: stdio (for Cursor, Claude Code, VS Code, etc.)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}

package/dist/index.js

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+/**
+ * @ai-hub/dynamic-forms-mui-mcp
+ *
+ * MCP server that exposes the FormSchema structure of @ai-hub/dynamic-forms-mui
+ * as tools, resources, and prompts for AI assistants.
+ *
+ * All tools (except list_versions) require a `version` parameter to ensure
+ * the AI gets documentation matching the project's installed library version.
+ *
+ * Transport: stdio (for Cursor, Claude Code, VS Code, etc.)
+ */
+import { createRequire } from 'node:module';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+// Schema loader
+import { getAvailableVersions, resolveVersion } from './schemaLoader.js';
+// Tools
+import { validateFormSchema } from './tools/validateSchema.js';
+import { listFieldTypes } from './tools/listFieldTypes.js';
+import { getFieldConfig } from './tools/getFieldConfig.js';
+import { generateFormSchema } from './tools/generateSchema.js';
+// Resources
+import { getFormSchemaResource } from './resources/jsonSchema.js';
+import { getFieldDocsResource } from './resources/fieldDocs.js';
+import { listExamples, getExample } from './resources/examples.js';
+// Prompts
+import { generateBackendEndpointPrompt } from './prompts/generateBackendEndpoint.js';
+import { generateFormConfigPrompt } from './prompts/generateFormConfig.js';
+// ── Read MCP server version from own package.json ──────────
+const require = createRequire(import.meta.url);
+const mcpPackageJson = require('../package.json');
+// ── Create MCP Server ──────────────────────────────────────
+const server = new McpServer({
+    name: '@ai-hub/dynamic-forms-mui-mcp',
+    version: mcpPackageJson.version,
+});
+// ── Shared version param description ───────────────────────
+const versionParamDesc = 'The @ai-hub/dynamic-forms-mui library version as major.minor (e.g. "0.1"). Full semver like "0.1.0" is also accepted and normalized to "0.1". Use list_versions to see available versions.';
+// ════════════════════════════════════════════════════════════
+//  TOOLS
+// ════════════════════════════════════════════════════════════
+// 1. list_versions (the only tool WITHOUT a version parameter)
+server.tool('list_versions', 'List available @ai-hub/dynamic-forms-mui library versions that this MCP server has documentation for.', {}, async () => {
+    const versions = getAvailableVersions();
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(versions, null, 2),
+            },
+        ],
+    };
+});
+// 2. validate_form_schema
+server.tool('validate_form_schema', 'Validate a JSON object against the dynamic-forms-mui FormSchema specification. Returns whether the schema is valid and any validation errors.', {
+    version: z.string().describe(versionParamDesc),
+    schema: z.string().describe('A JSON string representing the FormSchema to validate. Must have "sections" and "fields" top-level properties.'),
+}, async ({ version, schema: schemaStr }) => {
+    try {
+        resolveVersion(version);
+    }
+    catch (err) {
+        return {
+            content: [{ type: 'text', text: err.message }],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(schemaStr);
+    }
+    catch {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        valid: false,
+                        errors: ['Invalid JSON: failed to parse the input string'],
+                    }),
+                },
+            ],
+        };
+    }
+    const result = validateFormSchema(version, parsed);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// 3. list_field_types
+server.tool('list_field_types', 'List all supported field types in dynamic-forms-mui with their descriptions, config interfaces, specific props, and applicable validations.', {
+    version: z.string().describe(versionParamDesc),
+}, async ({ version }) => {
+    try {
+        resolveVersion(version);
+    }
+    catch (err) {
+        return {
+            content: [{ type: 'text', text: err.message }],
+        };
+    }
+    const types = listFieldTypes(version);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(types, null, 2),
+            },
+        ],
+    };
+});
+// 4. get_field_config
+server.tool('get_field_config', 'Get detailed configuration information for a specific field type, including all props, applicable validations, and a working example.', {
+    version: z.string().describe(versionParamDesc),
+    fieldType: z
+        .string()
+        .describe('The field type to get details for. One of: text, password, email, number, textarea, select, multiselect, checkbox, radio, switch, date, dateRange, file'),
+}, async ({ version, fieldType }) => {
+    try {
+        resolveVersion(version);
+    }
+    catch (err) {
+        return {
+            content: [{ type: 'text', text: err.message }],
+        };
+    }
+    const config = getFieldConfig(version, fieldType);
+    if (!config) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Unknown field type "${fieldType}". Use list_field_types to see available types for version ${version}.`,
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(config, null, 2),
+            },
+        ],
+    };
+});
+// 5. generate_form_schema
+server.tool('generate_form_schema', 'Generate a valid FormSchema JSON from a high-level description of fields. Validates the output automatically.', {
+    version: z.string().describe(versionParamDesc),
+    description: z.string().optional().describe('Description of the form (used as section title if no sections provided)'),
+    fields: z
+        .array(z.object({
+        name: z.string().describe('Unique field key (camelCase)'),
+        type: z.string().describe('Field type: text, password, email, number, textarea, select, multiselect, checkbox, radio, switch, date, dateRange, file'),
+        label: z.string().optional().describe('Display label (defaults to name)'),
+        required: z.boolean().optional().describe('Whether field is required'),
+        extraProps: z.record(z.unknown()).optional().describe('Additional field props (e.g. rows, min, max, options)'),
+        validationRules: z.record(z.unknown()).optional().describe('Additional validation rules (e.g. minLength, hasUppercase)'),
+    }))
+        .describe('Array of field definitions'),
+    sections: z
+        .array(z.object({
+        id: z.string().describe('Section ID'),
+        title: z.string().describe('Section title'),
+        fieldNames: z.array(z.string()).describe('Field keys in this section'),
+    }))
+        .optional()
+        .describe('Optional section groupings. If omitted, all fields go into a single section.'),
+}, async ({ version, description, fields, sections }) => {
+    try {
+        resolveVersion(version);
+    }
+    catch (err) {
+        return {
+            content: [{ type: 'text', text: err.message }],
+        };
+    }
+    const result = generateFormSchema({ version, description, fields, sections });
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// ════════════════════════════════════════════════════════════
+//  RESOURCES
+// ════════════════════════════════════════════════════════════
+// 1. FormSchema JSON Schema (versioned)
+server.resource('form-schema', new ResourceTemplate('schema://dynamic-forms/{version}/form-schema', {
+    list: async () => {
+        const { available } = getAvailableVersions();
+        return {
+            resources: available.map((v) => ({
+                uri: `schema://dynamic-forms/${v}/form-schema`,
+                name: `FormSchema JSON Schema (v${v})`,
+                description: `Complete JSON Schema for dynamic-forms-mui v${v}`,
+                mimeType: 'application/json',
+            })),
+        };
+    },
+}), {
+    description: 'Complete JSON Schema for the dynamic-forms-mui FormSchema type. Use this as a reference for the expected structure.',
+    mimeType: 'application/json',
+}, async (uri, { version }) => {
+    const v = Array.isArray(version) ? version[0] : version;
+    try {
+        resolveVersion(v);
+    }
+    catch {
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: `Version "${v}" not found. Available: ${getAvailableVersions().available.join(', ')}`,
+                    mimeType: 'text/plain',
+                },
+            ],
+        };
+    }
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                text: getFormSchemaResource(v),
+                mimeType: 'application/json',
+            },
+        ],
+    };
+});
+// 2. Field Types Documentation (versioned)
+server.resource('field-types-docs', new ResourceTemplate('schema://dynamic-forms/{version}/field-types', {
+    list: async () => {
+        const { available } = getAvailableVersions();
+        return {
+            resources: available.map((v) => ({
+                uri: `schema://dynamic-forms/${v}/field-types`,
+                name: `Field Types Documentation (v${v})`,
+                description: `Documentation for all field types in dynamic-forms-mui v${v}`,
+                mimeType: 'text/markdown',
+            })),
+        };
+    },
+}), {
+    description: 'Comprehensive documentation for all field types including props, validations, and examples.',
+    mimeType: 'text/markdown',
+}, async (uri, { version }) => {
+    const v = Array.isArray(version) ? version[0] : version;
+    try {
+        resolveVersion(v);
+    }
+    catch {
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: `Version "${v}" not found. Available: ${getAvailableVersions().available.join(', ')}`,
+                    mimeType: 'text/plain',
+                },
+            ],
+        };
+    }
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                text: getFieldDocsResource(v),
+                mimeType: 'text/markdown',
+            },
+        ],
+    };
+});
+// 3. Example Schemas (versioned + dynamic name)
+server.resource('example', new ResourceTemplate('schema://dynamic-forms/{version}/examples/{name}', {
+    list: async () => {
+        const { available } = getAvailableVersions();
+        const resources = [];
+        for (const v of available) {
+            const examples = listExamples(v);
+            for (const exName of examples) {
+                resources.push({
+                    uri: `schema://dynamic-forms/${v}/examples/${exName}`,
+                    name: `${exName} form example (v${v})`,
+                    description: `Example FormSchema: ${exName} (v${v})`,
+                    mimeType: 'application/json',
+                });
+            }
+        }
+        return { resources };
+    },
+}), {
+    description: 'Example FormSchema configurations for common use cases.',
+    mimeType: 'application/json',
+}, async (uri, { version, name }) => {
+    const v = Array.isArray(version) ? version[0] : version;
+    const exampleName = Array.isArray(name) ? name[0] : name;
+    try {
+        resolveVersion(v);
+    }
+    catch {
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: `Version "${v}" not found. Available: ${getAvailableVersions().available.join(', ')}`,
+                    mimeType: 'text/plain',
+                },
+            ],
+        };
+    }
+    const content = getExample(v, exampleName);
+    if (!content) {
+        const available = listExamples(v);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: `Example "${exampleName}" not found for version ${v}. Available: ${available.join(', ')}`,
+                    mimeType: 'text/plain',
+                },
+            ],
+        };
+    }
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                text: content,
+                mimeType: 'application/json',
+            },
+        ],
+    };
+});
+// ════════════════════════════════════════════════════════════
+//  PROMPTS
+// ════════════════════════════════════════════════════════════
+// 1. Generate Backend Endpoint
+server.prompt('generate-backend-endpoint', 'Generate backend API endpoint code (in any language/framework) that returns a valid FormSchema JSON.', {
+    language: z.string().describe('Programming language (e.g. Python, Go, C#, Java, TypeScript)'),
+    framework: z.string().describe('Web framework (e.g. FastAPI, Gin, ASP.NET, Spring Boot, Express)'),
+    formDescription: z
+        .string()
+        .describe('Natural language description of the form (e.g. "User registration with email, password, and profile fields")'),
+}, ({ language, framework, formDescription }) => ({
+    messages: [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: generateBackendEndpointPrompt(language, framework, formDescription),
+            },
+        },
+    ],
+}));
+// 2. Generate Form Config
+server.prompt('generate-form-config', 'Generate a complete FormSchema JSON configuration from a natural language description.', {
+    formDescription: z
+        .string()
+        .describe('Natural language description of the form and its fields'),
+    fieldHints: z
+        .string()
+        .optional()
+        .describe('Optional additional hints about specific fields, validations, or conditions'),
+}, ({ formDescription, fieldHints }) => ({
+    messages: [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: generateFormConfigPrompt(formDescription, fieldHints),
+            },
+        },
+    ],
+}));
+// ════════════════════════════════════════════════════════════
+//  START SERVER
+// ════════════════════════════════════════════════════════════
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`🚀 @ai-hub/dynamic-forms-mui-mcp v${mcpPackageJson.version} server is running (stdio)`);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/prompts/generateBackendEndpoint.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns a prompt that helps generate backend code returning a valid FormSchema.
+ */
+export declare function generateBackendEndpointPrompt(language: string, framework: string, formDescription: string): string;
+//# sourceMappingURL=generateBackendEndpoint.d.ts.map

package/dist/prompts/generateBackendEndpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateBackendEndpoint.d.ts","sourceRoot":"","sources":["../../src/prompts/generateBackendEndpoint.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,GACtB,MAAM,CA6BR"}

package/dist/prompts/generateBackendEndpoint.js

@@ -0,0 +1,33 @@
+/**
+ * Returns a prompt that helps generate backend code returning a valid FormSchema.
+ */
+export function generateBackendEndpointPrompt(language, framework, formDescription) {
+    return `You are a backend developer writing a REST API endpoint that returns a FormSchema JSON object.
+
+## Target Stack
+- Language: ${language}
+- Framework: ${framework}
+
+## Form Requirements
+${formDescription}
+
+## Instructions
+1. Create an API endpoint (GET) that returns a JSON object conforming to the FormSchema structure.
+2. The response must have two top-level properties:
+   - "sections": an array of section objects, each with "id", "title", and "fields" (array of field key strings)
+   - "fields": a map of field key → field configuration objects
+3. Each field configuration must include at minimum: "type" and "label"
+4. Use appropriate field types from this list:
+   text, password, email, number, textarea, select, multiselect, checkbox, radio, switch, date, dateRange, file
+5. Add validation rules where appropriate (required, minLength, maxLength, email, pattern, min, max, etc.)
+6. If fields depend on each other (e.g., city depends on country), use "optionsSource" with "queryParams" and "dependsOn"
+7. For conditional visibility, use "showIf" with condition operators: equals, notEquals, in, notIn, isEmpty, isNotEmpty, gt, gte, lt, lte
+8. Include custom validation messages in the "messages" property for better UX
+
+## Important
+- The endpoint should return ONLY the FormSchema JSON — the frontend @ai-hub/dynamic-forms-mui library will handle all rendering automatically.
+- Do NOT include any HTML or UI code. The backend only provides the schema; the frontend renders it.
+- Use proper HTTP status codes and error handling for your framework.
+
+Generate the complete endpoint code.`;
+}