CLIaaS

Imported from discordwell/CLIaaS (AGENTS.md). Install upstream with npx skills add discordwell/CLIaaS. Copyright stays with the author.

AGENTS.md

Domain Topology

• Primary domain: https://cliaas.com (including https://www.cliaas.com)
• Primary domain code location: /Users/discordwell/Projects/Zachathon
• Canonical repository: https://github.com/discordwell/CLIaaS
• Infrastructure note: deployed to a VPS via scripts/deploy_vps.sh, with systemd + nginx config from deploy/.

Guardrails

• Keep framework as Next.js App Router.
• Prioritize clean deploy path to a public URL.
• Ignore any code in the EasterEgg folder unless you are specifically tasked with developing it.

CLIaaS MCP Agent Guide

CLIaaS exposes 60 MCP tools, 6 resources, and 4 prompts for AI-powered helpdesk management.

Quick Start

# Install globally
npm install -g cliaas

# Initialize in any project (writes .mcp.json + agent instructions + demo data)
cliaas init

# Verify MCP server
cliaas mcp test

Or for full BYOC setup: cliaas setup

Tool Catalog

Tickets (3 tools)

Analysis (6 tools)

Knowledge Base (2 tools)

RAG (3 tools) — requires pgvector database

Queue (2 tools)

Config (2 tools)

Write Actions (7 tools)

Sync (8 tools)

Surveys (3 tools)

Chatbots (4 tools)

Workflows (6 tools)

Customers (4 tools)

Time Tracking (2 tools)

Forums (3 tools)

QA (2 tools)

Campaigns (3 tools)

Resources (6)

Prompts (4)

Domain Model

Ticket

• Statuses: open, pending, on_hold, solved, closed
• Priorities: low, normal, high, urgent
• Sources: zendesk, kayako, kayako-classic, helpcrunch, freshdesk, groove, intercom, helpscout, zoho-desk, hubspot
• Fields: id, externalId, subject, status, priority, assignee, requester, tags, createdAt, updatedAt

Message

• Types: reply, note, system
• Fields: id, ticketId, author, body, type, createdAt

KBArticle

• Fields: id, externalId, title, body, categoryPath

Data Modes

JSONL File Mode (no database needed)

All ticket/message/KB tools work with JSONL files in ./exports/. Generate demo data:

pnpm cliaas demo

Postgres Mode (full features + RAG)

Set DATABASE_URL and/or RAG_DATABASE_URL for RAG features:

# Self-hosted
docker compose up -d
pnpm cliaas rag init
pnpm cliaas rag import source --type kb
pnpm cliaas rag import source --type tickets

Workflow Recipes

Morning Triage

1. queue_stats — overview of queue volume
2. sla_report — check for breaches
3. triage_batch with status=open — AI-powered prioritization
4. draft_reply for urgent tickets — prepare responses

Customer Investigation

1. tickets_search with customer name/email
2. tickets_show for each relevant ticket
3. sentiment_analyze on the customer's tickets
4. detect_duplicates to find related issues

KB-Augmented Reply

1. tickets_show — read the full conversation
2. kb_suggest with useRag=true — find relevant articles
3. draft_reply with useRag=true — generate context-aware draft

Shift Handoff

1. summarize_queue — AI summary of queue state
2. sla_report — compliance status
3. sentiment_analyze — frustrated customers
4. Compile into handoff notes

Duplicate Cleanup

1. detect_duplicates with threshold=70
2. tickets_show for each group to verify
3. Tag or merge as appropriate

Error Patterns

Architecture

cli/mcp/
├── server.ts           # Entry point (stdio transport, `cliaas mcp serve`)
├── util.ts             # Safe wrappers, result helpers
├── tools/
│   ├── tickets.ts      # 3 tools: list, show, search
│   ├── analysis.ts     # 6 tools: triage, draft, sentiment, duplicates, summarize
│   ├── kb.ts           # 2 tools: search, suggest
│   ├── rag.ts          # 3 tools: search, ask, status
│   ├── queue.ts        # 2 tools: stats, sla
│   ├── config.ts       # 2 tools: show, set-provider
│   ├── actions.ts      # 7 tools: ticket CRUD, rules, ai_resolve
│   ├── sync.ts         # 8 tools: sync trigger/status/pull/push/conflicts, upstream
│   ├── surveys.ts      # 3 tools: config, send, stats
│   ├── chatbots.ts     # 4 tools: list, create, toggle, delete
│   ├── workflows.ts    # 6 tools: list, get, create, toggle, delete, export
│   ├── customers.ts    # 4 tools: list, show, search, merge
│   ├── time.ts         # 2 tools: report, log
│   ├── forums.ts       # 3 tools: categories, threads, thread_to_ticket
│   ├── qa.ts           # 2 tools: reviews, scorecard
│   └── campaigns.ts    # 3 tools: list, create, stats
├── resources/
│   └── index.ts        # 6 resources
└── prompts/
    └── index.ts        # 4 prompts

The MCP server reuses existing CLI infrastructure:

• cli/data.ts — JSONL file loading
• cli/providers/ — LLM provider abstraction (Claude, OpenAI, OpenClaw)
• cli/rag/ — pgvector retrieval pipeline
• cli/config.ts — config management