Homello MCP

Minimal Model Context Protocol (MCP) stdio server for the Homello platform.

• Package: @homello/mcp

• Binary: mcp

• License: AGPL-3.0-only

• Runtime: Node.js ≥ 20

What it does

Exposes a single MCP tool over stdio:

• homello.get_info – returns Homello product/docs metadata plus effective runtime config (API base, market, timeout, debug). Response is emitted as both text and structuredContent.

Quick start

# Run once (no install)
npx -y @homello/mcp

# Or add to a project
npm i -D @homello/mcp
npx mcp

The default command is start. It connects over stdio and waits for an MCP client.

With Goose (auto-install an extension)

Writes/updates ~/.config/goose/config.yaml (override with GOOSE_DIR or GOOSE_CONFIG_PATH).

# Install/update the extension entry
npx -y @homello/mcp install \
  --enabled=true \
  --timeout=300 \
  --available-tools homello.get_info \
  --env HOMELLO_API_BASE=https://api.homello.ai \
  --env-key HOMELLO_API_KEY

# Remove the extension entry
npx -y @homello/mcp uninstall

Common options:

• --id (default: homello) – extension id

• --name (default: Homello MCP)

• --description (default: Homello platform integration)

• --cmd (default: npx) and repeated --arg (default: -y @homello/mcp@latest)

• --enabled (default: false)

• --timeout seconds (default: 300)

• --bundled true|false|null (default: null)

• repeated --available-tools (e.g. homello.get_info)

• repeated --env KEY=VALUE (persist literal values)

• repeated --env-key KEY (reference variables to be supplied by the host)

Configuration

Config is resolved from process env, then Goose extension envs, with these keys:

• HOMELLO_API_BASE (default: https://api.homello.ai)

• HOMELLO_API_KEY (default: empty)

• HOMELLO_DEFAULT_MARKET (default: US)

• HOMELLO_TIMEOUT_SECS (default: 30)

• HOMELLO_DEBUG (1|true enables debug; default: 0)

Local dev toggle:

• HOMELLO_MCP_LOCAL_DEV=1
  Uses a dev extension id (homellomcp) and local Node/entrypoint paths from DEFAULTS.localCmd/localArgs.

CLI

# Start the stdio server (same as no subcommand)
mcp start

# Create/update Goose extension entry
mcp install [options]

# Remove Goose extension entry
mcp uninstall [--id homello]

Tool contract

homello.get_info returns:

{
  "platform": "Homello",
  "api_base": "https://api.homello.ai",
  "market": "US",
  "timeout_secs": 300,
  "debug": false,
  "docs": { "...": "..." }
}

docs is sourced from a packaged JSON bundle.

Development

# Dev (tsx)
npm run dev

# Build
npm run build

# Watch typescript
npm run watch

# Release patch version
npm run release

Node/stdio details

• Transport: @modelcontextprotocol/sdk stdio (McpServer + StdioServerTransport)

• Server identity: name: homello-mcp, version: 0.2.0, description: MCP server connecting to the Homello platform

• Graceful shutdown on SIGINT/SIGTERM.

Repository

https://github.com/homello/mcp