# @ng-forge/dynamic-form-mcp

MCP (Model Context Protocol) server for ng-forge dynamic forms - enables AI assistants to generate, validate, and work with dynamic form configurations.

[![CI](https://img.shields.io/github/actions/workflow/status/ng-forge/ng-forge/ci.yml?branch=main)](https://github.com/ng-forge/ng-forge/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/@ng-forge/dynamic-form-mcp.svg)](https://www.npmjs.com/package/@ng-forge/dynamic-form-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@ng-forge/dynamic-form-mcp.svg)](https://www.npmjs.com/package/@ng-forge/dynamic-form-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Discord](https://img.shields.io/discord/1494269650555371582?color=7289da&label=Discord&logo=discord&logoColor=white)](https://discord.gg/qpzzvFagj3)

## Features

- **Documentation Lookup**: Explore field types, concepts, and patterns
- **Code Examples**: Get working, copy-paste-ready form configurations
- **Config Validation**: Validate FormConfig objects with detailed error messages
- **Skeleton Generation**: Generate form scaffolds from parameters

## Installation

No manual install needed. This is a stdio MCP server that your MCP client launches on demand via `npx` (using the package name `@ng-forge/dynamic-form-mcp`); see the per-client config in Setup below.

## Setup

### Cursor

Add to your Cursor MCP settings:

```json
{
  "ng-forge": {
    "command": "npx",
    "args": ["-y", "@ng-forge/dynamic-form-mcp"]
  }
}
```

### VS Code with Copilot

Create `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "ng-forge": {
      "command": "npx",
      "args": ["-y", "@ng-forge/dynamic-form-mcp"]
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "ng-forge": {
      "command": "npx",
      "args": ["-y", "@ng-forge/dynamic-form-mcp"]
    }
  }
}
```

### JetBrains IDEs

Go to **Settings > Tools > AI Assistant > Model Context Protocol (MCP)** and add:

| Field     | Value                         |
| --------- | ----------------------------- |
| Name      | ng-forge                      |
| Command   | npx                           |
| Arguments | -y @ng-forge/dynamic-form-mcp |

### Local Development

For development within the ng-forge monorepo:

```json
{
  "mcpServers": {
    "ng-forge": {
      "command": "node",
      "args": ["/path/to/ng-forge/dist/packages/dynamic-form-mcp/bin/ng-forge-mcp.js"]
    }
  }
}
```

## Available Tools

The server provides 5 focused tools:

| Tool               | Description                                                    | Read-only |
| ------------------ | -------------------------------------------------------------- | --------- |
| `ngforge_lookup`   | Get documentation about field types, concepts, and patterns    | ✅        |
| `ngforge_examples` | Get working code examples for common form patterns             | ✅        |
| `ngforge_validate` | Validate FormConfig and get detailed error feedback            | ✅        |
| `ngforge_scaffold` | Generate valid FormConfig skeletons                            | ✅        |
| `ngforge_search`   | Free-text search across topics, patterns, wrappers, and addons | ✅        |

---

### ngforge_lookup

Get documentation about any ng-forge topic.

| Parameter       | Type                                                      | Default    | Description             |
| --------------- | --------------------------------------------------------- | ---------- | ----------------------- |
| `topic`         | string                                                    | (required) | Topic to look up        |
| `depth`         | `"brief"` \| `"full"` \| `"schema"`                       | `"full"`   | Level of detail         |
| `uiIntegration` | `"material"` \| `"bootstrap"` \| `"primeng"` \| `"ionic"` | -          | Filter UI-specific info |

**Available Topics:**

Run `ngforge_lookup topic="list"` for the complete, always-current list of topics. Categories include field types (`input`, `select`, `multi-checkbox`, ...), containers (`group`, `row`, `array`, `page`), concepts (`validation`, `conditional`, `derivation`, ...), wrappers, and addons.

---

### ngforge_examples

Get working code examples for common patterns.

| Parameter | Type                                                  | Default    | Description     |
| --------- | ----------------------------------------------------- | ---------- | --------------- |
| `pattern` | string                                                | (required) | Pattern name    |
| `depth`   | `"minimal"` \| `"brief"` \| `"full"` \| `"explained"` | `"full"`   | Level of detail |

**Available Patterns:**

| Pattern                    | Description                                |
| -------------------------- | ------------------------------------------ |
| `minimal-multipage`        | Simplest 2-page wizard form                |
| `minimal-array`            | Array with add/remove buttons              |
| `minimal-simplified-array` | Array using the simplified-array shorthand |
| `minimal-conditional`      | Show/hide a field based on a condition     |
| `minimal-validation`       | Password confirmation validation           |
| `minimal-hidden`           | Hidden fields in a multi-page form         |
| `multi-page`               | Multi-page wizard with navigation buttons  |
| `property-derivation`      | Derive a field property from another field |

Run `ngforge_examples pattern="list"` for the current set of patterns.

---

### ngforge_validate

Validate FormConfig and get detailed error feedback.

| Parameter       | Type                                                      | Default      | Description                    |
| --------------- | --------------------------------------------------------- | ------------ | ------------------------------ |
| `config`        | string \| object                                          | (required)   | File path or JSON config       |
| `uiIntegration` | `"material"` \| `"bootstrap"` \| `"primeng"` \| `"ionic"` | `"material"` | UI library to validate against |

**Input Detection:**

| Input                    | Treated As         |
| ------------------------ | ------------------ |
| Ends with `.ts` or `.js` | File path          |
| Starts with `{` or `[`   | JSON string        |
| Object                   | Validated directly |

**Example Errors:**

- "Hidden field missing REQUIRED value property"
- "options MUST be at FIELD level, NOT inside props"
- "containers only support 'hidden' logic type"

---

### ngforge_scaffold

Generate valid FormConfig skeletons.

| Parameter       | Type     | Default      | Description                           |
| --------------- | -------- | ------------ | ------------------------------------- |
| `pages`         | number   | `0`          | Number of pages (0 = single-page)     |
| `fields`        | string[] | `[]`         | Fields as `"name:type"` pairs         |
| `groups`        | string[] | `[]`         | Group field names                     |
| `arrays`        | string[] | `[]`         | Array field names                     |
| `hidden`        | string[] | `[]`         | Hidden fields as `"name:value"` pairs |
| `uiIntegration` | enum     | `"material"` | UI library                            |

**Supported field types:** `input`, `select`, `radio`, `checkbox`, `textarea`, `datepicker`, `slider`, `toggle`

---

## MCP Resources

| Resource URI               | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `ng-forge://instructions`  | Best practices guide for generating FormConfig |
| `ng-forge://examples`      | Curated FormConfig examples                    |
| `ng-forge://examples/{id}` | Specific example by ID                         |
| `ng-forge://field-types`   | Field type reference                           |
| `ng-forge://validators`    | Validator reference                            |
| `ng-forge://wrappers`      | Wrapper reference                              |
| `ng-forge://schemas`       | Standard Schema validation reference           |
| `ng-forge://ui-adapters`   | UI library configurations                      |
| `ng-forge://docs`          | Full documentation index                       |

## Development

### Building

```bash
nx build dynamic-form-mcp
```

### Testing

```bash
nx test dynamic-form-mcp
```

### Generating Registry

```bash
nx run dynamic-form-mcp:generate-registry
```

## License

MIT