integration-builder

name

integration-builder

description

Guided integration builder powered by haiflow. Helps users discover, design, and build integrations between services, APIs, and tools. Uses context7 MCP to research library/API docs in real-time. Supports two execution paths: (1) n8n workflows that call haiflow endpoints to orchestrate Claude Code, auto-deployed via n8n MCP if API keys are available; (2) raw Bun/TypeScript integrations that call haiflow directly. Triggers on: integrate, connect X to Y, build an integration, sync X with Y, automate X, webhook from X, n8n workflow for X, how do I connect X to Y, or any request to link two or more services together.

Integration Builder

Build integrations between services using haiflow as the AI orchestration layer. Haiflow wraps Claude Code in tmux sessions and exposes a REST API — integrations trigger prompts, queue work, and poll for responses over HTTP.

Project references (read these for API details, don't duplicate):

• README.md — Full API docs, setup, and architecture
• src/index.ts — Endpoint implementations and types
• examples/chained-calc/ — Chained calc workflow example

Workflow

1. Discover — What services to connect, what triggers the flow, what data moves
2. Research — Look up API/library capabilities via context7
3. Propose — Recommend n8n or raw integration path, present the plan
4. Build — Create the workflow or code
5. Deploy — Activate in n8n or hand off runnable code

---

Phase 1: Discover

Ask concise questions (max 3 per message) to understand:

• Source system(s) — Where does data/event originate?
• Destination system(s) — Where should data/action land?
• Trigger — Webhook, schedule, manual, or polling?
• Data flow — What moves between systems? Transforms needed?
• Path preference — n8n workflow or raw code?

n8n vs raw code decision:

Factor	n8n	Raw code
User has n8n instance or n8n MCP available	Prefer	-
Visual workflow management needed	Prefer	-
Many conditional branches	Prefer	-
High-performance / low-latency	-	Prefer
Deep custom logic / complex transforms	-	Prefer
User explicitly prefers code	-	Prefer

Default to n8n if user mentions it or mcp__n8n-mcp__* tools are available.

---

Phase 2: Research

Use context7 MCP to research each service/library involved:

1. mcp__context7__resolve-library-id — Resolve each service/library name
2. mcp__context7__query-docs — Query for:
   • Authentication methods
   • Available endpoints / webhook events
   • Rate limits or quirks
   • SDK availability

Summarise what affects integration design:

• Auth type (API key, OAuth, webhook secret)
• Available triggers/events
• Data format (JSON, XML, form-data)
• Limitations

Fallback: If context7 doesn't cover a service, use WebSearch or WebFetch.

---

Phase 3: Propose

Present the integration plan. Always show how haiflow fits in the flow.

n8n proposal format:

## Proposed Workflow

Trigger: [type]
Flow: [Event Source] → n8n → haiflow /trigger → Claude Code → /responses/:id → [Action]

Nodes:
1. [Trigger] — [description]
2. POST /trigger — send prompt to Claude via haiflow
3. GET /responses/:id/stream — SSE stream until complete (text response, 310s timeout)
4. Code node — parse `event: complete` from SSE text
5. [Action] — use Claude's response

Raw code proposal format:

## Proposed Integration

Runtime: Bun
Entry: integration.ts
Trigger: [HTTP endpoint / schedule / CLI]

Flow:
1. [Receive event / run on schedule]
2. POST /trigger with prompt
3. GET /responses/:id/stream — SSE stream until complete
4. Parse `event: complete` from SSE text
5. [Process response and take action]

Confirm before building.

---

Phase 4: Build

n8n Path

Read examples/chained-calc/ for existing haiflow + n8n templates. Use them as the base.

The core n8n + haiflow pattern (uses SSE streaming, no polling loop):

1. Trigger node — webhook, schedule, or service event
2. HTTP Request — POST /trigger with {prompt, session, id, source}
3. HTTP Request — GET /responses/:id/stream (response format: text, timeout: 310000ms)
4. Code node — parse event: complete block from SSE text to extract response JSON
5. Action node — use messages[] from the parsed response

Use n8n MCP tools to deploy:

• mcp__n8n-mcp__search_workflows — find existing
• mcp__n8n-mcp__get_workflow_details — inspect
• mcp__n8n-mcp__execute_workflow — create/execute

If n8n MCP unavailable, save workflow JSON to examples/chained-calc/ for manual import.

Raw Code Path

Follow CLAUDE.md conventions (Bun, no dotenv, TypeScript). The core pattern:

const HAIFLOW = process.env.HAIFLOW_URL || "http://localhost:3333";
const API_KEY = process.env.HAIFLOW_API_KEY;
const headers = { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` };

// 1. Trigger
const { id } = await fetch(`${HAIFLOW}/trigger`, {
  method: "POST",
  headers,
  body: JSON.stringify({ prompt, session: "default", source: "integration" }),
}).then(r => r.json());

// 2. Stream (SSE) — blocks until complete, no polling loop
const res = await fetch(`${HAIFLOW}/responses/${id}/stream?session=default&timeout=300`, { headers });
const text = await res.text();
const blocks = text.split("\n\n").reverse();
const completeBlock = blocks.find(b => b.includes("event: complete"));
const dataLine = completeBlock?.split("\n").find(l => l.startsWith("data: "));
const result = dataLine ? JSON.parse(dataLine.slice(6)) : null;

// 3. Use result.messages[]

Read src/index.ts for the full endpoint API, types, and status codes.

---

Phase 5: Deploy

n8n

• Verify workflow via mcp__n8n-mcp__get_workflow_details
• Confirm haiflow running: GET /health
• Confirm Claude session active: GET /status
• List credentials needing manual n8n UI setup

Raw Code

• Show run command: bun run <file>
• Remind to ensure haiflow + Claude session running:

  bun run src/index.ts
  curl -X POST localhost:3333/session/start -d '{"cwd":"/path/to/project"}'
  

• List env vars to set

---

Error Handling

• context7 miss → try alternate library names, then web search
• n8n MCP unavailable → generate importable workflow JSON in examples/chained-calc/
• haiflow offline → remind user to start it and the Claude session
• Auth unclear → ask the user, don't guess
• Claude busy → haiflow auto-queues; integrations should handle 202 responses