webforJ MCP Server

Report the webforJ versions this server knows about. Returns the latest stable release, the current in-development SNAPSHOT (from the main-branch pom.xml), and an array of every major with its highest observed tag plus a `status` flag: "development" (the active SNAPSHOT line — actively changing), "stable" (the latest released major — may still receive minor/patch bugfixes), or "frozen" (older released majors — no new releases will be cut). Each major also carries `dataAvailable` indicating whether the DWC styling tools can answer questions about it. Call this FIRST when you do not know what version the user is on or which version to target — never guess.

{
  "type": "object",
  "properties": {
    "reasoning": {
      "type": "string",
      "minLength": 1,
      "description": "Your step-by-step reasoning for why you are calling this tool and what you expect it to return. Stating it explicitly before the call helps you pick the right arguments, avoid redundant calls, and stay on the documented routing path for this tool."
    }
  },
  "required": [
    "reasoning"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the Maven archetype command that scaffolds a new webforJ project, plus the follow-up commands to change into the generated directory and start the dev server. Relay the Maven command to the user via the host shell tool without modifying its arguments. Set showOptions=true to list available archetypes and the startforJ web generator instead of producing a command.

{
  "type": "object",
  "properties": {
    "appName": {
      "type": "string",
      "minLength": 1,
      "description": "webforJ application name"
    },
    "artifactId": {
      "type": "string",
      "description": "Maven artifact ID (default: kebab-case of appName)"
    },
    "groupId": {
      "type": "string",
      "description": "Maven group ID (default: com.<artifactId-without-hyphens>)"
    },
    "archetype": {
      "type": "string",
      "enum": [
        "blank",
        "hello-world",
        "tabs",
        "sidemenu"
      ],
      "description": "Archetype template (default: hello-world)"
    },
    "flavor": {
      "type": "string",
      "enum": [
        "webforj",
        "webforj-spring"
      ],
      "description": "Project flavor (default: webforj-spring)"
    },
    "version": {
      "type": "string",
      "description": "Project version (default: 1.0-SNAPSHOT)"
    },
    "archetypeVersion": {
      "type": "string",
      "description": "webforJ archetype version (default: LATEST)"
    },
    "showOptions": {
      "type": "boolean",
      "description": "If true, list archetypes and startforJ info instead of generating. Default: false."
    },
    "reasoning": {
      "type": "string",
      "minLength": 1,
      "description": "Your step-by-step reasoning for why you are calling this tool and what you expect it to return. Stating it explicitly before the call helps you pick the right arguments, avoid redundant calls, and stay on the documented routing path for this tool."
    }
  },
  "required": [
    "appName",
    "reasoning"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return the full content of an indexed webforJ documentation or sample file. Use this as a follow-up to search_knowledge_base when a search result excerpt is not enough and you need the complete page — migration guides, tutorials, long API docs. Pass the documentId from a search result.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Document id. Take this from the `documentId` field of a search_knowledge_base result. Stable, unique per document."
    },
    "reasoning": {
      "type": "string",
      "minLength": 1,
      "description": "Your step-by-step reasoning for why you are calling this tool and what you expect it to return. Stating it explicitly before the call helps you pick the right arguments, avoid redundant calls, and stay on the documented routing path for this tool."
    }
  },
  "required": [
    "id",
    "reasoning"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Search webforJ documentation, JavaDoc, and code samples for any class, method, annotation, or component, and for CSS styling concepts and rules (palette semantics, seed vs h/s, :not([theme]) pattern, dark mode, ::part limits, table styling). Returns matching snippets with titles, categories, and relevance scores. Call this before claiming any webforJ API exists. For exact --dwc-* custom property or ::part() names on a specific component, use styles_get_component instead; to verify tokens in generated CSS, use styles_validate_tokens. Pass category to narrow the search; if the category is unknown the tool errors with a ranked list of similar names plus the full set of valid categories, so you can retry. In a webforJ project the deliverable is Java (or the Kotlin DSL) using webforJ classes; search for the dedicated webforJ component before falling back to React, JSX, or hand-built HTML.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Natural language query. Examples: \"how to create buttons\", \"form validation\", \"data binding\", \"routing with @Route annotation\"."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Maximum number of search results to return (default: 25)."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Restrict results to one or more categories (any-of). Omit the field, pass an empty array, or include \"all\" to search every category. Prefer passing categories when the query is scoped (e.g. [\"button\"] for a button question, [\"button\",\"flexlayout\"] for a button-inside-a-layout question). If any entry is not a known category the tool returns isError with ranked similar-name suggestions per bad entry and the full list of valid categories, so a corrected retry will succeed."
    },
    "type": {
      "type": "string",
      "enum": [
        "documentation",
        "java",
        "sample",
        "kotlin",
        "all"
      ],
      "description": "Restrict results to a single content type. \"documentation\" = markdown docs and guides, \"java\" = webforJ Java API signatures, \"sample\" = Java sample programs, \"kotlin\" = webforJ Kotlin DSL source. Default: \"all\"."
    },
    "reasoning": {
      "type": "string",
      "minLength": 1,
      "description": "Your step-by-step reasoning for why you are calling this tool and what you expect it to return. Stating it explicitly before the call helps you pick the right arguments, avoid redundant calls, and stay on the documented routing path for this tool."
    }
  },
  "required": [
    "query",
    "reasoning"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return the real CSS styling surface of a DWC web component: CSS custom properties, shadow parts, reflected attributes, and slots. Accepts a DWC tag ("dwc-button") or a webforJ Java class name ("Button", "TextField"). Use mode="list" for every valid tag, mode="map" for Java -> tag mappings. Call this before writing CSS for a component so you never guess a var or part name. Prefer a typed Java setter on the component over CSS when both can produce the same result.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The component to look up. Accepts a DWC tag (\"dwc-button\") or a webforJ Java class name (\"Button\", \"TextField\"). Omit when mode is \"list\" or \"map\"."
    },
    "mode": {
      "type": "string",
      "enum": [
        "lookup",
        "list",
        "map"
      ],
      "description": "\"lookup\" (default): return a single component's styling metadata. \"list\": return every valid DWC tag for the target webforJ version. \"map\": return the Java class -> DWC tag mapping."
    },
    "webforjVersion": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+(-SNAPSHOT)?$",
      "description": "The webforJ version you are targeting, exactly as it appears in the project's pom.xml: a released major.minor like \"25.12\", or the current upcoming SNAPSHOT like \"26.00-SNAPSHOT\" (only the next unreleased version is published as SNAPSHOT; there is just one active SNAPSHOT at any time). Read it from pom.xml or ask the user."
    },
    "reasoning": {
      "type": "string",
      "minLength": 1,
      "description": "Your step-by-step reasoning for why you are calling this tool and what you expect it to return. Stating it explicitly before the call helps you pick the right arguments, avoid redundant calls, and stay on the documented routing path for this tool."
    }
  },
  "required": [
    "webforjVersion",
    "reasoning"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return the authoritative list of global --dwc-* tokens (palette seeds, color shades, surfaces, spacing, typography, borders, etc.). Use this for any "which tokens are available for X" question — DO NOT ask the knowledge base to list tokens; it returns prose and the answer will be hallucinated. Filter with "prefix" (e.g. "--dwc-color-primary-") or "contains" (e.g. "seed") to narrow the result. For component-scoped CSS vars like --dwc-button-* use styles_get_component instead. The returned list is verbatim and complete for the filter you passed — do not add, rename, complete, or explain "implied" tokens, and do not reference tokens from other webforJ versions. If a token you expect is missing from the response, it does not exist for that version. Tokens that share a description are returned in a single entry where "names" is the list of every token that has that description; treat each name as a real, independently usable token. When writing CSS, use a token instead of hardcoding colors, spacing, or font sizes.

{
  "type": "object",
  "properties": {
    "prefix": {
      "type": "string",
      "description": "Return only tokens that start with this string. Examples: \"--dwc-color-primary-\" for every primary-palette shade, \"--dwc-space-\" for spacing, \"--dwc-color-\" for all color tokens."
    },
    "contains": {
      "type": "string",
      "description": "Return only tokens that contain this substring anywhere. Useful for cross-palette queries like \"seed\" (all palette seeds) or \"text\" (all text-contrast shades)."
    },
    "webforjVersion": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+(-SNAPSHOT)?$",
      "description": "The webforJ version you are targeting, exactly as it appears in the project's pom.xml: a released major.minor like \"25.12\", or the current upcoming SNAPSHOT like \"26.00-SNAPSHOT\" (only the next unreleased version is published as SNAPSHOT; there is just one active SNAPSHOT at any time). Read it from pom.xml or ask the user."
    },
    "reasoning": {
      "type": "string",
      "minLength": 1,
      "description": "Your step-by-step reasoning for why you are calling this tool and what you expect it to return. Stating it explicitly before the call helps you pick the right arguments, avoid redundant calls, and stay on the documented routing path for this tool."
    }
  },
  "required": [
    "webforjVersion",
    "reasoning"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Validate every --dwc-* reference in CSS, Java, MDX, or Markdown text against the real DWC global tokens and component CSS variables. Returns the list of invalid tokens with line numbers and ranked similar-name suggestions. Run this on any generated or edited stylesheet before writing it to disk.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "minLength": 1,
      "description": "The CSS, Java, Markdown, or MDX text to scan. Every --dwc-* reference is checked against the real DWC global tokens and the component CSS variables for the target webforJ version."
    },
    "webforjVersion": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+(-SNAPSHOT)?$",
      "description": "The webforJ version you are targeting, exactly as it appears in the project's pom.xml: a released major.minor like \"25.12\", or the current upcoming SNAPSHOT like \"26.00-SNAPSHOT\" (only the next unreleased version is published as SNAPSHOT; there is just one active SNAPSHOT at any time). Read it from pom.xml or ask the user."
    },
    "reasoning": {
      "type": "string",
      "minLength": 1,
      "description": "Your step-by-step reasoning for why you are calling this tool and what you expect it to return. Stating it explicitly before the call helps you pick the right arguments, avoid redundant calls, and stay on the documented routing path for this tool."
    }
  },
  "required": [
    "content",
    "webforjVersion",
    "reasoning"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Validate fully qualified class names against the catalog of types declared in webforJ source for the target version. Accepts either an explicit list of FQCNs or a Java snippet (the handler extracts its import statements). Returns unknown FQCNs with ranked similar-name suggestions. FQCNs outside the webforJ package family are not validated. Run this on any generated or edited Java before writing it to disk.

{
  "type": "object",
  "properties": {
    "imports": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1,
      "description": "A list of fully qualified class names to validate. Pass one or many; each entry is checked independently. Use this field when you already have the FQCN strings in hand. Provide either this field OR `content`, never both in the same call."
    },
    "content": {
      "type": "string",
      "minLength": 1,
      "description": "A Java source snippet or file. The handler extracts every `import X.Y.Z;` line it contains and validates each FQCN against the catalog. Static imports and wildcard imports are skipped. Provide either this field OR `imports`, never both in the same call."
    },
    "webforjVersion": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+(-SNAPSHOT)?$",
      "description": "The webforJ version you are targeting, exactly as it appears in the project's pom.xml: a released major.minor like \"25.12\", or the current upcoming SNAPSHOT like \"26.00-SNAPSHOT\" (only the next unreleased version is published as SNAPSHOT; there is just one active SNAPSHOT at any time). Read it from pom.xml or ask the user."
    },
    "reasoning": {
      "type": "string",
      "minLength": 1,
      "description": "Your step-by-step reasoning for why you are calling this tool and what you expect it to return. Stating it explicitly before the call helps you pick the right arguments, avoid redundant calls, and stay on the documented routing path for this tool."
    }
  },
  "required": [
    "webforjVersion",
    "reasoning"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Generate a webforJ theme from a primary HSL color. Returns two content blocks: a JSON summary with theme metadata, @AppTheme / @StyleSheet snippets, and recommended file paths, plus a second text block prefixed "CSS_CONTENT:" containing the full stylesheet.

{
  "type": "object",
  "properties": {
    "primaryColor": {
      "type": "array",
      "minItems": 3,
      "maxItems": 3,
      "items": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 360,
          "description": "Hue (0-360)"
        },
        {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Saturation (0-100)"
        },
        {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Lightness (0-100)"
        }
      ],
      "description": "Primary color in HSL format: [hue, saturation, lightness]. Example: [220, 70, 50] for blue."
    },
    "themeName": {
      "type": "string",
      "description": "Optional theme name for multi-theme applications. Omit for global CSS overrides."
    },
    "infoDegree": {
      "type": "number",
      "minimum": 0,
      "maximum": 360,
      "description": "Degree offset for info/secondary color (pre-25.12 only, default: 180)."
    },
    "tintBaseSaturation": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "Base saturation for neutral grey tints (pre-25.12 only, default: 10)."
    },
    "tintScaleFactor": {
      "type": "number",
      "description": "Scale factor for tint generation (pre-25.12 only, default: 0)."
    },
    "step": {
      "type": "number",
      "minimum": 1,
      "maximum": 20,
      "description": "Step size for contrast calculations (pre-25.12 only, default: 5)."
    },
    "detectPrimaryColorCategory": {
      "type": "boolean",
      "description": "Auto-detect color category for optimization (pre-25.12 only, default: true)."
    },
    "contrastSensitiveLightness": {
      "type": "boolean",
      "description": "Use contrast-sensitive lightness calculations (pre-25.12 only, default: false)."
    },
    "webforjVersion": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+(-SNAPSHOT)?$",
      "description": "The webforJ version you are targeting, exactly as it appears in the project's pom.xml: a released major.minor like \"25.12\", or the current upcoming SNAPSHOT like \"26.00-SNAPSHOT\" (only the next unreleased version is published as SNAPSHOT; there is just one active SNAPSHOT at any time). Read it from pom.xml or ask the user."
    },
    "reasoning": {
      "type": "string",
      "minLength": 1,
      "description": "Your step-by-step reasoning for why you are calling this tool and what you expect it to return. Stating it explicitly before the call helps you pick the right arguments, avoid redundant calls, and stay on the documented routing path for this tool."
    }
  },
  "required": [
    "primaryColor",
    "webforjVersion",
    "reasoning"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}