Core API Methods

Complete reference for all public methods in flowmcp-core. Methods are organized by usage category. All methods are static.

import { FlowMCP } from 'flowmcp-core'

FlowMCP Core exports both v2 (default) and v1 APIs. This reference covers the v2 API. For v1 methods, import from flowmcp-core/v1.

Method Overview

Method	Purpose	Returns
`.loadSchema()`	Load and validate a v2 schema file	`{ status, main, handlerMap }`
`.validateMain()`	Validate a main export against 79 rules	`{ status, messages }`
`.scanSecurity()`	Run security scan on a schema file	`{ status, messages }`
`.fetch()`	Execute an API request for a route	`{ status, dataAsString, messages }`
`.resolveSharedLists()`	Resolve shared list references	`{ sharedLists }`
`.interpolateEnum()`	Interpolate shared list values into enum templates	`{ result }`
`.loadLibraries()`	Load declared libraries from allowlist	`{ libraries }`
`.createHandlers()`	Create handler map from factory function	`{ handlerMap }`
`.detectLegacy()`	Detect if a module uses v1 format	`{ isLegacy, format }`
`.adaptLegacy()`	Convert a v1 schema to v2 format	`{ main, handlersFn, hasHandlers, warnings }`
`.getDefaultAllowlist()`	Get the default library allowlist	`{ allowlist }`
`.generateOutputSchema()`	Generate output schema from API response	`{ output }`

Schema Loading & Validation

.loadSchema()

Loads a .mjs schema file, runs security scanning, validates the main export, resolves shared lists, loads declared libraries, and creates the handler map. This is the primary entry point for working with schemas.Method

const result = await FlowMCP.loadSchema( { filePath, listsDir, allowlist } )

Parameters

Key	Type	Description	Required
`filePath`	string	Absolute or relative path to the `.mjs` schema file	Yes
`listsDir`	string	Directory containing shared list files	No
`allowlist`	array	Allowed library names for handlers. Uses default if omitted	No

Example

import { FlowMCP } from 'flowmcp-core'

const { status, main, handlerMap } = await FlowMCP.loadSchema( {
    filePath: './schemas/coingecko-price.mjs'
} )

if( !status ) {
    console.error( 'Schema loading failed' )
}

// Use the loaded schema
const result = await FlowMCP.fetch( {
    main,
    handlerMap,
    userParams: { id: 'bitcoin' },
    serverParams: {},
    routeName: 'getPrice'
} )

Returns

{
    status: true,          // false if loading, validation, or security scan failed
    main: { ... },         // The validated main export object
    handlerMap: { ... }    // Route-keyed handler functions (empty object if no handlers)
}

.validateMain()

Validates a main export object against the FlowMCP v2.0.0 specification. Runs 79 validation rules across 12 categories including structure, naming, parameters, security, and output declarations.Method

const { status, messages } = FlowMCP.validateMain( { main } )

Parameters

Key	Type	Description	Required
`main`	object	The `main` export from a schema file	Yes

Example

import { FlowMCP } from 'flowmcp-core'
import { main } from './schemas/coingecko-price.mjs'

const { status, messages } = FlowMCP.validateMain( { main } )

if( status ) {
    console.log( 'Schema is valid' )
} else {
    console.error( 'Validation failed:' )
    messages.forEach( ( msg ) => console.error( `  - ${msg}` ) )
}

Returns

{
    status: true,      // true if all 79 rules pass
    messages: []       // Array of error messages when status is false
}

Use validateMain() during development to catch schema errors early. In production, use loadSchema() which includes validation as part of the full pipeline.

.scanSecurity()

Runs a static security scan on a schema file. Checks for forbidden patterns like import statements, require() calls, filesystem access, eval(), and other disallowed constructs.Method

const { status, messages } = await FlowMCP.scanSecurity( { filePath } )

Parameters

Key	Type	Description	Required
`filePath`	string	Path to the `.mjs` schema file to scan	Yes

Example

import { FlowMCP } from 'flowmcp-core'

const { status, messages } = await FlowMCP.scanSecurity( {
    filePath: './schemas/my-schema.mjs'
} )

if( !status ) {
    console.error( 'Security violations found:' )
    messages.forEach( ( msg ) => console.error( `  - ${msg}` ) )
}

Returns

{
    status: true,      // false if forbidden patterns are detected
    messages: []       // Descriptions of security violations
}

Execution

.fetch()

Executes an HTTP request for a specific route using the loaded schema. Handles parameter substitution, URL construction, header injection, and optional pre/post-processing via handlers.Method

const result = await FlowMCP.fetch( { main, handlerMap, userParams, serverParams, routeName } )

Parameters

Key	Type	Description	Required
`main`	object	The validated `main` export from a schema	Yes
`handlerMap`	object	Handler map from `loadSchema()` or `createHandlers()`	Yes
`userParams`	object	User-provided parameters (from AI client input)	Yes
`serverParams`	object	Server-side parameters (API keys, tokens)	Yes
`routeName`	string	Name of the route to execute	Yes

Example

import { FlowMCP } from 'flowmcp-core'

const { status, main, handlerMap } = await FlowMCP.loadSchema( {
    filePath: './schemas/coingecko-price.mjs'
} )

const result = await FlowMCP.fetch( {
    main,
    handlerMap,
    userParams: { id: 'bitcoin', vs_currency: 'usd' },
    serverParams: {},
    routeName: 'getPrice'
} )

if( result.status ) {
    console.log( 'Response:', result.dataAsString )
} else {
    console.error( 'Request failed:', result.messages )
}

Returns

{
    status: true,                              // false if request failed
    dataAsString: '{"bitcoin":{"usd":45000}}', // Response body as string
    messages: []                               // Error messages when status is false
}

The serverParams object should contain API keys and secrets. These values are injected into headers and parameters at runtime but are never exposed to AI clients.

Shared Lists & Dependencies

.resolveSharedLists()

Resolves shared list references from a directory of list files. Shared lists are reusable value collections (chain IDs, token symbols, protocol names) that schemas reference via $listName syntax in enum parameters.Method

const { sharedLists } = await FlowMCP.resolveSharedLists( { sharedListRefs, listsDir } )

Parameters

Key	Type	Description	Required
`sharedListRefs`	array	Array of shared list reference strings from the schema	Yes
`listsDir`	string	Directory path containing shared list `.mjs` files	Yes

Example

import { FlowMCP } from 'flowmcp-core'

const { sharedLists } = await FlowMCP.resolveSharedLists( {
    sharedListRefs: [ 'evmChains', 'stablecoins' ],
    listsDir: './lists/'
} )

console.log( 'Resolved lists:', Object.keys( sharedLists ) )
// Output: ['evmChains', 'stablecoins']

Returns

{
    sharedLists: {
        evmChains: [ 'ethereum', 'polygon', 'arbitrum', ... ],
        stablecoins: [ 'USDT', 'USDC', 'DAI', ... ]
    }
}

.interpolateEnum()

Interpolates shared list values into an enum template string. Replaces $listName references with actual values from resolved shared lists.Method

const { result } = FlowMCP.interpolateEnum( { template, sharedLists } )

Parameters

Key	Type	Description	Required
`template`	string	Enum template containing `$listName` references	Yes
`sharedLists`	object	Resolved shared lists from `resolveSharedLists()`	Yes

Example

import { FlowMCP } from 'flowmcp-core'

const sharedLists = {
    evmChains: [ 'ethereum', 'polygon', 'arbitrum' ]
}

const { result } = FlowMCP.interpolateEnum( {
    template: '$evmChains',
    sharedLists
} )

console.log( result )
// Output: ['ethereum', 'polygon', 'arbitrum']

Returns

{
    result: [ 'ethereum', 'polygon', 'arbitrum' ]  // Resolved enum values
}

.loadLibraries()

Loads npm packages declared in a schema’s requiredLibraries field. Only packages on the allowlist can be loaded. This enforces the zero-import security model.Method

const { libraries } = await FlowMCP.loadLibraries( { requiredLibraries, allowlist } )

Parameters

Key	Type	Description	Required
`requiredLibraries`	array	Library names declared in the schema	Yes
`allowlist`	array	Permitted library names. Use `getDefaultAllowlist()` for defaults	Yes

Example

import { FlowMCP } from 'flowmcp-core'

const { allowlist } = FlowMCP.getDefaultAllowlist()

const { libraries } = await FlowMCP.loadLibraries( {
    requiredLibraries: [ 'ethers' ],
    allowlist
} )

// libraries.ethers is now available for handler injection

Returns

{
    libraries: {
        ethers: { ... }  // The loaded library module
    }
}

.getDefaultAllowlist()

Returns the default library allowlist. These are the npm packages that handlers are permitted to use via dependency injection.Method

const { allowlist } = FlowMCP.getDefaultAllowlist()

ParametersNone.Example

import { FlowMCP } from 'flowmcp-core'

const { allowlist } = FlowMCP.getDefaultAllowlist()
console.log( 'Allowed libraries:', allowlist )

Returns

{
    allowlist: [ 'ethers', 'viem', ... ]  // Array of permitted library names
}

Handler Management

.createHandlers()

Creates a handler map by invoking the handlers factory function with injected dependencies. The resulting map is keyed by route name and contains preProcess and postProcess functions.Method

const { handlerMap } = FlowMCP.createHandlers( { handlersFn, sharedLists, libraries, routeNames } )

Parameters

Key	Type	Description	Required
`handlersFn`	function	The `handlers` factory function from a schema	Yes
`sharedLists`	object	Resolved shared lists to inject	Yes
`libraries`	object	Loaded libraries to inject	Yes
`routeNames`	array	Expected route names for validation	Yes

Example

import { FlowMCP } from 'flowmcp-core'
import { handlers } from './schemas/my-schema.mjs'

const { handlerMap } = FlowMCP.createHandlers( {
    handlersFn: handlers,
    sharedLists: { evmChains: [ 'ethereum', 'polygon' ] },
    libraries: {},
    routeNames: [ 'getPrice', 'getHistory' ]
} )

// handlerMap.getPrice.postProcess is now available

Returns

{
    handlerMap: {
        getPrice: {
            postProcess: async ( { data } ) => { ... }
        },
        getHistory: {
            preProcess: async ( { params } ) => { ... },
            postProcess: async ( { data } ) => { ... }
        }
    }
}

You rarely need to call createHandlers() directly. The loadSchema() pipeline handles handler creation automatically. Use this method when you need manual control over the dependency injection process.

Legacy Compatibility

.detectLegacy()

Detects whether a loaded module uses the v1 schema format. Returns the detected format version.Method

const { isLegacy, format } = FlowMCP.detectLegacy( { module } )

Parameters

Key	Type	Description	Required
`module`	object	The imported module from a `.mjs` schema file	Yes

Example

import { FlowMCP } from 'flowmcp-core'

const schemaModule = await import( './schemas/old-schema.mjs' )
const { isLegacy, format } = FlowMCP.detectLegacy( { module: schemaModule } )

if( isLegacy ) {
    console.log( `Legacy format detected: ${format}` )
    // Use adaptLegacy() to convert
}

Returns

{
    isLegacy: true,    // true if the module uses v1 format
    format: 'v1'       // Detected format version string
}

.adaptLegacy()

Converts a v1 schema object to the v2 two-export format. Returns the adapted main export, optional handlers factory function, and any conversion warnings.Method

const { main, handlersFn, hasHandlers, warnings } = FlowMCP.adaptLegacy( { legacySchema } )

Parameters

Key	Type	Description	Required
`legacySchema`	object	A v1 format schema object	Yes

Example

import { FlowMCP } from 'flowmcp-core'

const oldSchema = { namespace: 'myapi', root: '...', routes: { ... } }
const { main, handlersFn, hasHandlers, warnings } = FlowMCP.adaptLegacy( {
    legacySchema: oldSchema
} )

if( warnings.length > 0 ) {
    console.log( 'Migration warnings:' )
    warnings.forEach( ( w ) => console.log( `  - ${w}` ) )
}

// Use the adapted schema with v2 methods
const result = await FlowMCP.fetch( {
    main,
    handlerMap: {},
    userParams: { ... },
    serverParams: {},
    routeName: 'myRoute'
} )

Returns

{
    main: { ... },             // Converted main export
    handlersFn: Function|null, // Handlers factory (null if no handlers)
    hasHandlers: false,        // Whether the schema had handlers
    warnings: []               // Conversion warnings (deprecated features, etc.)
}

Output Schema Generation

.generateOutputSchema()

Generates an output schema from a captured API response. The output schema declares the expected response shape for downstream consumers and documentation.Method

const { output } = FlowMCP.generateOutputSchema( { response, mimeType } )

Parameters

Key	Type	Description	Required
`response`	string	Raw API response body	Yes
`mimeType`	string	Response MIME type (e.g. `application/json`)	Yes

Example

import { FlowMCP } from 'flowmcp-core'

const { output } = FlowMCP.generateOutputSchema( {
    response: '{"bitcoin":{"usd":45000,"eur":38000}}',
    mimeType: 'application/json'
} )

console.log( output )
// { type: 'object', fields: { bitcoin: { type: 'object', fields: { ... } } } }

Returns

{
    output: {
        type: 'object',
        fields: { ... }    // Inferred field structure from the response
    }
}

Use this method during schema development to auto-generate the output block for your routes. Capture a real API response with fetch(), then pass it to generateOutputSchema().

v1 API (Legacy)

The v1 API is still available for backward compatibility. Import it separately:

import { v1 } from 'flowmcp-core'
const { FlowMCP } = v1

v1 Method Overview

The v1 API uses a flat schema format (single export) with different method signatures.

Method	v1 Signature	v2 Equivalent
`.validateSchema()`	`FlowMCP.validateSchema( { schema } )`	`.validateMain( { main } )`
`.fetch()`	`FlowMCP.fetch( { schema, userParams, serverParams, routeName } )`	`.fetch( { main, handlerMap, ... } )`
`.activateServerTools()`	`FlowMCP.activateServerTools( { server, schema, serverParams } )`	Use MCP SDK directly with `.loadSchema()`
`.activateServerTool()`	`FlowMCP.activateServerTool( { server, schema, routeName, serverParams } )`	Use MCP SDK directly
`.prepareServerTool()`	`FlowMCP.prepareServerTool( { schema, serverParams, routeName } )`	Use `.loadSchema()` + `.fetch()`
`.filterArrayOfSchemas()`	`FlowMCP.filterArrayOfSchemas( { arrayOfSchemas, ... } )`	Same (v1 only)
`.getArgvParameters()`	`FlowMCP.getArgvParameters( { argv } )`	Same (v1 only)
`.getZodInterfaces()`	`FlowMCP.getZodInterfaces( { schema } )`	Zod schemas are generated during `.loadSchema()`
`.getAllTests()`	`FlowMCP.getAllTests( { schema } )`	Test values are in parameter `test` fields

The v1 API will be maintained for backward compatibility but will not receive new features. All new schemas should use the v2 format.

Typical Workflow

The standard workflow for using FlowMCP Core combines these methods:

import { FlowMCP } from 'flowmcp-core'

// 1. Load schema (validates, scans security, resolves lists, creates handlers)
const { status, main, handlerMap } = await FlowMCP.loadSchema( {
    filePath: './schemas/coingecko-price.mjs'
} )

if( !status ) {
    throw new Error( 'Schema loading failed' )
}

// 2. Execute a route
const result = await FlowMCP.fetch( {
    main,
    handlerMap,
    userParams: { id: 'bitcoin' },
    serverParams: { API_KEY: process.env.COINGECKO_KEY },
    routeName: 'getPrice'
} )

// 3. Use the result
if( result.status ) {
    console.log( 'Price data:', result.dataAsString )
} else {
    console.error( 'Errors:', result.messages )
}

For MCP server integration, see the Server Integration Guide.

Getting Started

Specification v2.0.0

Guides

Ecosystem

Reference

Method Overview

Schema Loading & Validation

Execution

Shared Lists & Dependencies

Handler Management

Legacy Compatibility

Output Schema Generation

v1 API (Legacy)

Typical Workflow

Getting Started

Specification v2.0.0

Guides

Ecosystem

Reference

​Method Overview

​Schema Loading & Validation

​Execution

​Shared Lists & Dependencies

​Handler Management

​Legacy Compatibility

​Output Schema Generation

​v1 API (Legacy)

​Typical Workflow

Method Overview

Schema Loading & Validation

Execution

Shared Lists & Dependencies

Handler Management

Legacy Compatibility

Output Schema Generation

v1 API (Legacy)

Typical Workflow