brimley 0.8.1

A lightweight, file-based function execution engine.

Brimley

Early-stage MCP tooling runtime focused on faster iteration loops.

Status: Brimley is not yet ready for production use. It is aimed at improving the MCP development workflow and is still under active development.

Brimley is an authoring and execution engine for function-based AI tooling. It is focused on reducing the change/test loop during MCP tool development: change code -> reload -> re-test.

Design goals

• Faster iteration loop: author tools in .py, .sql, .md, and .yaml files and execute them immediately, without a full redeploy cycle.
• Safer change workflow: discovery is AST-first for Python (no import-time execution during scan), with diagnostics instead of immediate process termination.
• Live runtime ergonomics: use a thin REPL client attached to a daemon-owned runtime, with optional watch-mode reload.
• MCP integration path: expose selected functions as MCP tools via FastMCP when needed.
• Declarative HTTP and CLI integration (0.7+): wrap external APIs and shell commands as first-class Brimley functions using YAML — no boilerplate code required.
• Managed dependency injection (0.8+): @provider, Depends(), @on_startup/@on_shutdown hooks, and BrimleyContainer with singleton and request scopes — shared resources with proper lifecycle semantics.
• Operations clarity: built-in reload diagnostics, runtime error surfacing, and explicit daemon lifecycle controls.

Architectural approach

Brimley separates tool authoring/execution semantics from MCP transport hosting:

• Brimley handles discovery, schemas, argument resolution, execution, reload policy, and diagnostics.
• FastMCP (optional) handles MCP server transport.

Keeping function logic separate from transport makes it reusable across local REPL workflows, dedicated MCP serving, and host-embedded deployments.

Quick Start

1) Install

poetry install

Optional MCP support:

poetry install -E fastmcp

2) Add brimley.yaml

brimley:
  app_name: "Brimley App"

config:
  support_email: "[e-mail]"

state:
  request_count: 0

databases:
  default:
    connector: sqlite
    url: "sqlite:///./data.db"

auto_reload:
  enabled: true

mcp:
  embedded: true
  host: 127.0.0.1
  port: 8000

3) Add a Python function (calc.py)

from brimley import function

@function(mcpType="tool")
def calculate_tax(amount: float, rate: float = 8.25) -> float:
    return round(amount * (rate / 100.0), 2)

4) Run REPL

PYTHONPATH=src poetry run brimley repl --root .

5) Invoke once from CLI

PYTHONPATH=src poetry run brimley invoke calculate_tax --root . --input "{amount: 100, rate: 8.25}"

Core CLI Commands

• brimley repl --root . [--mcp|--no-mcp] [--watch|--no-watch]
• brimley repl --root . --shutdown-daemon
• brimley mcp-serve --root . [--watch|--no-watch] [--host HOST] [--port PORT]
• brimley invoke <function_name> --root . --input "{...}"
• brimley build --root . [--output PATH]
• brimley validate --root . [--format text|json] [--fail-on warning|error] [--output PATH]
• brimley schema-convert --in schema.yaml --out fieldspec.yaml [--allow-lossy]

MCP Integration

Mark a function as an MCP tool:

• Python: @function(mcpType="tool")
• SQL/Template/API/CLI frontmatter:

mcp:
  type: tool

API and CLI functions defined in .yaml files are first-class MCP tools. See API Functions and CLI Functions.

Then serve tools with:

PYTHONPATH=src poetry run brimley mcp-serve --root .

Runtime Model (0.8 architecture baseline)

• REPL uses a thin client attached to a daemon-owned runtime.
• Daemon owns state, watcher lifecycle, and embedded MCP hosting.
• /detach leaves daemon running; /quit (or --shutdown-daemon) terminates daemon session.
• Reload is partitioned and diagnostics-driven; schema-shape tool changes require MCP client reconnect.

Documentation Map

• High-level design
• CLI & REPL harness
• Configuration
• Discovery & loader spec
• MCP integration
• API Functions (0.7+)
• CLI Functions (0.7+)
• Secrets (0.7+)
• Security — Threat Model (0.7+)
• Dependency Injection & Managed Objects (0.8+)