Skip to main content

Quick Reference

Schema Template

import { FlowMCP } from './src/index.mjs'

const schema = {
  // Required
  namespace: "github",              // Letters only
  root: "https://api.github.com",   // Valid URL
  
  // Routes (all fields required)
  routes: {
    getUser: {
      requestMethod: "GET",
      route: "/users/{{USER_PARAM}}",
      parameters: [
        { position: { key: "username", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["min(1)", "max(39)"] } }
      ],
      modifiers: []
    }
  },
  
  // Optional
  headers: { "Authorization": "Bearer {{GITHUB_TOKEN}}" },
  tags: ['production', 'development']
}

Parameter Patterns

// Query parameter (URL query string)
{ position: { key: "page", value: "{{USER_PARAM}}", location: "query" }, z: { primitive: "number()", options: ["min(1)", "max(100)", "int()"] } }

// Insert parameter (URL path substitution) 
{ position: { key: "username", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["min(1)", "max(39)"] } }

// Body parameter (JSON body)
{ position: { key: "data", value: "{{USER_PARAM}}", location: "body" }, z: { primitive: "object()", options: [] } }

// Header parameter
{ position: { key: "X-API-Key", value: "{{USER_PARAM}}", location: "header" }, z: { primitive: "string()", options: ["length(32)"] } }

Validation Options

TypeOptionsExample
string()min(), max(), length(), regex(), email(), url(){ primitive: "string()", options: ["min(1)"] }
number()min(), max(), int(), positive(), negative(){ primitive: "number()", options: ["min(0)"] }
boolean()None{ primitive: "boolean()", options: [] }
array()min(), max(), length(){ primitive: "array()", options: ["min(1)"] }
object()Custom shape definitions{ primitive: "object()", options: [] }

MCP Server Setup

Basic Server Creation

import { FlowMCP } from './src/index.mjs'
import { Server } from '@modelcontextprotocol/sdk/server/index.js'

// Create MCP server
const server = new Server({
  name: 'my-flowmcp-server',
  version: '1.0.0'
}, {
  capabilities: { tools: {} }
})

// Transform schemas into MCP tools
const { mcpTools } = FlowMCP.activateServerTools({
  server,
  schema: githubSchema,
  serverParams: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }
})

console.log('Active tools:', Object.keys(mcpTools))

Multiple Schemas

const schemas = [githubSchema]

schemas.forEach(schema => {
  FlowMCP.activateServerTools({
    server,
    schema,
    serverParams: {
      GITHUB_TOKEN: process.env.GITHUB_TOKEN
    }
  })
})

Core Methods

import { FlowMCP } from './src/index.mjs'

// Validate schema
const { status, messages } = FlowMCP.validateSchema({ schema })

// Execute API call
const result = await FlowMCP.fetch({
  schema,
  userParams: { username: 'octocat' },
  serverParams: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
  routeName: 'getUser'
})

// Filter schemas
const { filteredArrayOfSchemas } = FlowMCP.filterArrayOfSchemas({
  arrayOfSchemas: schemas,
  includeNamespaces: ['github'],
  excludeNamespaces: [],
  activateTags: []
})

Claude Desktop Configuration

Config Location:
  • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "flowmcp": {
      "command": "node",
      "args": ["/absolute/path/to/server.mjs"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxx"
      }
    }
  }
}

Common Patterns

Authentication Headers

// Bearer token
headers: { "Authorization": "Bearer {{API_TOKEN}}" }

// API key header
headers: { "X-API-Key": "{{API_KEY}}" }

// GitHub token format
headers: { "Authorization": "token {{GITHUB_TOKEN}}" }

// Basic auth
headers: { "Authorization": "Basic {{BASE64_CREDENTIALS}}" }

Error Handling

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

if (result.status) {
  const data = JSON.parse(result.dataAsString)
  console.log('Success:', data)
} else {
  console.error('API Error:', result.messages)
}

Schema Filtering

// Include specific namespaces
const { filteredArrayOfSchemas } = FlowMCP.filterArrayOfSchemas({
  arrayOfSchemas: allSchemas,
  includeNamespaces: ['github'],
  excludeNamespaces: [],
  activateTags: [
    'production',     // Include production schemas
    'github.getUser'  // Include specific route
  ]
})

Debugging Commands

# Validate schema
node -e "import('./src/index.mjs').then(({FlowMCP}) => console.log(FlowMCP.validateSchema({schema})))"

# Test API call
node -e "import('./src/index.mjs').then(({FlowMCP}) => FlowMCP.fetch({schema, userParams, serverParams, routeName}).then(console.log))"

# Check environment variables
node -e "console.log(process.env.GITHUB_TOKEN)"

Project Structure

project/
├── src/
│   └── index.mjs    # FlowMCP Core
├── schemas/
│   └── github.mjs   # Schema definitions
├── server.mjs       # MCP server
├── package.json
└── .env

Package.json Template

{
  "name": "my-flowmcp-server",
  "type": "module",
  "scripts": {
    "start": "node server.mjs",
    "dev": "node server.mjs"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0"
  }
}

Complete Server Example

import { FlowMCP } from './src/index.mjs'
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { githubSchema } from './schemas/github.mjs'

// Create MCP server
const server = new Server({
  name: 'multi-api-server',
  version: '1.0.0'
}, {
  capabilities: { tools: {} }
})

// Server parameters for API authentication
const serverParams = {
  GITHUB_TOKEN: process.env.GITHUB_TOKEN
}

// Validate and activate schemas
const schemas = [githubSchema]

schemas.forEach(schema => {
  // Validate schema
  const validation = FlowMCP.validateSchema({ schema })
  if (!validation.status) {
    console.error(`Schema ${schema.namespace} invalid:`, validation.messages)
    return
  }

  // Activate schema as MCP tools
  const { mcpTools } = FlowMCP.activateServerTools({
    server,
    schema,
    serverParams,
    validate: true
  })

  console.log(`✅ Activated ${schema.namespace}: ${Object.keys(mcpTools).join(', ')}`)
})

console.log('🚀 FlowMCP server ready for Claude Desktop')

Common Issues

Schema Validation Errors

// ❌ Wrong namespace (no hyphens/numbers)
namespace: "github-api"  // Use: "github"

// ❌ Missing required fields
routes: {
  getUser: {
    requestMethod: "GET"  // Missing: route, parameters, modifiers
  }
}

// ✅ Complete route definition
routes: {
  getUser: {
    requestMethod: "GET",
    route: "/users/{{USER_PARAM}}",
    parameters: [
      { position: { key: "username", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["min(1)", "max(39)"] } }
    ],
    modifiers: []
  }
}

Environment Variables

# Check if variables are set
echo $GITHUB_TOKEN

# Set variables (Linux/Mac)
export GITHUB_TOKEN="ghp_xxxxx"

# Set variables (Windows)
set GITHUB_TOKEN=ghp_xxxxx