FlowMCP

By a6b8 GitHub

A modular framework for building, validating, and testing REST API routes using declarative schemas and zod interfaces.

mcp mcp-server

Overview

What is FlowMCP?

FlowMCP is a modular framework designed for building, validating, and testing REST API routes using declarative schemas and zod interfaces. It simplifies the integration of various REST APIs by providing a unified schema system with built-in validation.

How to use FlowMCP?

To use FlowMCP, install it via npm and define your API schema. You can then execute API requests and automatically generate tests based on the schema.

Key features of FlowMCP?

Automatically generates zod interfaces from API schemas
Standardized routing for REST endpoints
Built-in test generation
Supports API-specific transformation logic via modifiers
Easily extensible using JSON-like schema definitions

Use cases of FlowMCP?

Building and validating REST API clients
Testing API endpoints with automatically generated test cases
Integrating multiple APIs with different structures into a single framework

FAQ from FlowMCP?

Can FlowMCP handle any REST API?

Yes! FlowMCP is designed to work with any REST API by defining the appropriate schema.

Is FlowMCP free to use?

Yes! FlowMCP is open-source and available for free.

How does FlowMCP ensure API validation?

FlowMCP uses zod interfaces for validation, ensuring that API requests and responses conform to the defined schema.

Content

FlowMCP

FlowMCP provides a declarative and modular approach to integrating various REST APIs using a unified schema system with zod-based validation. Its goal is to make APIs easy to consume, test, and extend — even when they differ greatly in structure and design.

Features

Automatically generates zod interfaces from API schemas
Standardized routing for REST endpoints
Built-in test generation
Supports API-specific transformation logic via modifiers
Easily extensible using JSON-like schema definitions

Quickstart

Installation

npm install a6b8/flowMCP#beta

Example Usage

Define your API schema (e.g. testSchema.mjs) and execute a request using FlowMCP:

import { testSchema as schema } from "./tests/data/testSchema.mjs";
import { FlowMCP } from "flowmcp";

const serverParams = { ETHERSCAN_API_KEY: 'your-api-key-here' };

// Load automatically generated tests
const tests = FlowMCP.getAllTests({ schema });
const [routeName, userParams] = tests[0];

// Execute API request
const { status, messages, data } = await FlowMCP.fetch({
  schema,
  userParams,
  serverParams,
  routeName
});

console.log('status:', status);
console.log('data:', data);

FlowMCP

Overview

At the core of FlowMCP is a declarative API schema that defines all aspects of an interface: endpoints, parameters, validation, tests, and processing logic. FlowMCP transforms this schema into fully functioning, tested API clients.

Methods

`getZodInterfaces({ schema })`

Generates zod-based validation interfaces from the schema.

FlowMCP.getZodInterfaces({ schema });

`getAllTests({ schema })`

Returns all test cases defined in the schema.

const tests = FlowMCP.getAllTests({ schema });

`fetch({ schema, userParams, serverParams, routeName })`

Executes the API request as defined in the schema.

const result = await FlowMCP.fetch({
  schema,
  userParams,
  serverParams,
  routeName
});

Schema

An example of a compatible (simplified) schema:

const testSchema = {
  root: "https://api.etherscan.io",
  vars: ["ETHERSCAN_API_KEY"],
  routes: {
    getContractABI: {
      requestMethod: "GET",
      description: "Returns the Contract ABI of a verified smart contract.",
      route: "/api",
      parameters: [
        { position: ["module", "contract", "query"] },
        { position: ["action", "getabi", "query"] },
        { position: ["address", "{{USER_PARAM}}", "query"], z: ["string", "min(42)", "max(42)"] },
        { position: ["apikey", "{{ETHERSCAN_API_KEY}}", "query"] }
      ],
      tests: [
        {
          _description: "Basic test for getContractABI",
          address: "0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413"
        }
      ],
      modifiers: [["post", "convertToJSON"]]
    }
  },
  modifiers: {
    convertToJSON: async (struct) => {
      if (struct.data.status !== "1") {
        struct.status = false;
        struct.messages.push(struct.data.message);
        return struct;
      }
      struct.data = struct.data.result;
      return struct;
    }
  }
};