foro (Python)

The Python SDK and CLI for foro.sh — the fastest path from "I want to build an MCP server" to a deployed https://<slug>.foro.sh URL.

Quickstart
CLI
Runtime
foro.yaml reference
Example
Develop this package

Quickstart

uvx foro init my-server && cd my-server
uvx foro dev

foro init scaffolds a working FastMCP server plus a foro.yaml; foro dev runs it exactly as foro.sh will and confirms it would pass the platform's health check. Once it looks good:

git init && git add -A && git commit -m "init" && gh repo create --push

Then, on the foro.sh dashboard: sign in with GitHub, pick the repo, add any secrets your tools need, and deploy.

CLI

Install once with uv tool install foro, or run ad-hoc with uvx foro ... — no need to add it to your project's own dependencies.

Command	What it does
`foro init [name]`	Scaffold a new project, or add `foro.yaml` to an existing one (run with no argument). `--yes` takes every default without prompting, for CI and coding agents
`foro check [path]`	Validate a repo against foro.sh's deploy contract before you push
`foro dev [path]`	Run the server locally exactly as foro.sh will, and confirm it would pass the health check

foro check mirrors the platform's own validation rule for rule, so a repo it passes will deploy and one it flags will not — the same reason code, surfaced locally instead of as a 60-second health-check timeout.

Runtime

One import, used from your server's entrypoint:

from fastmcp import FastMCP
import foro

mcp = FastMCP("my-server")

@mcp.tool
def add(a: int, b: int) -> int:
    return a + b

if __name__ == "__main__":
    foro.run(mcp)  # streamable HTTP, host 0.0.0.0, port $MCP_PORT - identical locally and deployed

Function	What it does
`foro.run(server, *, port=None)`	The one correct way to start a server for foro.sh. Accepts any FastMCP-shaped server (standalone `fastmcp.FastMCP`, `mcp.server.fastmcp.FastMCP`, or a low-level `Server`) — it's duck-typed, not tied to a specific class.
`foro.secret(name)`	Read a required secret from the environment, raising a dashboard-actionable error if it's missing. Set secrets in your project's Secrets tab on the dashboard; they arrive as env vars at deploy time.

Bare foro (what a deployed container installs — no [cli] extra) stays dependency-free, so a deployed container never pulls in CLI tooling it doesn't use.

`foro.yaml` reference

Every deployable repo carries one, at its root:

name: my-server          # required, ^[a-z0-9-]{3,48}$ - display name only, not the URL slug
entrypoint: server.py    # required, relative path, run as `uv run <entrypoint>`
build_path: .            # optional, default "." - dir holding pyproject.toml + uv.lock
python_version: "3.12"   # optional, one of 3.11 / 3.12 / 3.13
port: 8000               # optional, default 8000 - the port your server must listen on

At runtime the container gets MCP_PORT (matching port above) and every project secret as its own env var. Public traffic arrives at https://<slug>.foro.sh, so your server must listen on 0.0.0.0:$MCP_PORT — which is exactly what foro.run() does for you.

Example

foro-sh/todo-mcp is a small stateful todo-list server built the way described above — every new foro.sh workspace gets a deployed copy of it to poke at before deploying anything of your own.

Develop this package

uv sync
uv run pytest

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

foro-0.4.0.tar.gz (318.9 kB view details)

Uploaded Jul 29, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

foro-0.4.0-py3-none-any.whl (19.1 kB view details)

Uploaded Jul 29, 2026 Python 3

File details

Details for the file foro-0.4.0.tar.gz.

File metadata

Download URL: foro-0.4.0.tar.gz
Upload date: Jul 29, 2026
Size: 318.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for foro-0.4.0.tar.gz
Algorithm	Hash digest
SHA256	`32cd5c003e3a26b7303ddb53e14e2d5cac1c8405f7c746a229e65198e6fc6fe7`
MD5	`6b9dfbfa3622ddebd8a90dac302f8845`
BLAKE2b-256	`e95a7b2e438ff664488cb3878f3be9e528e3d35440431984c3aaaafa6a093f54`

See more details on using hashes here.

Provenance

The following attestation bundles were made for foro-0.4.0.tar.gz:

Publisher: semantic-release.yml on foro-sh/foro

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: foro-0.4.0.tar.gz
- Subject digest: 32cd5c003e3a26b7303ddb53e14e2d5cac1c8405f7c746a229e65198e6fc6fe7
- Sigstore transparency entry: 2282305448
- Sigstore integration time: Jul 29, 2026
Source repository:
- Permalink: foro-sh/foro@a277ac8bf9b842e02d0b7f762a879912eda879f6
- Branch / Tag: refs/heads/main
- Owner: https://github.com/foro-sh
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: semantic-release.yml@a277ac8bf9b842e02d0b7f762a879912eda879f6
- Trigger Event: push