README
¶
firelynx - Scriptable App Gateway
firelynx runs scriptable applications behind configurable listeners and routes.
It includes a gateway-style Model Context Protocol (MCP)
server app: ordinary firelynx apps are defined once, then an MCP server app
references them by app_id and exposes supported app providers as MCP tools.
Features
- MCP Gateway Support: Expose existing firelynx apps through the standardized Model Context Protocol
- Scriptable Tools: Create custom tool implementations using multiple scripting languages
- Hot-Reloadable Configuration: Update server configuration via gRPC or file reload without stopping the server
- Modular Architecture: Separation between listeners, endpoints, and applications
- Multiple Script Engines: Powered by go-polyscript
- Lifecycle Management: Handled by go-supervisor
Quick Start
Installation
# Install from source
go install github.com/atlanticdynamic/firelynx/cmd/firelynx@latest
# Or build from source
git clone https://github.com/atlanticdynamic/firelynx.git
cd firelynx
make install
Running the Server
# Start with a configuration file (gRPC config API services disabled)
firelynx server --config /path/to/config.toml
# Start with an empty configuration (enable gRPC services on port 8765)
firelynx server --listen :8765
# Start with an initial config AND enable the gRPC listener for updates
firelynx server --config /path/to/config.toml --listen :8765
# Use the client CLI to interact with the server
firelynx client --server localhost:8765
Configuration
firelynx uses TOML configuration files with the following structure:
# firelynx Server Configuration
# TBD...
Architecture
firelynx follows a three-layer architecture:
- Listeners: Protocol-specific entry points such as HTTP and gRPC
- Endpoints: Connection mapping between listeners and applications
- Applications: Functional components including script apps, echo apps, and MCP gateway apps
Development
Requires Go 1.26.2 or later to compile.
# Clone the repository
git clone https://github.com/atlanticdynamic/firelynx.git
cd firelynx
# Generate protobuf code
make protogen
# Run tests
make test
make test-all
# Compile the binary
make build
# Run the compiled server/client binary
./bin/firelynx --help
Documentation
Documentation is located near the code in README files throughout the codebase:
- Configuration Domain Model: Configuration validation and domain model
- Configuration Transactions: Saga pattern for configuration updates
- Transaction Manager: Configuration transaction coordination
- CLI Usage: Command-line interface and commands
License
GPL v3 - See LICENSE for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
firelynx
command
|
|
|
Package examples provides access to example configurations for testing.
|
Package examples provides access to example configurations for testing. |
|
gen
|
|
|
internal
|
|
|
config
Package config provides configuration management for the firelynx server.
|
Package config provides configuration management for the firelynx server. |
|
config/apps
Package apps provides types and functionality for application configuration in the firelynx server.
|
Package apps provides types and functionality for application configuration in the firelynx server. |
|
config/apps/calculation
Package calculation provides app-specific configuration for calculation apps.
|
Package calculation provides app-specific configuration for calculation apps. |
|
config/apps/composite
Package composite provides types and utilities for composite script applications in firelynx.
|
Package composite provides types and utilities for composite script applications in firelynx. |
|
config/apps/echo
Package echo provides app-specific configurations for the firelynx server.
|
Package echo provides app-specific configurations for the firelynx server. |
|
config/apps/fileread
Package fileread provides app-specific configuration for file read apps.
|
Package fileread provides app-specific configuration for file read apps. |
|
config/apps/mcpserver
Package mcpserver provides error definitions for MCP server configuration validation.
|
Package mcpserver provides error definitions for MCP server configuration validation. |
|
config/apps/scripts
Package scripts provides types and utilities for script-based applications in firelynx.
|
Package scripts provides types and utilities for script-based applications in firelynx. |
|
config/apps/scripts/evaluators
Package evaluators provides types and utilities for various script evaluators used in firelynx.
|
Package evaluators provides types and utilities for various script evaluators used in firelynx. |
|
config/endpoints
Package endpoints provides configuration types and utilities for routing in the firelynx server.
|
Package endpoints provides configuration types and utilities for routing in the firelynx server. |
|
config/endpoints/middleware
Package middleware provides types and functionality for middleware configuration in the firelynx server.
|
Package middleware provides types and functionality for middleware configuration in the firelynx server. |
|
config/endpoints/routes
Package routes provides configuration types and utilities for request routing in the firelynx server.
|
Package routes provides configuration types and utilities for request routing in the firelynx server. |
|
config/errz
Package errz provides shared error definitions for the config package and its subpackages.
|
Package errz provides shared error definitions for the config package and its subpackages. |
|
config/listeners
Package listeners provides configuration types and utilities for network listeners in the firelynx server.
|
Package listeners provides configuration types and utilities for network listeners in the firelynx server. |
|
config/loader/toml
Package toml provides TOML configuration loading with protobuf post-processing.
|
Package toml provides TOML configuration loading with protobuf post-processing. |
|
config/staticdata
Package staticdata provides types and utilities for handling static data that can be passed to apps and routes in firelynx.
|
Package staticdata provides types and utilities for handling static data that can be passed to apps and routes in firelynx. |
|
config/transaction
TODO: change the param order, standardize on a metadata struct
|
TODO: change the param order, standardize on a metadata struct |
|
config/transaction/finitestate
Configuration saga state machine implementation.
|
Configuration saga state machine implementation. |
|
config/validation
Package validation provides validation utilities for domain config types.
|
Package validation provides validation utilities for domain config types. |
|
server/apps/mcpserver
Package mcpserver provides MCP server applications that expose firelynx app providers as MCP tools using the mcp-io abstraction layer.
|
Package mcpserver provides MCP server applications that expose firelynx app providers as MCP tools using the mcp-io abstraction layer. |
|
server/runnables/cfgservice
Runner manages configuration state and serves a gRPC API for clients to retrieve and update the configuration.
|
Runner manages configuration state and serves a gRPC API for clients to retrieve and update the configuration. |
|
server/runnables/listeners/http
Package http provides the HTTP listener implementation with SagaParticipant support.
|
Package http provides the HTTP listener implementation with SagaParticipant support. |
|
server/runnables/listeners/http/cfg
Package cfg provides configuration management for HTTP listeners.
|
Package cfg provides configuration management for HTTP listeners. |
|
server/runnables/listeners/http/middleware/headers
Package headers provides HTTP header manipulation middleware for both requests and responses.
|
Package headers provides HTTP header manipulation middleware for both requests and responses. |
|
server/runnables/txmgr
Package txmgr implements the transaction manager for configuration updates and adapters between domain config and runtime components.
|
Package txmgr implements the transaction manager for configuration updates and adapters between domain config and runtime components. |
|
server/runnables/txmgr/txstorage
Package txstorage provides an implementation of the TransactionStorage interface for storing and retrieving configuration transactions.
|
Package txstorage provides an implementation of the TransactionStorage interface for storing and retrieving configuration transactions. |
Click to show internal directories.
Click to hide internal directories.