Description

Toolhouse n8n Custom Nodes

Important: Before building or running, you must install dependencies with:

npm install

This package provides custom n8n nodes to integrate with Toolhouse, including:

• Toolhouse: Interact with Toolhouse agents (send/continue conversations)
• Toolhouse Webhook: Receive callbacks from Toolhouse agents

Features

• Start and continue conversations with Toolhouse agents
• Securely store and use Toolhouse API tokens via n8n Credentials
• Dynamically select agents from your Toolhouse account
• Webhook node to handle agent callback events (completed/failed)
• Alternative flows for errors and status handling

Prerequisites

• Node.js (v16+ recommended)
• n8n (locally or via Docker)
• Docker and Docker Compose (for running in Docker)

Setup & Build

1. Install dependencies (if you haven't already)

   npm install
   

2. Build the nodes and copy assets

   npm run build
   

   • This will compile TypeScript files to the dist/ directory and copy the toolhouse.svg icons.
   • Always use npm run build instead of just npx tsc to ensure assets are included!

Running with Docker Compose

A docker-compose.yml is provided. It will:

• Run n8n
• Mount your built custom nodes from ./dist into the container

First Time Setup

1. Install dependencies:

   npm install
   

2. Build your custom nodes and copy assets:

   npm run build
   

3. Start n8n with Docker Compose:

   docker compose up
   

   or (older versions)

   docker-compose up
   

4. Access n8n:
   • Open http://localhost:5678 in your browser.

Rebuilding After Changes

• If you make changes to your TypeScript node files or assets, you must rebuild before restarting Docker Compose:

  npm run build
  docker compose down
  docker compose up
  

• This ensures the latest code and assets are available in the container.

Using the Custom Nodes

1. Toolhouse Node

• Add the Toolhouse node to your workflow.
• Select or create a Toolhouse API credential (store your API token securely).
• Select an agent from the dropdown (populated from your Toolhouse account).
• Enter your message and (optionally) a run ID to continue a conversation.
• The node supports two outputs:
  • Output 1: Success
  • Output 2: Error

2. Toolhouse Webhook Node

• Add the Toolhouse Webhook node to your workflow.
• Set your Toolhouse agent's callback_url to:

  https://<your-n8n-domain>/webhook/toolhouse-callback
  

• The node supports two outputs:
  • Output 1: status is completed
  • Output 2: status is failed
• The webhook receives and outputs:
  • run_id
  • status
  • last_agent_message

Credentials Setup

1. In the n8n UI, go to Credentials.
2. Create a new credential of type Toolhouse API.
3. Enter your Toolhouse API token.
4. Select this credential in the Toolhouse node.

Debugging & Troubleshooting

• Use console.log() in your node code to print debug info (viewable in Docker logs or terminal).
• Check the n8n UI Executions tab for workflow run details and errors.
• If credentials are not found:
  • Ensure the credential name matches everywhere (toolhouseApi)
  • Rebuild (npm run build) and restart Docker/n8n
  • Check that dist/nodes/ToolhouseApi.credentials.js and dist/nodes/toolhouse.svg are present and mounted
  • Check logs for errors

Advanced: VS Code Debugging

You can run n8n in debug mode and attach a debugger:

• Add to your docker-compose.yml:

  command: node --inspect=0.0.0.0:9229 /usr/local/lib/node_modules/n8n/bin/n8n
  ports:
    - 9229:9229
  

• Attach VS Code to localhost:9229

References

• n8n Docs: Custom Nodes
• n8n Docs: Docker
• Toolhouse

License

MIT