workiq-proxy

Extends Microsoft Work IQ with broad MCP client support, structured search tools, an interactive REPL, and an OpenAI-compatible HTTP API.

What it does

workiq-proxy enhances Work IQ's MCP server so it works seamlessly with Claude Code, VS Code, Codex, and other MCP clients.

In MCP mode the proxy sits between the MCP client and the Work IQ server:

MCP Client <-stdio-> workiq-proxy <-stdio-> workiq mcp

It:

1. Extends MCP capabilities — Adds support for prompts/list, resources/list, and resources/templates/list so every MCP client connects cleanly
2. Advertises full capabilities — Ensures clients see a fully capable server during initialization
3. Future-proof — Automatically steps aside when Work IQ gains these capabilities natively
4. Error enrichment — Wraps opaque errors with troubleshooting context (EULA not accepted, token protection / error 530084, Entra ID conditional access / AADSTS, interactive login required, and "Failed to create conversation")
5. Synthetic tools — Exposes 7 domain-specific tools (search_emails, search_documents, search_chats, search_channels, search_meetings, search_people, search_external) backed by ask_work_iq
6. Interactive REPL — When run from a terminal with no arguments, launches a Bubble Tea UI with slash commands (/ask, /emails, /docs, /chats, /channels, /meetings, /people, /accept-eula, /tools, /help, /quit), session history, and glamour markdown rendering
7. OpenAI-compatible HTTP API — workiq-proxy serve starts a local server with /v1/chat/completions (streaming and non-streaming) and /v1/models
8. CLI passthrough — When run from an interactive terminal with arguments, delegates to the underlying workiq CLI (EULA acceptance, auth, queries) so you only need one package
9. Traffic logging — Logs all JSON-RPC messages to ~/.work-iq-cli/mcp-traffic.log

Install

curl -fsSL https://stuffbucket.github.io/workiq-proxy/install.sh | sh

The installer detects (or installs) Node.js and sets up workiq-proxy via npm.

On Windows (PowerShell):

irm https://stuffbucket.github.io/workiq-proxy/install.ps1 | iex

Alternatively, install directly with npm:

npm install -g @stuffbucket/workiq-proxy

This also installs @microsoft/workiq as a dependency — no separate setup needed. The npm package provides both workiq-proxy and wiq as binaries.

Or download a binary from GitHub Releases and place it in your PATH.

Prerequisites

Before using the proxy, set up Work IQ from your terminal:

# First run: accepts EULA interactively, then triggers browser auth
npx -y @stuffbucket/workiq-proxy ask

The interactive session walks you through EULA acceptance and signs you in via the browser. Once complete, the MCP server reuses cached tokens silently.

You can also accept the EULA directly:

npx -y @stuffbucket/workiq-proxy accept-eula

To verify auth works non-interactively:

npx -y @stuffbucket/workiq-proxy ask -q "What's on my calendar?"

Commands

Command	Description
(no args, TTY)	Start the interactive REPL
ask -q "..."	Ask Microsoft 365 Copilot a question (passthrough to workiq)
accept-eula	Accept the Work IQ EULA via the MCP accept_eula tool
mcp	Start MCP proxy server (stdio) — also the implicit mode when no TTY
serve	Start OpenAI-compatible HTTP API on localhost
json	Interactive JSON-RPC testing mode
version	Show workiq CLI version (passthrough)
help	Show usage summary

Configure

Claude Code

Project-level (adds to .mcp.json in current directory):

claude mcp add --transport stdio workiq --scope project -- npx -y @stuffbucket/workiq-proxy

User-level (available in all projects):

claude mcp add --transport stdio workiq --scope user -- npx -y @stuffbucket/workiq-proxy

Or add to .mcp.json manually:

{
  "mcpServers": {
    "workiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stuffbucket/workiq-proxy"]
    }
  }
}

VS Code / GitHub Copilot

Project-level — add to .vscode/mcp.json:

{
  "servers": {
    "workiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stuffbucket/workiq-proxy"]
    }
  }
}

User-level — add to VS Code user settings (settings.json):

{
  "mcp": {
    "servers": {
      "workiq": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@stuffbucket/workiq-proxy"]
      }
    }
  }
}

OpenAI Codex CLI

Add to .codex/mcp.json:

{
  "mcpServers": {
    "workiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stuffbucket/workiq-proxy"]
    }
  }
}

Flags

Flag	Default	Description
--workiq-cmd	npx -y @microsoft/workiq	Base command to reach the Work IQ CLI (proxy appends mcp for MCP mode)
--log-file	~/.work-iq-cli/mcp-traffic.log	Override log file path
--no-log	false	Disable traffic logging
--port	11435	Port for serve mode (seeks next available if busy)

Example with a globally installed Work IQ CLI:

{
  "mcpServers": {
    "workiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stuffbucket/workiq-proxy", "--workiq-cmd", "workiq"]
    }
  }
}

Verify

After configuring, check that the server connects:

• Claude Code: Run /mcp to see server status and available tools
• VS Code: Check the MCP server status in the output panel

You should see 9 tools: accept_eula, ask_work_iq, plus the 7 synthetic search tools.

Troubleshoot

The proxy enriches five categories of upstream errors with actionable hints:

Error pattern	Likely cause	Fix
EULA / license agreement	Work IQ EULA not accepted	Run workiq-proxy accept-eula
Error 530084 / token protection	Org requires token protection CA policy	Ask IT admin to exempt the Work IQ CLI app
AADSTS / security policy	Entra ID conditional access policy blocking	Check the error code and contact IT admin
InteractionRequired	Browser login needed	Run workiq-proxy ask -q "What's on my calendar?" to re-authenticate
Failed to create conversation	Auth token expired or Copilot license inactive	Run workiq-proxy ask -q "What's on my calendar?" to re-authenticate

Server not connecting — Check ~/.work-iq-cli/mcp-traffic.log for the full JSON-RPC transcript.

Development

# Build
make build

# Test
make test

# Lint (Go + JS)
make lint

# Cross-compile all platforms
make all

Programmatic API

Use workiq-proxy as a dependency to embed Work IQ in your own Node.js project:

npm install @stuffbucket/workiq-proxy

Pipe-based (no port, no network)

const { createClient } = require("@stuffbucket/workiq-proxy");

const client = await createClient();
const answer = await client.ask("What's on my calendar?");
console.log(answer);

const emails = await client.searchEmails({ from: "alice", date_range: "last week" });
const docs   = await client.searchDocuments({ keywords: "quarterly report" });
const chats  = await client.searchChats({ person: "bob", keywords: "standup" });

await client.close();

createClient() spawns workiq-proxy over stdio pipes — no port, no HTTP. The MCP handshake happens automatically.

Method	Description
ask(question)	Ask Microsoft 365 Copilot a question
searchEmails(params)	Search emails (from, subject, keywords, date_range)
searchDocuments(params)	Search documents (filename, keywords, site, file_type)
searchChats(params)	Search chats (person, keywords, date_range, channel)
callTool(name, args)	Call any MCP tool by name
listTools()	List all available tools
close()	Shut down the child process

Options: createClient({ workiqCmd?, noLog? })

HTTP server (OpenAI-compatible)

If you need an HTTP API (e.g. for non-Node consumers):

const { createServer } = require("@stuffbucket/workiq-proxy");

const server = await createServer();           // starts serve --json
const models = await server.listModels();      // /v1/models
const reply  = await server.chat("What's on my calendar?");
console.log(reply.choices[0].message.content);
await server.close();

Method	Description
server.url	Base URL (e.g. http://127.0.0.1:11435)
server.listModels()	List available models
server.chat(message)	Send a chat message (string or full OpenAI request body)
server.chat(body, { stream: true })	Stream SSE chunks
server.onEvent(fn)	Subscribe to JSONL log events; returns unsubscribe function
server.events	Array of all captured log events
server.close()	Shut down the server

Options: createServer({ port?, workiqCmd?, noLog? })

License

MIT — see LICENSE. Charmbracelet libraries are used under the MIT license (see third-party notices in LICENSE).