Tools and Integrations

Tools and Integrations

FML provides native support for connecting LLMs to external systems via the Model Context Protocol (MCP), structured Collections (databases and knowledge bases), and a built-in web Search tool.

---

Tool Declaration Model: require vs. use

FML uses a two-tier tool declaration model to separate global environment dependency registration from session-level permission scoping:

graph TD
    subgraph Global["Global Declaration (require)"]
        R1["require mcp github"]
        R2["require collection vector_db"]
    end

    subgraph S1["Session 1: Read-Only"]
        R1 -.-> U1["use mcp github { allowlist = ['get_issue', 'list_commits'] }"]
    end

    subgraph S2["Session 2: Mutation"]
        R1 -.-> U2["use mcp github { allowlist = ['create_issue_comment'] }"]
    end

Loading

Construct	Location	Purpose	Allowlist Support
require	File-level (Root)	Registers external tool dependencies for the plan runner.	No. Strictly single-line statements.
use	Inside session	Activates tools for that specific session; injects tool schemas into LLM context.	Yes. Supports allowlist = [...].

---

1. Model Context Protocol (mcp)

The Model Context Protocol allows FML plans to interact with any MCP-compliant server.

Global Declaration

require mcp github
require mcp slack_notifier
require mcp file_system

Important

Global require statements must be strictly single-line declarations without block bodies:

# CORRECT:
require mcp github

# INCORRECT:
require mcp github { allowlist = ["list_repos"] } # COMPILE ERROR!

Session Activation & Allowlists

Inside a session, activate the required MCP tool and optionally filter which functions the LLM is permitted to see:

session("triage_issue") {
    # Expose only specific functions to the model
    use mcp github {
        allowlist = ["get_issue", "get_issue_comments", "list_labels"]
    }

    + Retrieve issue #{{ .params.issue_number }} and inspect comments.
    - Categorize the issue and suggest appropriate labels.

    schema {
        issue_id: int
        category: bug|feature|documentation
        suggested_labels: string[]
    }
}

Tip

Principle of Least Privilege: Always use allowlist to restrict tool access to only the functions needed by the current session. This saves prompt tokens and prevents the model from accidentally executing destructive operations (like deleting repositories or modifying data).

Note that allowlist is the only configuration parameter supported in the use block body.

---

2. Collections (collection)

Collections represent data repositories, relational databases, or vector search indices.

Syntax

# Global declaration
require collection knowledge_base
require collection customer_db

# Session activation
session("query_customers") {
    use collection customer_db

    + Query customer_db for accounts active in Q3.
    - Format customer list.

    schema {
        customers: string[]
    }
}

---

3. The Built-in Search Tool (use search)

FML includes a first-class web search capability.

Syntax & Critical Rule

session("market_overview") {
    # Activate built-in search (no name parameter)
    use search

    + Search the web for recent advancements in solid-state battery technology.
    - Extract top breakthroughs.

    schema {
        breakthroughs: string[]
    }
}

Caution

Never Require Search: The built-in search tool does not have an external dependency name. Writing require mcp search or require search at the file level is a compilation error. Simply declare use search inside the sessions that need web search capabilities.

---

4. Tool Output Transformers (transformer)

When an external tool returns massive JSON objects (e.g. hundreds of fields or thousands of items), passing the raw output directly to an LLM wastes context tokens and degrades attention.

A transformer intercepts the output of a specific tool function and filters or reshapes it before the LLM receives the payload.

JMESPath Transformer

Ideal for filtering properties or projecting array elements using standard JMESPath queries:

transformer("trim_github_repos") {
    onFunctionOutput = "list_org_repositories"
    jmesPath = "[].{name: name, stars: stargazers_count, url: html_url}"
}

JavaScript Transformer

Ideal for complex data transformations, deduplication, or calculations:

transformer("dedup_and_clean_articles") {
    onFunctionOutput = "search_news"
    code(
        (
            const seen = new Set();
            const cleaned = [];
            for (const item of args) {
                if (!seen.has(item.url)) {
                    seen.add(item.url);
                    cleaned.push({ title: item.title, link: item.url });
                }
            }
            cleaned; # Final expression is the transformed result
        )
    )
}

Transformer Constraints

1. Exclusivity: A transformer must define either jmesPath or code, but never both.
2. Matching: onFunctionOutput must match the exact function identifier exposed by the tool.
3. Automatic Application: Whenever any session (or PreCall) executes that function, the output is automatically transformed.

---

Integration Architecture Diagram

┌───────────────────────────────────────────────────────────┐
│ MCP Server / Tool API                                     │
│  └─ Returns: Large raw payload (500KB JSON)               │
└─────────────────────────────┬─────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│ FML Transformer (jmesPath / code)                         │
│  └─ Filters & projects: Sanitized payload (5KB JSON)      │
└─────────────────────────────┬─────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│ Active Session History (LLM Prompt Context)               │
│  └─ Pre-prompt (+) LLM receives only relevant fields      │
└───────────────────────────────────────────────────────────┘