# 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

```bash
poetry install
```

Optional MCP support:

```bash
poetry install -E fastmcp
```

### 2) Add `brimley.yaml`

```yaml
brimley:
  app_name: "Brimley App"

config:
  support_email: "support@example.com"

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`)

```python
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

```bash
PYTHONPATH=src poetry run brimley repl --root .
```

### 5) Invoke once from CLI

```bash
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: 

```yaml
mcp:
  type: tool
```

API and CLI functions defined in `.yaml` files are first-class MCP tools. See [API Functions](docs/brimley-api-functions.md) and [CLI Functions](docs/brimley-cli-functions.md).

Then serve tools with:

```bash
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](docs/brimley-high-level-design.md)
- [CLI & REPL harness](docs/brimley-cli-and-repl-harness.md)
- [Configuration](docs/brimley-configuration.md)
- [Discovery & loader spec](docs/brimley-discovery-and-loader-specification.md)
- [MCP integration](docs/brimley-model-context-protocol-integration.md)
- [API Functions](docs/brimley-api-functions.md) *(0.7+)*
- [CLI Functions](docs/brimley-cli-functions.md) *(0.7+)*
- [Secrets](docs/brimley-secrets.md) *(0.7+)*
- [Security — Threat Model](docs/security/brimley-0.7-threat-model.md) *(0.7+)*
- [Dependency Injection & Managed Objects](docs/roadmap/brimley-0.8-dependency-injection-and-managed-objects.md) *(0.8+)*
