### Start flAPI Server and Ping

Source: https://github.com/datazoode/flapi/blob/main/cli/Readme.md

Examples for starting the flAPI server with a configuration file and then pinging the server to verify its responsiveness using the Node.js CLI.

```bash
./build/release/flapi --port 8080 --config examples/flapi.yaml
```

```bash
node dist/index.js ping --base-url http://localhost:8080
```

--------------------------------

### Complete FLAPI Main Configuration Example (flapi.yaml)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

A comprehensive `flapi.yaml` example demonstrating project info, template settings, multiple database connections (BigQuery, Parquet, PostgreSQL), DuckDB configuration, global rate limiting, and HTTPS setup. This file defines the overall FLAPI application behavior.

```yaml
# Project Information
project_name: enterprise-api
project_description: Enterprise data API with multiple sources
server_name: production-server

# Template Configuration
template:
  path: './sqls'
  environment-whitelist:
    - '^FLAPI_.*'
    - '^DB_.*'

# Database Connections
connections:
  # BigQuery connection
  bigquery-warehouse:
    init: |
      FORCE INSTALL 'bigquery' FROM 'http://storage.googleapis.com/hafenkran';
      LOAD 'bigquery';
    properties:
      project_id: 'my-gcp-project'
      dataset: 'analytics'
    log-queries: true
    log-parameters: false
    allow: '*'

  # Parquet files
  customer-data:
    properties:
      path: './data/customers.parquet'
    log-queries: false

  # PostgreSQL connection
  postgres-orders:
    init: |
      INSTALL postgres_scanner;
      LOAD postgres_scanner;
    properties:
      host: 'localhost'
      port: '5432'
      database: 'orders'
      user: 'flapi_user'
      password: '${DB_PASSWORD}'

# DuckDB Configuration
duckdb:
  db_path: ./enterprise_cache.db
  access_mode: READ_WRITE
  threads: 8
  max_memory: 8GB
  default_order: DESC

# Global Rate Limiting
rate-limit:
  enabled: true
  max: 1000
  interval: 3600  # 1 hour

# HTTPS Configuration
enforce-https:
  enabled: true
  ssl-cert-file: './ssl/cert.pem'
  ssl-key-file: './ssl/key.pem'

# Global Heartbeat
heartbeat:
  enabled: true
  worker-interval: 30
```

--------------------------------

### Setup Python Virtual Environment and Install Dependencies

Source: https://github.com/datazoode/flapi/blob/main/test/integration/README.md

Commands to create and activate a Python virtual environment, and then install project dependencies using uv.

```bash
uv venv
source .venv/bin/activate

uv pip install -e .
```

--------------------------------

### Complex FLAPI Endpoint Configuration Example

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

An example of a complex FLAPI endpoint configuration that integrates multiple features, including dynamic URL paths using environment variables, demonstrating a more advanced setup.

```yaml
# Main endpoint configuration
url-path: /analytics/{{env.API_VERSION}}/customers
```

--------------------------------

### Install and Build flapii CLI

Source: https://github.com/datazoode/flapi/blob/main/cli/Readme.md

Instructions for installing and building the flapii CLI. It covers using 'make cli-build' from the repo root, or manual steps using npm within the 'cli' directory. It also shows how to run the CLI without global installation using 'npx'.

```bash
# from repo root
make cli-build   # installs deps and builds the CLI
```

```bash
cd cli
npm ci
npm run build
```

```bash
# from repo root
npx ./cli --help
npx ./cli ping
```

```bash
# from inside the cli directory
cd cli && npx . --help
cd cli && npx . ping
```

```bash
# ensure a fresh build first
npm --prefix cli run build && npx ./cli ping
```

```bash
# run the compiled file directly
node cli/dist/index.js --help
```

```bash
# or use npm exec
npm exec --prefix cli flapii -- --help
```

--------------------------------

### Documenting Customer Endpoint Configuration (YAML)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Provides an example of documenting a customer endpoint configuration in FLAPI with comments explaining its purpose, request parameters, connection details, and caching strategy.

```yaml
# Customer data endpoint
# Provides access to customer information with optional filtering
url-path: /customers

request:
  - field-name: segment
    field-in: query
    description: Filter customers by segment (premium, standard, basic)
    required: false
    validators:
      - type: enum
        allowedValues: [premium, standard, basic]

# Use customer data connection (Parquet files)
connection: [customer-data]

# Cache results for 30 minutes to improve performance
cache:
  enabled: true
  cache-table-name: customers_cache
  refresh-time: 30m
```

--------------------------------

### Unified Configuration Example (MCP Resource Only)

Source: https://github.com/datazoode/flapi/blob/main/Readme.md

Example of a YAML configuration file defining only an MCP resource.

```APIDOC
## Unified Configuration Example (MCP Resource Only)

### Description
This example shows a YAML configuration file that defines solely an MCP resource (`mcp-resource`). This resource provides schema definitions and can be accessed via the MCP server.

### Method
POST (via JSON-RPC to `tools/call` with `name: customer_schema`)

### Endpoint
`/mcp/jsonrpc`

### Request Body (MCP Tool Call - `customer_schema`)
- **jsonrpc** (string) - Required - "2.0"
- **id** (integer or string) - Required - Request identifier.
- **method** (string) - Required - "tools/call"
- **params** (object) - Required
  - **name** (string) - Required - "customer_schema"
  - **arguments** (object) - Optional - Any arguments required by the schema retrieval process.

### Request Example (MCP Tool Call)
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "customer_schema"
  }
}
```

### Response (MCP Tool Call - JSON-RPC Success)
- **jsonrpc** (string) - "2.0"
- **id** (integer or string) - The request identifier.
- **result** (object) - The schema definition for the customer database.

### Response Example (MCP Tool Call)
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "schema": {
      "id": "integer",
      "name": "string",
      "email": "string"
    }
  }
}
```
```

--------------------------------

### Unified Configuration Example (REST Endpoint + MCP Tool)

Source: https://github.com/datazoode/flapi/blob/main/Readme.md

Example of a single YAML configuration file defining both a REST endpoint and an MCP tool.

```APIDOC
## Unified Configuration Example (REST Endpoint + MCP Tool)

### Description
This example demonstrates how a single YAML file can define a REST endpoint (`url-path`) and an MCP tool (`mcp-tool`) simultaneously. It includes request parameter validation, rate limiting, and authentication.

### Method
GET (for REST endpoint), POST (for MCP tool call via JSON-RPC)

### Endpoint
`/customers/` (REST endpoint)
`/mcp/jsonrpc` (MCP tool call)

### Parameters (REST Endpoint)
#### Query Parameters
- **id** (integer) - Optional - Customer ID. Must be between 1 and 1000000. `preventSqlInjection` is enabled.

### Request Body (MCP Tool Call - `get_customers`)
- **jsonrpc** (string) - Required - "2.0"
- **id** (integer or string) - Required - Request identifier.
- **method** (string) - Required - "tools/call"
- **params** (object) - Required
  - **name** (string) - Required - "get_customers"
  - **arguments** (object) - Required
    - **id** (string) - Optional - The ID of the customer to retrieve.

### Request Example (REST)
```
GET /customers/?id=123
```

### Request Example (MCP Tool Call)
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_customers",
    "arguments": {
      "id": "123"
    }
  }
}
```

### Response (REST Endpoint - 200 OK)
- **customer_data** (object) - Information about the customer.

### Response Example (REST Endpoint)
```json
{
  "customer_data": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}
```

### Response (MCP Tool Call - JSON-RPC Success)
- **jsonrpc** (string) - "2.0"
- **id** (integer or string) - The request identifier.
- **result** (object) - The result of the `get_customers` tool call.

### Response Example (MCP Tool Call)
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "customer_data": {
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }
}
```
```

--------------------------------

### Scenario 1: Multi-Source Analytics API

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

An example of creating an API that combines data from BigQuery, PostgreSQL, and local Parquet files using FLAPI.

```APIDOC
## Scenario 1: Multi-Source Analytics API

**Goal**: Create an API that combines data from BigQuery, PostgreSQL, and local Parquet files.

```yaml
# flapi.yaml
project_name: analytics-hub
project_description: Multi-source analytics API

template:
  path: './endpoints'

connections:
  bigquery-warehouse:
    init: |
      FORCE INSTALL 'bigquery' FROM 'http://storage.googleapis.com/hafenkran';
      LOAD 'bigquery';
    properties:
      project_id: 'analytics-project'
      dataset: 'warehouse'

  postgres-transactions:
    init: |
      INSTALL postgres_scanner;
      LOAD postgres_scanner;
    properties:
      host: '{{env.POSTGRES_HOST}}'
      database: 'transactions'
      user: '{{env.POSTGRES_USER}}'
      password: '{{env.POSTGRES_PASSWORD}}'

  local-customers:
    properties:
      path: './data/customers.parquet'

duckdb:
  db_path: ./analytics_cache.db
  threads: 8
  max_memory: 16GB
```
```

--------------------------------

### Environment Variable Usage Examples in YAML

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Demonstrates various ways to use environment variables within YAML configuration files for dynamic values.

```yaml
# In any string value
database_url: '{{env.DATABASE_URL}}'
password: '{{env.DB_PASSWORD}}'
api_key: '{{env.API_KEY}}'

# In connection properties
connections:
  my-db:
    properties:
      host: '{{env.DB_HOST}}'
      port: '{{env.DB_PORT}}'
      user: '{{env.DB_USER}}'
      password: '{{env.DB_PASSWORD}}'

# In file paths
template-source: 'queries-{{env.ENVIRONMENT}}.sql'

# In include paths
{{include from config/{{env.ENVIRONMENT}}-settings.yaml}}
```

--------------------------------

### Multi-Source Analytics API Setup (YAML)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Defines a Flapi project for an analytics hub, configuring connections to BigQuery, PostgreSQL, and local Parquet files, along with DuckDB settings.

```yaml
# flapi.yaml
project_name: analytics-hub
project_description: Multi-source analytics API

template:
  path: './endpoints'

connections:
  bigquery-warehouse:
    init: |
      FORCE INSTALL 'bigquery' FROM 'http://storage.googleapis.com/hafenkran';
      LOAD 'bigquery';
    properties:
      project_id: 'analytics-project'
      dataset: 'warehouse'

  postgres-transactions:
    init: |
      INSTALL postgres_scanner;
      LOAD postgres_scanner;
    properties:
      host: '{{env.POSTGRES_HOST}}'
      database: 'transactions'
      user: '{{env.POSTGRES_USER}}'
      password: '{{env.POSTGRES_PASSWORD}}'

  local-customers:
    properties:
      path: './data/customers.parquet'

duckdb:
  db_path: ./analytics_cache.db
  threads: 8
  max_memory: 16GB
```

--------------------------------

### SQL Template Example

Source: https://github.com/datazoode/flapi/blob/main/Readme.md

Example of a SQL template using Mustache syntax to dynamically generate SQL queries based on endpoint parameters and connection properties.

```APIDOC
## SQL Template Example (e.g., ./sqls/customers.sql)

### Description
This section shows an example of a SQL template file that uses the Mustache templating language. It dynamically constructs SQL queries by referencing connection properties (like `conn.path`) and request parameters (like `params.id`).

### Method
N/A (SQL Template file)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```sql
SELECT * FROM '{{{conn.path}}}'
WHERE 1=1
{{#params.id}}
  AND c_custkey = {{{ params.id }}}
{{/params.id}}
```

### Response
N/A (SQL Template file)
```

--------------------------------

### YAML Syntax Correction Example (YAML)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Illustrates a common YAML syntax error related to incorrect indentation in FLAPI configuration and shows the corrected version for proper parsing.

```yaml
# ❌ Bad - inconsistent indentation
request:
  - field-name: id
    field-in: query
  description: Customer ID  # Wrong indentation

# ✅ Good - consistent indentation
request:
  - field-name: id
    field-in: query
    description: Customer ID
```

--------------------------------

### Flapi CLI - Endpoint Management (Bash)

Source: https://context7.com/datazoode/flapi/llms.txt

Commands for managing flAPI endpoints using the TypeScript CLI. Includes installation, configuration, listing, getting details, validation, reloading, and testing endpoints.

```bash
# Install CLI globally
npm install -g @flapi/cli

# Configure CLI
flapi config show
flapi config set base-url http://localhost:8080
flapi config set auth-token YOUR_TOKEN
flapi config set log-level debug

# List all endpoints
flapi endpoints list
flapi endpoints list --output json

# Get endpoint details
flapi endpoints get /customers/
flapi endpoints get customer_lookup  # MCP tool by name

# Validate endpoint YAML before deployment
flapi endpoints validate /customers/ -f ./sqls/customers.yaml

# Reload endpoint from disk (hot reload)
flapi endpoints reload /customers/

# Test endpoint with parameters
flapi endpoints test /customers/ --params '{"id": 123}'

```

--------------------------------

### Interact with MCP Tools using cURL

Source: https://github.com/datazoode/flapi/blob/main/examples/sqls/customers/README.md

This section shows how to use cURL to communicate with MCP (Microservice Communication Protocol) tools. It includes examples for listing available tools and calling a specific tool like 'customer_lookup' with arguments. The MCP service is expected to be running on http://localhost:8081.

```bash
# List available MCP tools
curl -X POST http://localhost:8081/mcp/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

# Call customer lookup tool
curl -X POST http://localhost:8081/mcp/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "customer_lookup", "arguments": {"id": "123"} } }'
```

--------------------------------

### BigQuery Connection Configuration (YAML)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Defines a production BigQuery connection for FLAPI, including installation of the BigQuery module, connection properties like project ID and dataset, and query logging settings.

```yaml
connections:
  prod-bigquery:
    init: |
      FORCE INSTALL 'bigquery' FROM 'http://storage.googleapis.com/hafenkran';
      LOAD 'bigquery';
    properties:
      project_id: 'production-project'
      dataset: 'analytics'
    log-queries: false
    log-parameters: false
```

--------------------------------

### Basic Authentication Configuration (YAML)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Sets up basic authentication with a list of users, their passwords, and assigned roles.

```yaml
auth:
  enabled: true
  type: basic
  users:
    - username: admin
      password: admin_password
      roles: [admin, read, write]
    - username: readonly
      password: readonly_password
      roles: [read]
```

--------------------------------

### FLAPIMCPClient Basic Usage

Source: https://github.com/datazoode/flapi/blob/main/test/integration/README.md

Example of using the FLAPIMCPClient for basic MCP testing, including connection, listing tools, and calling a tool.

```python
client = FLAPIMCPClient("http://localhost:8080")
await client.connect()
tools = await client.list_tools()
result = await client.call_tool("get_customers", {"id": "1"})
```

--------------------------------

### Template and Connection Configuration

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Specifies the SQL template file and connections to be used.

```APIDOC
## Template and Connection Configuration

### Description
Specify the SQL template file and the list of connections to use.

### Parameters
#### Request Body
- **template-source** (string) - Required. SQL template file name
- **connection** (array) - Required. List of connection names to use
  - string - Connection name from main config
```

--------------------------------

### YAML Includes

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Demonstrates modular configuration using YAML includes for entire files, specific sections, and relative path resolution.

```APIDOC
## YAML Includes

### Description
Allows modularization of FLAPI configurations by including content from other YAML files, supporting full file inclusion, section inclusion, and relative path resolution.

### File Include Example
```yaml
{{include from common/auth.yaml}}
{{include from common/rate-limit.yaml}}

url-path: /customers
template-source: customers.sql
```

### Section Include Example
```yaml
url-path: /customers
{{include:request from common/customer-request.yaml}}
{{include:auth from common/basic-auth.yaml}}
template-source: customers.sql
```

### Relative Path Resolution Example
```yaml
{{include from ../shared/database-config.yaml}}
{{include from ./local-overrides.yaml}}
```
```

--------------------------------

### Send GET Request with Basic Auth and jq Formatting

Source: https://github.com/datazoode/flapi/blob/main/Readme.md

Demonstrates how to send a GET request to a local flapi endpoint using curl, including basic authentication with admin:secret credentials. The output is piped to jq for pretty-printing the JSON response. This is useful for testing API endpoints.

```bash
> curl -X GET -u admin:secret "http://localhost:8080/customers?id=123" | jq .

{
  "next": "",
  "total_count": 1,
  "data": [
    {
      "c_mktsegment": "BUILDING",
      "c_acctbal": 5897.82999999999992724,
      "c_phone": "15-817-151-1168",
      "c_address": "YsOnaaER8MkvK5cpf4VSlq",
      "c_nationkey": 5,
      "c_name": "Customer#000000123",
      "c_comment": "ependencies. regular, ironic requests are fluffily regu",
      "c_custkey": 123
    }
  ]
}

```

--------------------------------

### Retrieve MCP Prompts with cURL

Source: https://github.com/datazoode/flapi/blob/main/examples/sqls/customers/README.md

This example demonstrates how to use cURL to fetch prompts from the MCP service, which can be used for AI-driven analysis. It shows retrieving the 'customer_data_analysis' prompt with specified arguments like customer ID, analysis type, and time period. The MCP service is available at http://localhost:8081.

```bash
# Get customer analysis prompt
curl -X POST http://localhost:8081/mcp/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 4, "method": "prompts/get", "params": { "name": "customer_data_analysis", "arguments": { "customer_id": "123", "analysis_type": "behavioral", "time_period": "last_90_days" } } }'
```

--------------------------------

### MCP Prompt Configuration

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Configuration for an MCP prompt, including its name, description, template, and arguments.

```APIDOC
## MCP Prompt Configuration

### Description
Configure an MCP prompt with name, description, template, and arguments.

### Parameters
#### Request Body
- **mcp-prompt** (object) - Required. MCP prompt configuration.
  - **name** (string) - Required. Prompt name for MCP protocol
  - **description** (string) - Required. Human-readable prompt description
  - **template** (string) - Required. Prompt template with placeholders
  - **arguments** (array) - Required. List of template arguments
    - string - Argument name
```

--------------------------------

### Path Resolution

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Explains how Flapi resolves include paths, covering relative, absolute, and search path configurations.

```APIDOC
## Path Resolution

### Relative Paths
Include paths are resolved relative to the file containing the include directive.

**Directory Structure:**
```
flapi.yaml
├── endpoints/
│   ├── customers.yaml
│   └── orders.yaml
├── common/
│   ├── auth.yaml
│   └── database.yaml
└── config/
    ├── dev.yaml
    └── prod.yaml
```

**Path Examples:**
```yaml
# From endpoints/customers.yaml
{{include from ../common/auth.yaml}}        # Go up one level, then to common/
{{include from ../config/dev.yaml}}        # Go up one level, then to config/
{{include from ./local-overrides.yaml}}    # Same directory as customers.yaml

# From flapi.yaml (root)
{{include from common/auth.yaml}}           # Direct path to common/
{{include from endpoints/shared.yaml}}     # Direct path to endpoints/
```

### Absolute Paths
You can use absolute paths for includes outside your project:

```yaml
{{include from /etc/flapi/global-config.yaml}}
{{include from /home/user/shared-configs/auth.yaml}}
```

### Search Paths
Configure additional search paths for includes:

```yaml
# This feature is configured in the ExtendedYamlParser
# Currently used internally, may be exposed in future versions
```
```

--------------------------------

### Environment Variables in Includes

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Demonstrates how to use environment variables for dynamic path resolution and content substitution within included files.

```APIDOC
## Environment Variables in Includes

### Variable Substitution in Paths
Use environment variables to make include paths dynamic:

**Syntax:**
```yaml
{{include from path/{{env.VARIABLE_NAME}}/file.yaml}}
```

**Examples:**
```yaml
# Environment-specific configuration
{{include from config/{{env.ENVIRONMENT}}-database.yaml}}
{{include from config/{{env.ENVIRONMENT}}-auth.yaml}}

# Dynamic file selection
{{include from templates/{{env.TEMPLATE_TYPE}}.yaml}}
{{include from connections/{{env.DATA_SOURCE}}-connection.yaml}}

# Combined with section includes
{{include:auth from security/{{env.AUTH_PROVIDER}}-config.yaml}}
```

**Environment Setup:**
```bash
export ENVIRONMENT=production
export TEMPLATE_TYPE=advanced
export DATA_SOURCE=bigquery
export AUTH_PROVIDER=oauth2
```

### Variable Substitution in File Content
Environment variables are also substituted in the content of included files:

```yaml
# config/production-database.yaml
connections:
  prod-db:
    properties:
      host: '{{env.DB_HOST}}'
      password: '{{env.DB_PASSWORD}}'
      database: '{{env.DB_NAME}}'
```
```

--------------------------------

### Conditional Includes

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Explains how to conditionally include files based on environment variables or boolean logic.

```APIDOC
## Conditional Includes

### Basic Conditions
Include files only when certain conditions are met:

**Syntax:**
```yaml
{{include from file_path if condition}}
{{include:section from file_path if condition}}
```

### Environment Variable Conditions
```yaml
# Include if environment variable is set and non-empty
{{include from debug-config.yaml if env.DEBUG_MODE}}
{{include from ssl-config.yaml if env.ENABLE_SSL}}

# Include based on environment
{{include from dev-tools.yaml if env.ENVIRONMENT}}
```

### Boolean Conditions
```yaml
# Always include (useful for temporary enabling/disabling)
{{include from optional-config.yaml if true}}

# Never include (useful for temporary disabling)
{{include from experimental-config.yaml if false}}
```

### Condition Evaluation Rules
- **Environment variables**:
  - `true` if variable exists and is non-empty
  - `false` if variable doesn't exist or is empty string
- **Boolean literals**: `true` and `false` are supported
- **Missing conditions**: If condition cannot be evaluated, include is skipped

**Examples:**
```bash
# These will include the file
export ENABLE_AUTH=1
export ENABLE_AUTH=true  
export ENABLE_AUTH=yes

# These will NOT include the file
export ENABLE_AUTH=
export ENABLE_AUTH=false
unset ENABLE_AUTH
```
```

--------------------------------

### Basic File Include in YAML

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Shows how to include the entire content of another YAML file using the `{{include from ...}}` directive.

```yaml
# main.yaml
project_name: my-project
{{include from common/database-config.yaml}}
{{include from common/auth-config.yaml}}

# common/database-config.yaml
connections:
  main-db:
    properties:
      path: './data/main.parquet'

# common/auth-config.yaml  
auth:
  enabled: true
  type: basic
  users:
    - username: admin
      password: secret
```

--------------------------------

### Template and Connection Configuration (YAML)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Specifies the 'template-source' file and a list of 'connection' names required for an endpoint.

```yaml
template-source: string         # Required. SQL template file name
connection:                     # Required. List of connection names to use
  - string                      # Connection name from main config
```

--------------------------------

### MCP Prompt Configuration

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Configuration for an MCP Prompt, which defines AI prompt templates with placeholders for dynamic arguments.

```APIDOC
## MCP Prompt Configuration

### Description
Defines an MCP Prompt template for AI interactions. The template uses placeholders for dynamic arguments that can be provided during prompt execution.

### Method
N/A (prompt is executed)

### Endpoint
N/A (prompt is executed by name)

### Parameters
N/A (arguments are defined within the prompt configuration)

### Request Example
```yaml
mcp-prompt:
  name: customer_analysis
  description: Generate customer analysis report
  template: |
    Analyze the customer data for segment: {{segment}}
    
    Focus on:
    1. Customer behavior patterns
    2. Revenue trends for {{time_period}}
    3. Recommendations for {{analysis_type}}
    
    Use the available customer data to provide insights.
  
  arguments:
    - segment
    - time_period
    - analysis_type
```

### Response
#### Success Response (200)
- **result** (string) - The generated text output from the AI prompt.

#### Response Example
```json
{
  "result": "Analysis of customer data for premium segment during Q4 2023 shows positive revenue trends..."
}
```
```

--------------------------------

### Advanced Include Patterns

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Covers advanced include patterns like nested includes and complex conditional logic for sophisticated configuration management.

```APIDOC
## Advanced Include Patterns

### Nested Includes
Included files can contain their own include directives:

```yaml
# main.yaml
{{include from config/base.yaml}}

# config/base.yaml
project_name: my-project
{{include from database/{{env.DB_TYPE}}.yaml}}
{{include from auth/{{env.AUTH_TYPE}}.yaml}}

# database/postgres.yaml
connections:
  main:
    {{include from ../connection-templates/postgres-template.yaml}}

# connection-templates/postgres-template.yaml
init: |
  INSTALL postgres_scanner;
  LOAD postgres_scanner;
properties:
  host: '{{env.POSTGRES_HOST}}'
  database: '{{env.POSTGRES_DB}}'
```

### Complex Conditional Logic
```yaml
# Include different configurations based on environment
{{include from config/development.yaml if env.ENVIRONMENT}}
{{include from config/staging.yaml if env.ENVIRONMENT}}  
{{include from config/production.yaml if env.ENVIRONMENT}}
```
```

--------------------------------

### MCP Prompt Configuration (YAML)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Configures an MCP Prompt endpoint, requiring 'name', 'description', 'template', and 'arguments'. The template can include placeholders.

```yaml
mcp-prompt:
  name: string                  # Required. Prompt name for MCP protocol
  description: string           # Required. Human-readable prompt description
  template: string              # Required. Prompt template with placeholders
  arguments:                    # Required. List of template arguments
    - string                    # Argument name
```

--------------------------------

### Flapi Server Deployment (Docker & Binary)

Source: https://context7.com/datazoode/flapi/llms.txt

Provides commands to start the flAPI server using Docker or a native binary. It includes volume mounting for configuration files and port mapping for accessibility.

```bash
# Start flAPI server with config
docker run -it --rm \
  -p 8080:8080 -p 8081:8081 \
  -v $(pwd)/examples/:/config \
  ghcr.io/datazoode/flapi:latest \
  -c /config/flapi.yaml

# Or for native binary:
./flapi -c ./flapi.yaml

```

--------------------------------

### Environment Variable Substitution

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Illustrates how to use environment variables within FLAPI configurations for dynamic settings like connection properties and include paths.

```APIDOC
## Environment Variable Substitution

### Description
Enables the use of environment variables in FLAPI configurations to dynamically set values for connections, API keys, and file paths.

### Example
```yaml
connections:
  production-db:
    properties:
      host: '{{env.DB_HOST}}'
      password: '{{env.DB_PASSWORD}}'
      api_key: '{{env.BIGQUERY_API_KEY}}'

# Environment variable in include paths
{{include from common/{{env.ENVIRONMENT}}-config.yaml}}
```
```

--------------------------------

### GET /customers

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Retrieves customer information. The customer ID can be specified as a query parameter.

```APIDOC
## GET /customers

### Description
Retrieves customer information. The customer ID can be specified as a query parameter.

### Method
GET

### Endpoint
/customers

### Parameters
#### Query Parameters
- **customer_id** (int) - Required - The ID of the customer to retrieve. Must be a positive integer.
```

--------------------------------

### Basic FLAPI Main Configuration (flapi.yaml)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Sets up a basic FLAPI project with project details, SQL template path, a Parquet database connection, and DuckDB settings. This serves as the entry point for FLAPI applications.

```yaml
# Basic project setup
project_name: my-api-project
project_description: My first FLAPI project

# SQL templates directory
template:
  path: './sqls'

# Database connection
connections:
  my-data:
    properties:
      path: './data/customers.parquet'

# DuckDB settings
duckdb:
  db_path: ./flapi_cache.db
  threads: 4
  max_memory: 2GB
```

--------------------------------

### Test Basic Endpoint with Curl

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Sends a GET request to a basic FLAPI endpoint '/customers' with a query parameter 'id'. Used for verifying endpoint accessibility and basic functionality.

```bash
curl "http://localhost:8080/customers?id=123"
```

--------------------------------

### Directory Structure for FLAPI Project (Text)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Illustrates a recommended directory structure for organizing FLAPI project files, including main configuration, endpoints, common modules, and environment-specific configuration files.

```text
flapi.yaml
├── endpoints/
│   ├── customers/
│   │   ├── customers.yaml
│   │   ├── customer-analytics.yaml
│   │   └── customer-segments.yaml
│   └── orders/
│       ├── orders.yaml
│       └── order-history.yaml
├── common/
│   ├── auth.yaml
│   ├── rate-limits.yaml
│   └── connections.yaml
└── config/
    ├── development.yaml
    ├── staging.yaml
    └── production.yaml
```

--------------------------------

### Building flapi from Source (Linux)

Source: https://github.com/datazoode/flapi/blob/main/Readme.md

Provides the necessary commands to build the flapi project from its C++ source code on a Linux system. Includes installing dependencies, checking out the repository, and running the build command.

```bash
sudo apt-get install -y build-essential cmake ninja-build
git clone --recurse-submodules https://github.com/datazoode/flapi.git
cd flapi
make release
```

--------------------------------

### Test Endpoint with Authentication using Curl

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Sends a GET request to a FLAPI endpoint '/customers' with basic authentication (username and password) and a query parameter 'id'. Useful for testing secured endpoints.

```bash
curl -u "username:password" "http://localhost:8080/customers?id=123"
```

--------------------------------

### YAML Include: Configuration Variants

Source: https://github.com/datazoode/flapi/blob/main/examples/sqls/customers/README.md

Illustrates how to select specific configuration variants using YAML includes. This allows for fine-grained control over settings such as authentication methods, rate limits, and caching policies.

```yaml
# Select specific configuration variants
{{include:auth-dev from common/customer-common.yaml}}      # Development auth
{{include:auth-prod from common/customer-common.yaml}}     # Production JWT auth
{{include:rate-limit-high from common/customer-common.yaml}} # High-traffic limits
{{include:rate-limit-ai from common/customer-common.yaml}}   # AI tool limits
{{include:cache-performance from common/customer-common.yaml}} # High-perf cache
```

--------------------------------

### Flapi CLI Commands

Source: https://context7.com/datazoode/flapi/llms.txt

Examples of using the Flapi command-line interface to manage and inspect MCP resources and tools. These commands allow users to retrieve specific tool configurations and list available resources or prompts.

```shell
# Get specific tool configuration
flapi mcp tools get customer_lookup

# List MCP resources
flapi mcp resources list

# List MCP prompts
flapi mcp prompts list
```

--------------------------------

### Correcting Include Path Resolution (YAML)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Provides an example of correctly specifying relative paths for the `include` directive in FLAPI configuration to resolve module paths, especially when files are in different directories.

```yaml
# If your structure is:
# endpoints/customers.yaml
# common/auth.yaml

# Use:
{{include from ../common/auth.yaml}}
```

--------------------------------

### Manual MCP Endpoint Initialization Request

Source: https://github.com/datazoode/flapi/blob/main/test/integration/README.md

Example cURL command to manually send an 'initialize' request to the FLAPI MCP JSON-RPC endpoint.

```bash
curl -s http://localhost:8080/mcp/jsonrpc -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{},"resources":{},"prompts":{},"sampling":{}}}}'
```

--------------------------------

### YAML Include: Basic Shared Configuration

Source: https://github.com/datazoode/flapi/blob/main/examples/sqls/customers/README.md

Demonstrates basic YAML includes to reference shared configuration components from a consolidated file. This approach reduces file duplication and improves organization by centralizing common settings.

```yaml
# Include sections from consolidated configuration file
{{include:request from common/customer-common.yaml}}
{{include:auth from common/customer-common.yaml}}
{{include:rate-limit from common/customer-common.yaml}}
```

--------------------------------

### YAML Include: Environment-Aware Configuration

Source: https://github.com/datazoode/flapi/blob/main/examples/sqls/customers/README.md

Shows how to implement environment-aware configurations using conditional YAML includes. This allows different configuration sections to be loaded based on environment variables, such as selecting development or production authentication.

```yaml
# Different authentication based on environment
{{include:auth from common/customer-auth-dev.yaml if env.ENVIRONMENT}}
{{include:auth from common/customer-auth-prod.yaml if env.ENVIRONMENT}}
```

--------------------------------

### GET /analytics/customers

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Retrieves customer analytics data, allowing filtering by customer segment and date range. This endpoint combines data from multiple sources including local customer data, transaction logs, and warehouse metrics.

```APIDOC
## GET /analytics/customers

### Description
Retrieves customer analytics data, allowing filtering by customer segment and date range. This endpoint combines data from multiple sources including local customer data, transaction logs, and warehouse metrics.

### Method
GET

### Endpoint
/analytics/customers

### Parameters
#### Query Parameters
- **customer_segment** (string) - Optional - Customer segment to analyze. Allowed values: premium, standard, basic.
- **date_range** (integer) - Optional - Analysis date range in days. Defaults to 30. Must be between 1 and 365.

### Request Example
```json
{
  "query": {
    "customer_segment": "premium",
    "date_range": "90"
  }
}
```

### Response
#### Success Response (200)
- **customer_id** (string) - The unique identifier for the customer.
- **segment** (string) - The customer segment.
- **registration_date** (string) - The date the customer registered.
- **total_spent** (number) - The total amount spent by the customer.
- **transaction_count** (integer) - The number of transactions made by the customer.
- **engagement_score** (number) - The customer's engagement score from the warehouse.
- **lifetime_value** (number) - The customer's lifetime value from the warehouse.

#### Response Example
```json
{
  "customer_id": "cust123",
  "segment": "premium",
  "registration_date": "2023-01-15",
  "total_spent": 1500.75,
  "transaction_count": 25,
  "engagement_score": 85,
  "lifetime_value": 5000.00
}
```
```

--------------------------------

### Nested Includes with Environment Variables (YAML)

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Illustrates advanced include patterns where included files can themselves contain include directives, forming a hierarchical configuration structure. This example shows nested includes combined with environment variable substitution for database and authentication configurations.

```yaml
# main.yaml
{{include from config/base.yaml}}

# config/base.yaml
project_name: my-project
{{include from database/{{env.DB_TYPE}}.yaml}}
{{include from auth/{{env.AUTH_TYPE}}.yaml}}

# database/postgres.yaml
connections:
  main:
    {{include from ../connection-templates/postgres-template.yaml}}

# connection-templates/postgres-template.yaml
init: |
  INSTALL postgres_scanner;
  LOAD postgres_scanner;
properties:
  host: '{{env.POSTGRES_HOST}}'
  database: '{{env.POSTGRES_DB}}'
```

--------------------------------

### List All Templates (CLI)

Source: https://github.com/datazoode/flapi/blob/main/cli/Readme.md

Lists all available templates using the flapi CLI. Requires specifying the output format, base URL, and configuration file.

```bash
node dist/index.js templates list --output table \
  --base-url http://localhost:8080 --config examples/flapi.yaml
```

--------------------------------

### YAML Include: Original Multi-File Approach

Source: https://github.com/datazoode/flapi/blob/main/examples/sqls/customers/README.md

Presents the original, multi-file approach to managing configuration components. Each configuration aspect (request fields, authentication, rate limiting) is defined in its own separate YAML file, demonstrating a less consolidated method.

```yaml
{{include:request from common/customer-request-fields.yaml}}
{{include:auth from common/customer-auth.yaml}}
{{include:rate-limit from common/customer-rate-limit.yaml}}
```

--------------------------------

### Project Configuration

Source: https://github.com/datazoode/flapi/blob/main/Readme.md

Defines the overall project settings, including database connections and environment variable whitelisting.

```APIDOC
## Project Configuration (config.yaml)

### Description
This section outlines the main configuration for a flAPI project, including project name, description, template paths, database configurations (like DuckDB and external connections), and optional features like heartbeat and HTTPS enforcement.

### Method
N/A (Configuration file)

### Endpoint
N/A

### Parameters
#### Project Settings
- **project_name** (string) - Required - The name of the flAPI project.
- **project_description** (string) - Optional - A description of the flAPI project.

#### Template Configuration
- **template.path** (string) - Required - The directory where SQL templates and API endpoint configurations are stored.
- **template.environment-whitelist** (array of strings) - Optional - A list of regular expressions for whitelisting environment variables available in templates.

#### DuckDB Configuration
- **duckdb.db_path** (string) - Optional - Path to the DuckDB database file. If omitted, an in-memory database is used.
- **duckdb.access_mode** (string) - Optional - Access mode for DuckDB (e.g., `READ_WRITE`).
- **duckdb.threads** (integer) - Optional - Number of threads for DuckDB.
- **duckdb.max_memory** (string) - Optional - Maximum memory allocation for DuckDB (e.g., `8GB`).
- **duckdb.default_order** (string) - Optional - Default ordering for queries (e.g., `DESC`).

#### Database Connections
- **connections** (map) - Required - A map of named database connection configurations.
  - **connection_name** (map) - Configuration for a specific connection.
    - **init** (string) - Optional - SQL commands to initialize the connection (e.g., loading extensions).
    - **properties** (map) - Required - Connection-specific properties (e.g., `path`, `project_id`).

#### Heartbeat Configuration
- **heartbeat.enabled** (boolean) - Optional - Enable the heartbeat worker.
- **heartbeat.worker-interval** (integer) - Optional - Interval in seconds for the heartbeat worker.

#### HTTPS Enforcement
- **enforce-https.enabled** (boolean) - Optional - Whether to force HTTPS.
- **enforce-https.ssl-cert-file** (string) - Optional - Path to the SSL certificate file.
- **enforce-https.ssl-key-file** (string) - Optional - Path to the SSL key file.

### Request Example
```yaml
project_name: example-flapi-project
project_description: An example flAPI project demonstrating various configuration options
template:
  path: './sqls'
  environment-whitelist:
    - '^FLAPI_.*'
duckdb:
  db_path: ./flapi_cache.db
  access_mode: READ_WRITE
  threads: 8
  max_memory: 8GB
  default_order: DESC
connections:
   bigquery-lakehouse:
      init: |
         INSTALL 'bigquery' FROM 'http://storage.googleapis.com/hafenkran';
         LOAD 'bigquery';
      properties:
         project_id: 'my-project-id'

   customers-parquet:
      properties:
         path: './data/customers.parquet'

heartbeat:
  enabled: true
  worker-interval: 10

enforce-https:
  enabled: false
```

### Response
N/A (Configuration file)
```

--------------------------------

### Flapi Modular YAML Configuration (Includes)

Source: https://context7.com/datazoode/flapi/llms.txt

Demonstrates how to use YAML includes for modularity and environment variable substitution in flAPI configuration files. This reduces duplication and allows for environment-specific settings.

```yaml
# File: sqls/customer-common.yaml
request:
  - field-name: id
    field-in: query
    validators:
      - type: int
        min: 1
        max: 1000000

auth:
  enabled: true
  type: basic
  users:
    - username: '{{env.API_USER}}'
      password: '{{env.API_PASSWORD}}'
      roles: [admin]

rate-limit:
  enabled: true
  max: 100
  interval: 60

connection:
  - customers-parquet

template-source: customers.sql

```

```yaml
# File: sqls/customers-rest.yaml
url-path: /customers/

# Include shared sections to eliminate duplication
{{include:request from customer-common.yaml}}
{{include:auth from customer-common.yaml}}
{{include:rate-limit from customer-common.yaml}}
{{include:connection from customer-common.yaml}}
{{include:template-source from customer-common.yaml}}

# REST-specific config
with-pagination: true
cache:
  enabled: true
  table: customers_rest_cache

```

```yaml
# File: sqls/customers-mcp-tool.yaml
mcp-tool:
  name: customer_lookup
  description: AI-powered customer lookup

# Reuse same shared configuration
{{include:request from customer-common.yaml}}
{{include:auth from customer-common.yaml}}
{{include:connection from customer-common.yaml}}
{{include:template-source from customer-common.yaml}}

# MCP-specific config
rate-limit:
  max: 50
  interval: 60

```

--------------------------------

### FLAPI Project Settings Reference

Source: https://github.com/datazoode/flapi/blob/main/docs/config.md

Defines core project settings for FLAPI, including the project name, description, and server name. These are fundamental for project identification and configuration.

```yaml
project_name: string              # Required. Project identifier
project_description: string       # Optional. Human-readable description  
server_name: string              # Optional. Server identifier (default: "flapi-server")
```

--------------------------------

### Access MCP Resources with cURL

Source: https://github.com/datazoode/flapi/blob/main/examples/sqls/customers/README.md

This snippet illustrates how to retrieve resource definitions, such as schemas, via the MCP protocol using cURL. The example specifically shows fetching the 'customer_schema'. The MCP service should be accessible at http://localhost:8081.

```bash
# Get customer schema
curl -X POST http://localhost:8081/mcp/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 3, "method": "resources/read", "params": { "uri": "flapi://customer_schema" } }'
```