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

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.