FlowMCP enforces validation rules when loading schemas, shared lists, groups, resources, and skills. Each rule has a code, severity level, and description. Run validation with flowmcp validate <schema-path>.
Severity Description Effect errorMust fix before use Schema cannot be loaded warningShould fix Schema loads with warnings infoNice to have Informational only
flowmcp validate etherscan/contracts.mjs
VAL014 error main.version: Must match ^3 \.\d + \.\d + $ (found "2.0.0" )
VAL031 error tools: Maximum 8 tools exceeded (found 10 )
VAL036 warning getContractAbi: output schema is recommended
TST001 warning getContractAbi: No tests found
Schema cannot be loaded (has errors )
Code Severity Rule VAL001 error Schema must export main as named export VAL002 error main must be an objectVAL003 error main must not contain unknown fieldsVAL004 error handlers (if exported) must be a functionVAL005 warning handlers function must return an object with keys matching tool names
Code Severity Rule VAL010 error main.namespace is required and must be a stringVAL011 error main.namespace must match ^[a-z]+$VAL012 error main.name is required and must be a stringVAL013 error main.description is required and must be a stringVAL014 error main.version is required and must match ^3\.\d+\.\d+$VAL015 error main.root is required and must be a valid URLVAL016 error main.tools is required and must be a non-empty object
Code Severity Rule VAL020 error main.docs (if present) must be an array of stringsVAL021 error main.tags (if present) must be an array of stringsVAL022 error main.requiredServerParams (if present) must be an array of stringsVAL023 error main.headers (if present) must be a plain objectVAL024 error main.sharedLists (if present) must be an array of objectsVAL025 error main.requiredLibraries (if present) must be an array of stringsVAL026 error Each entry in requiredLibraries must be on the runtime allowlist
Code Severity Rule VAL030 error Tool name must match ^[a-z][a-zA-Z0-9]*$ VAL031 error Maximum 8 tools per schema VAL032 error tool.method is required and must be GET, POST, PUT, or DELETEVAL033 error tool.path is required and must be a string starting with /VAL034 error tool.description is required and must be a stringVAL035 error tool.parameters is required and must be an arrayVAL036 warning tool.output is recommended for new schemasVAL037 info tool.async is a reserved field (not executed in v3.0.0)
Code Severity Rule VAL040 error Each parameter must have position and z objects VAL041 error position.key is required and must be a stringVAL042 error position.value is required and must be a stringVAL043 error position.location must be insert, query, or bodyVAL044 error z.primitive is required and must be a valid primitive typeVAL045 error z.options must be an array of stringsVAL046 error enum() values must not be emptyVAL047 error Shared list interpolation {{listName:fieldName}} is only allowed in enum() VAL048 error Referenced shared list must be declared in main.sharedLists VAL049 error Referenced field must exist in the shared list’s meta.fields VAL050 error insert parameters must have a corresponding {{key}} in tool.path
Code Severity Rule VAL060 error output.mimeType must be a supported MIME typeVAL061 error output.schema must be a valid schema definitionVAL062 error output.schema.type must match MIME type expectationsVAL063 warning Nested depth should not exceed 4 levels VAL064 error properties is only valid when type is objectVAL065 error items is only valid when type is array
Code Severity Rule VAL070 error sharedLists[].ref is required and must be a stringVAL071 error sharedLists[].version is required and must be semverVAL072 error Referenced list must exist in the list registry VAL073 error Referenced list version must match or be compatible VAL074 error filter (if present) must have valid key fieldVAL075 warning Unused shared list reference (not used by any parameter or handler)
Code Severity Rule SEC001 error Forbidden pattern found in schema file — no import statements allowed SEC002 error main block contains non-serializable value (function, symbol, etc.)SEC003 error Shared list file contains forbidden pattern SEC004 error Shared list file contains executable code SEC005 error requiredLibraries contains unapproved package
See Security Model for the complete list of forbidden patterns and error codes.
Code Severity Rule LST001 error List must export list as named export LST002 error list.meta.name is required and must be uniqueLST003 error list.meta.version is required and must be semverLST004 error list.meta.fields is required and must be a non-empty arrayLST005 error Each field must have key, type, and description LST006 error list.entries is required and must be a non-empty arrayLST007 error Each entry must have all required fields LST008 error Entry field types must match meta.fields type declarations LST009 error dependsOn references must resolve to existing listsLST010 error Circular dependencies are forbidden LST011 error Maximum dependency depth: 3 levels
Code Severity Rule GRP001 error Group name must match ^[a-z][a-z0-9-]*$ GRP002 error Maximum 50 tools per group GRP003 error Tool reference must follow namespace/file::type::name format GRP004 error All referenced tools must be resolvable GRP005 error Duplicate tool references are forbidden GRP006 error Group hash must match calculated hash
Code Severity Rule TST001 error Each tool must have at least 1 test TST002 error Each test must have a _description field of type string TST003 error Each test must provide values for all required {{USER_PARAM}} parameters TST004 error Test parameter values must pass the corresponding z validation TST005 error Test objects must be JSON-serializable TST006 error Test objects must only contain keys matching {{USER_PARAM}} parameter keys or _description TST007 warning Tools with enum or chain parameters should test multiple enum values TST008 info Consider adding tests that demonstrate optional parameter usage
See Tests for the complete test specification.
Code Severity Rule PRM001 error Skill name must match ^[a-z][a-z0-9-]*$ PRM002 error File must exist at declared path PRM003 error File must have # Title (first line) PRM004 error File must have ## Workflow section PRM005 warning Tool references must resolve in group PRM006 error Group must have at least one tool PRM007 error No duplicate skill names within a group PRM008 error Filename must match skill name
See Groups & Skills for skill format details.
Code Severity Rule RES001 error resources (if present) must be an objectRES002 error Resource name must match ^[a-z][a-zA-Z0-9]*$ RES003 error Maximum 2 resources per schema RES004 error resource.description is required and must be a stringRES005 error resource.source must be 'sqlite'RES006 error resource.database is required and must be a string ending in .dbRES007 error resource.queries is required and must be a non-empty objectRES008 error Maximum 4 queries per resource RES009 error Query name must match ^[a-z][a-zA-Z0-9]*$ RES010 error query.description is required and must be a stringRES011 error query.sql is required and must be a stringRES012 error SQL must start with SELECT (read-only enforcement) RES013 error SQL must not contain blocked patterns RES014 error SQL must use ? placeholders (no string interpolation) RES015 error Number of ? placeholders must match number of parameters RES016 error query.parameters (if present) must be an arrayRES017 error Each query parameter must have key, type, and description RES018 error Query parameter type must be string, number, or boolean RES019 error Query parameter key must match ^[a-z][a-zA-Z0-9]*$ RES020 error No duplicate parameter keys within a query RES021 error Database file must exist at schema-relative path (runtime check) RES022 warning Consider adding tests to resource queries RES023 error SQL must not contain subqueries with write operations
Code Severity Rule SKL001 error skills (if present) must be an arraySKL002 error Maximum 4 skills per schema SKL003 error Each skill entry must have name, file, and description SKL004 error Skill name must match ^[a-z][a-z0-9-]*$ SKL005 error Skill file must end in .mjs SKL006 error Skill file must exist at schema-relative path SKL007 error Skill file must export skill as named export SKL008 error skill.name must match the name in main.skills entrySKL009 error skill.version must be 'flowmcp-skill/1.0.0'SKL010 error skill.description is required and must be a stringSKL011 error skill.content is required and must be a non-empty stringSKL012 error skill.requires must be an object with tools, resources, and external arraysSKL013 error Each requires.tools entry must match a tool name in the schema SKL014 error Each requires.resources entry must match a resource name in the schema SKL015 error skill.input (if present) must be an arraySKL016 error Each input must have key, type, description, and required fields SKL017 error Input key must match ^[a-z][a-zA-Z0-9]*$ SKL018 error Input type must be string, number, or boolean SKL019 error No duplicate input keys within a skill SKL020 error skill.output (if present) must be a stringSKL021 warning {{tool:x}} placeholders should reference tools in requires.toolsSKL022 warning {{resource:x}} placeholders should reference resources in requires.resourcesSKL023 warning {{input:x}} placeholders should reference input keysSKL024 error {{skill:x}} placeholders must reference other skills in the schemaSKL025 error No circular skill references via {{skill:x}} placeholders
Code Severity Rule DEP001 warning main.routes is deprecated — use main.tools insteadDEP002 info Legacy ::routeName format in groups — use ::tool::routeName discriminator DEP003 warning prompts key in groups.json — renamed to skillsDEP004 info version: '2.x.x' detected — run flowmcp migrate to upgrade