AI assistant custom tools test server

A small HTTP server for trying out custom tools without wiring up a real backend. It holds two fake accounts and looks them up by the contact's external user id, which libredesk sends in the X-Libredesk-Contact-External-Id header. Add your own test users by editing the users map in main.go.

Custom tools are only called by AI assistants. Copilot gets the built-in tools and never touches these.

Run

go run ./scripts/tools-server

It listens on :7070, or pass -addr to change that. Every request logs the contact headers and the raw args JSON the model sent, which is usually enough to work out why a tool call did not do what you expected.

Headers libredesk sends

Libredesk injects the contact and conversation context on every custom tool call. This happens server-side, so the model cannot see or change any of it:

Header	Value
`X-Libredesk-Contact-Id`	internal contact id
`X-Libredesk-Contact-External-Id`	external user id (from the livechat JWT), if any
`X-Libredesk-Contact-Type`	`contact` or `visitor`
`X-Libredesk-Contact-Email`	contact email, if known
`X-Libredesk-Contact-Verified`	`true` only after OTP/JWT identity verification
`X-Libredesk-Conversation-UUID`	conversation uuid
`X-Libredesk-Inbox-Id`	inbox id

A visitor can type any email address into a chat, so only trust X-Libredesk-Contact-Email for account data when X-Libredesk-Contact-Verified is true. This server returns a 403 otherwise.

Work out who the customer is from these headers and nothing else. The request body holds the model's arguments, written from whatever the customer typed, so it must never decide which account you return.

Endpoints

Endpoint	Returns
`/account`	name, email, plan, KYC status
`/orders`	recent orders with status
`/balance`	account balance

Tool setup (Admin -> AI -> Tools)

Create one tool per endpoint:

Method: POST
Auth header: X-Api-Key
Auth value: test-secret-token
Parameters: leave empty

For example, name get_account, URL http://localhost:7070/account, description "Get the customer's account details: name, email, plan, and KYC status."

Grant the tools to an assistant under Admin -> AI -> Assistants, then assign a conversation to that assistant. Nothing gets called until you do both.

Test contacts

Set the contact's external user id and email to one of:

USR1001 / alice@example.com - pro plan, KYC verified, has orders
USR1002 / bob@example.com - free plan, KYC pending, no orders

Error paths: bad API key -> 401, unverified contact -> 403, missing external id -> 400, unknown id -> 404, email mismatch -> 403.