FlowMCP (Core)

FlowMCP is a schema-based framework that bridges existing web APIs (e.g., REST or GraphQL) with AI systems. It standardizes interaction using a universal format called the Model Context Protocol (MCP).

---

✨ Purpose

FlowMCP abstracts complex APIs into clean, structured schema definitions, enabling seamless AI-driven communication with external services. These schemas eliminate ambiguity and ensure compatibility through versioned contracts.

---

🔧 Core Features

Schema-Based Integration – Each route is described in a structured schema that AI systems can interpret.
Modifier System – Pre-, post-, and execute-phase handlers enable transformation and logic injection.
Inline Parameters with Zod Validation – Parameters use inline formatting with built-in type enforcement.
Test Coverage – Each route supports embedded test cases to verify real-world API interactions.
Text-Based Output – Results are returned in clear, human-readable format.

requestMethod: "GET" or "POST"
description: Summary of the endpoint
route: URL path with optional placeholders (e.g., /item/:id)
parameters: Input list, defined inline
tests: Array of input samples with _description
modifiers: Required array with phase and handlerName. If not in use set to []

{ position: { key: "id", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["length(24)"] } }

string()
number()
boolean()
enum(...)

length(n)
min(n), max(n)
regex(pattern)
optional()
default(value)

tests: [
    { _description: "Sample test", id: "abc123xyz456789def000000" }
]

_description is required
Only declared parameter keys are allowed
All fields must match schema structure

modifiers: [
    { phase: "pre", handlerName: "prepareQuery" },
    { phase: "post", handlerName: "transformOutput" },
    { phase: "execute", handlerName: "customFetcher" }
]

Phases: "pre", "post", "execute"
Each handler must exist in handlers block

handlers: {
    normalizeResult: async ({ struct, payload }) => {
        if (!struct.data?.result) {
            struct.status = false;
            struct.messages.push("Missing result data");
        } else {
            struct.data = struct.data.result;
        }
        return { struct, payload };
    }
}

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { FlowMCP } from 'flowMCP'
import { schema } from './schema.mjs'
const server = new McpServer({

    name: 'Schema Tester',

    description: 'Local server for schema testing',

    version: '1.2.2'

})
FlowMCP.activateServerTools({

    server,

    schema,

    serverParams: { API_KEY: 'abc123' }

})
await server.connect(new StdioServerTransport())

FlowMCP.activateServerTools(...)
FlowMCP.getAllTests(...)
FlowMCP.fetch(...)
FlowMCP.validateSchema(...)
FlowMCP.prepareActivations(...)
FlowMCP.getArgvParameters(...)

Always use 4-space indentation
Parameters and modifiers must be one-liners
Leave two blank lines before export { schema };
Declare constants (e.g. enums, helper mappings) above the schema

chainlink
luksoNetwork
coingecko
poap
solanatracker


• etherscan, dexscreener, moralis, and more...



import { schema } from './schemas/chainlink/getLatestPrices.mjs'

Just describe the API behavior in plain English, and the tool will produce a valid .mjs schema file ready to use with FlowMCP.

This README is written for FlowMCP schema specification version 1.2.2`.