lightbulb-mcp 0.4.0

MCP server for the Lightbulb Partners Agents platform — Claude Code, Codex, and Cursor integration

Lightbulb MCP

MCP server and helper CLI for the Lightbulb Partners Agents platform. Connect your Claude Code, Codex, or Cursor account to your Lightbulb workspace — domain agents, code workspaces, connectors, document/page builders, voice, AutoCompany (AOC), and more.

For the MCP host integration details (authentication, tool surface, troubleshooting), see MCP.md.

The Python SDK (LightbulbClient, AsyncLightbulbClient, etc.) ships in this package as preview / unstable internals. The supported product right now is the MCP server and helper CLI — direct Python API consumers should expect changes between minor versions.

Install

pip install lightbulb-mcp

Console scripts:

• lightbulb-mcp — runs the MCP server over stdio for Claude Code / Codex / Cursor (see MCP.md).
• lightbulb — helper CLI for status, login, and one-shot platform commands.

Quick start — wire up Claude Code

pip install lightbulb-mcp
lightbulb setup

lightbulb setup is an interactive wizard: device-flow login (browser handles MFA), probe /api/users/me, then merge a lightbulb MCP server entry into Claude Code (.mcp.json / .claude.json), Codex (~/.codex/config.toml), or Cursor (~/.cursor/mcp.json). Existing servers are preserved; backups use .bak.

Flags: --target codex, --yes / --no-write, --skip-login, --url.

Manual .mcp.json

If you'd rather wire Claude Code by hand:

{
  "mcpServers": {
    "lightbulb": {
      "command": "lightbulb-mcp",
      "env": {
        "LIGHTBULB_URL": "https://agents.lightbulbpartners.com"
      }
    }
  }
}

The MCP server resolves credentials from a cached device-flow token (~/.lightbulb/tokens/) by default, or from env (LIGHTBULB_JWT + LIGHTBULB_TENANT_ID, etc.). Full auth precedence in MCP.md.

CLI

Running lightbulb with no arguments prints status: platform URL, cached token hint, detected Claude/Codex/Cursor configs, and next steps.

lightbulb                    # status (default)
lightbulb setup              # guided auth + MCP config merge
lightbulb whoami
lightbulb dispatch finance --action chat --message "Quick AR aging summary"
lightbulb search-documents "quarterly revenue" --top-k 5
lightbulb approvals list

Environment variables (CLI & MCP)

Variable	Purpose
LIGHTBULB_URL	Platform base URL (default https://agents.lightbulbpartners.com)
LIGHTBULB_JWT	Bearer JWT
LIGHTBULB_TENANT_ID	Required with JWT
LIGHTBULB_COMPANY_ID	Optional company scope
LIGHTBULB_EMAIL / LIGHTBULB_PASSWORD	Legacy password login
LIGHTBULB_API_KEY / LIGHTBULB_USER_ID	Localhost integration bootstrap

Python API (preview)

The package also ships a Python client used internally by the MCP server. Not yet a stable product surface — expect breaking changes between minor versions. Pin exactly if you depend on it.

from lightbulb import LightbulbClient, device_login

BASE = "https://agents.lightbulbpartners.com"

# Recommended for humans: OAuth2-style device flow (browser handles MFA)
auth, _expires = device_login(BASE, client_id="my-app")

client = LightbulbClient(BASE, auth=auth)
print(client.whoami())

result = client.dispatch("finance", action="chat", message="Summarize cash this week")
print(result.reply)

Email / password and 2FA

from lightbulb import login, complete_2fa_login, TwoFactorRequired

try:
    auth = login(BASE, "[e-mail]", "secret")
except TwoFactorRequired as exc:
    code = input("Authenticator code: ").strip()
    auth = complete_2fa_login(exc.base_url, exc.email, code)

client = LightbulbClient(BASE, auth=auth)

For MFA accounts, device login is usually simpler.

Async

from lightbulb import AsyncLightbulbClient, JwtAuth

async def main():
    auth = JwtAuth(token="...", tenant_id="...", company_id=None)
    async with AsyncLightbulbClient(BASE, auth=auth) as client:
        me = await client.whoami()

Coverage in AsyncLightbulbClient is curated for hot paths; use LightbulbClient for full surface area.

Refreshing expired JWTs

Pass auth_refresh and call refresh_auth() after an AuthenticationError, then retry:

from lightbulb import LightbulbClient, AuthenticationError
from lightbulb.auth import device_login

def refresh():
    auth, _ = device_login(BASE, client_id="my-worker")
    return auth

client = LightbulbClient(BASE, auth=initial_auth, auth_refresh=refresh)

try:
    client.dispatch("crm", action="chat", message="hello")
except AuthenticationError:
    if client.refresh_auth():
        client.dispatch("crm", action="chat", message="hello")

Same pattern on AsyncLightbulbClient with await client.refresh_auth().

Exceptions (lightbulb.errors)

HTTP failures from LightbulbClient and AsyncLightbulbClient raise LightbulbError subclasses (not raw httpx.HTTPStatusError):

Type	Typical status
AuthenticationError	401
PermissionDenied	403
NotFoundError	404
ValidationError	400 / 422 (also subclasses ValueError)
RateLimitedError	429 (retry_after when present)
ServerError	5xx

Helpers: from_response, wrap_http_error, raise_if_error (used internally; safe to call on any httpx.Response).

Messages avoid leaking raw response bodies; structured JSON fields like message / error are capped.

Deep wrappers (XeroAgentClient, connector clients) use the same HTTP stack and raise the same types.

Typed integrations

• Stripe: StripeOrchestratorClient, StripeWorkflow
• Xero: XeroAgentClient, XeroPlaybook
• Connectors: SlackClient, JiraClient, BambooHRClient, GreenhouseClient, MondayClient (thin invoke_tool / HR-live helpers)

Security posture

• HTTPS enforced for non-local hosts by default (enforce_https=False only for dev).
• Path segments and risky inputs validated (validators module); SSO / device-flow URLs validated before opening a browser.
• Token cache: atomic write, restrictive permissions, symlink and ownership checks.
• lightbulb setup: atomic config writes, safe TOML escaping for Codex, backups chmod-restricted.

Regression tests live in tests/test_security.py (audit IDs in docstrings).

Types (PEP 561)

The wheel ships py.typed for Pyright/mypy consumers.

Version history

0.4.0

• Renamed package to lightbulb-mcp; MCP deps (mcp, pydantic, pydantic-settings) are now hard dependencies. Python API ships as preview/unstable internals.
• Defaults updated to production: LIGHTBULB_URL defaults to https://agents.lightbulbpartners.com. CLI / MCP server / setup wizard all use the plural production hostname.
• Security hardening: redirect URL validation, token/config atomic writes, TOML injection fixes, SSE size limits, localhost detection via hostname parsing, preview proxy header merging.
• errors module and raise_if_error: platform HTTP errors map to LightbulbError subclasses from the sync/async clients and Xero wrapper.
• refresh_auth / optional auth_refresh callback; setup wizard retries once on stale cached token.
• py.typed + README/MCP docs consolidation.

0.3.0

• 2FA (TwoFactorRequired, complete_2fa_login), SSO URL helper, SSE streaming for code/page/document builders, code workspace tools & preview, marketing connector setup methods, typed connector clients, AsyncLightbulbClient, lightbulb CLI, guided lightbulb setup / lightbulb status, lightbulb-mcp entry point.

0.2.0

• Large MCP tool expansion, domain registry alignment, XeroAgentClient, expanded platform surface in MCP.