kolay-cli 0.11.11a0

Command-line interface for Kolay IK (https://apidocs.kolayik.com)

CLI and MCP Server for Kolay IK

               ███████████████████████
              ████               ████ 
             ████               ████ 
            ████               ████          ████                             ███ 
           ███                ████           ████                             ███ 
         ████                ███             ████                             ███ 
        ████               ████              ████     █████    █████████      ███     █████████ ████  ████        ████ 
       ████               ████               ████   █████    █████████████    ███    ███████████████   ████      ████ 
      ████               ████                ████  ████     ████       ████   ███   ████       █████    ███     ████ 
       ████             ██████               ████████      ████         ████  ███  ████         ████    ████    ███ 
        ████           ████████              ████████      ████         ████  ███  ████         ████     ████  ████ 
         ████         ███   ████             ████ █████    ████         ████  ███  ████         ████      ████████ 
          ████      ████     ████            ████   ████    █████     █████   ███   █████     ██████       ██████ 
           ████    ████        ███           ████     ████    ███████████     ███     ██████████████        █████ 
             ███  ████          ████                             █████                   ████               ████ 
              ███████            ████                                                                      ████ 
               ███████████████████████                                                                  ██████ 
                █████████████████████                                                                   ███ 

CLI and MCP server for Kolay IK. Manage employees, leaves, timelogs, trainings, and payroll from your terminal or through any AI assistant that supports MCP.

---

Table of Contents

• Disclaimer (Alpha)
• Install
• Setup
• CLI Usage
  • People
  • Leaves
  • Timelogs
  • Trainings
  • Transactions & Payroll
  • Other Resources
• User Experience
• Output Modes
• MCP Server (AI Integration)
  • Quick Start — Which setup is right for me?
  • Option 1: Public Server (no deployment needed)
  • Option 2: Local Mode (stdio)
  • Option 3: Self-Host (Railway / Docker)
  • Proxy Monitoring & Limits
• Client Setup Guides
  • ChatGPT (OpenAI)
  • Perplexity AI
  • Mistral Le Chat
  • Claude Desktop
  • Cursor
  • Gemini CLI
  • VS Code (GitHub Copilot)
  • Windsurf
  • Zed
  • Any Other MCP Client
• How Authentication Works
• Available MCP Tools
• MCP Prompts
• Usage Examples (AI Conversations)
• Test with curl
• Project Structure
• Development
• License

---

Disclaimer (Alpha)

⚠️ Please read before using.

1. Unofficial project. This is an independent lab application, not a Kolay IK product. Kolay Yazilim A.S. is not responsible for any data loss or issues caused by this software.
2. Your token, your responsibility. Generate tokens at app.kolayik.com/settings/developer-settings and keep them safe.
3. Write operations are real. Every create, update, delete, and terminate action modifies live HR data. There is no sandbox.
4. Alpha software. Expect bugs. Report them at GitHub Issues.

---

Install

# recommended (isolated environment)
pipx install kolay-cli

# or plain pip
pip install kolay-cli

This gives you two commands:

Command	Purpose
kolay	Interactive CLI for terminal use
kolay-mcp	MCP server binary (used by AI clients)

---

Setup

# guided first-time setup (token + config in one step)
kolay setup

# or authenticate manually
kolay auth login

You need a Kolay IK API token. Generate one at: app.kolayik.com/settings/developer-settings

Verify everything works:

kolay doctor

---

CLI Usage

Commands follow a kolay <resource> <action> pattern.

People

# list active employees (default: 20 per page)
kolay person list

# list with a limit
kolay person list --limit 50

# search by name
kolay person list --search "Ahmet"

# view a specific employee (interactive picker if no ID given)
kolay person view
kolay person view abc123def456

# create a new employee
kolay person create --first-name "Ayse" --last-name "Yilmaz" \
  --email "[e-mail]" --start-date 2026-04-01

# terminate an employee
kolay person terminate abc123def456 --date 2026-03-31 --reason 03

Leaves

# list approved leaves
kolay leave list

# list pending leaves for a specific person
kolay leave list --status waiting --person-id abc123def456

# create a leave request
kolay leave create --person-id abc123def456 --type-id <leave-type-uuid> \
  --start 2026-04-10 --end 2026-04-12

# cancel a leave
kolay leave cancel <leave-id>

Timelogs

# list recent timelogs
kolay timelog list

# create an overtime entry
kolay timelog create --person-id abc123def456 \
  --start "2026-03-10 18:00:00" --end "2026-03-10 21:00:00" --type overtime

# delete a timelog
kolay timelog delete <timelog-id>

Trainings

# list training catalogue
kolay training list

# assign a training to an employee
kolay training assign --person-id abc123def456 --training-id <training-uuid>

Transactions & Payroll

# list all transactions (bonuses, deductions, etc.)
kolay transaction list

# create a bonus record
kolay transaction create --person-id abc123def456 \
  --type bonus --amount 5000 --date 2026-03-01

# view the full payroll sheet (Çarşaf Bordro) for a run
kolay payroll view abc123def456

# search/filter rows within a payroll run
kolay payroll view abc123def456 --search "Ahmet" --filter "Dev"

Other Resources

kolay calendar list                       # company calendar events
kolay unit tree                           # organisational chart
kolay approval list                       # approval workflows
kolay expense list                        # expense records

---

🛠️ User Experience

This CLI is designed with a "People First" philosophy. We hate digging for UUIDs and getting cold errors.

• Interactive Fallbacks: Every command that requires an ID (view, delete, update) will launch an interactive fuzzy picker if you omit the argument.
• Smart Hints: If a command fails, we don't just show a stack trace. We suggest next steps, missing scopes, or dashboard paths.
• Structured Error Handling: When running with --json, we provide machine-readable error shapes for robust automation.
• Client-Side Magic: Most list commands support --filter (regex/substring) to instantly narrow down results locally without re-fetching from the API.
• Rich Visualization: We use Rich to render beautiful tables, status badges, and panels that make HR data human-readable.

---

Output Modes

Flag	What it does
--json	Machine-readable JSON output (for scripts and AI agents)
--yes	Skip confirmation prompts on destructive actions
--debug	Log HTTP traces to ~/.config/kolay/debug.log

# pipe JSON output to jq
kolay --json person list --limit 5 | jq '.items[].firstName'

# delete without confirmation prompt
kolay --yes timelog delete <id>

---

MCP Server (AI Integration)

kolay-cli ships a full Model Context Protocol server. Any MCP-compatible AI client can manage your HR data through natural language.

Quick Start — Which setup is right for me?

I want to…	Method	Time
Use with ChatGPT, Le Chat, Perplexity, or any web AI	Public Server (Option 1)	2 min
Use with Claude Desktop, Cursor, Gemini CLI	Local Mode (Option 2)	1 min
Full control, own hosting	Self-Host (Option 3)	15 min

---

Option 1: Use the Public Server (no deployment needed)

A shared multi-tenant endpoint is available at:

https://kolay.up.railway.app/mcp

Each user sends their own Kolay IK token via the X-Kolay-Token header. No tokens are stored on the server; they are used only for the duration of each request.

Connect from any MCP client by setting the URL and passing your token:

{
  "mcpServers": {
    "kolay-ik": {
      "url": "https://kolay.up.railway.app/mcp",
      "headers": {
        "X-Kolay-Token": "YOUR_KOLAY_API_TOKEN"
      }
    }
  }
}

Option 2: Local Mode (stdio)

For AI clients running on your machine (Claude Desktop, Cursor, etc.), the automated installer writes the correct config for you:

kolay mcp install

Restart your AI client after running this. Supported clients:

Client	Config Location
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor (global)	~/.cursor/mcp.json
Cursor (project)	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Gemini CLI	~/.gemini/settings.json
VS Code (Copilot)	User-level mcp.json
Zed	~/.config/zed/settings.json

Option 3: Self-Host (Railway / Docker)

Deploy your own private instance for full control.

1. Push the repo to GitHub
2. Create a Railway project -> Deploy from GitHub repo
3. Set environment variables in Railway:

Variable	Description
KOLAY_API_TOKEN	Your Kolay IK API token (single-tenant mode)
PYTHONUNBUFFERED	1
MCP_API_KEY	Optional gateway key for abuse prevention

4. Enable public networking in Railway settings
5. Your endpoint: https://<your-app>.up.railway.app/mcp

Or run locally in HTTP mode:

export KOLAY_API_TOKEN="your-token"
kolay mcp serve --transport http --port 8000

---

Proxy Monitoring & Limits

When hosting the MCP proxy (e.g., on Railway), you can enable rate limiting and monitor activities.

Rate Limiting (Opt-in)

The proxy supports per-token sliding-window rate limiting. It tracks requests by a privacy-safe hash of each Kolay API token. To enable, set:

MCP_RATE_LIMIT_ENABLED=true
MCP_RATE_LIMIT_PER_MINUTE=30    # Default: 30
MCP_RATE_LIMIT_PER_HOUR=500     # Default: 500

Activity Logging

The proxy outputs structured JSON logs for every tool invocation to stdout. These logs include:

• Hashed token key (last 8 chars)
• Tool name and duration
• Redacted argument summary (no PII or long strings)
• Success/failure status

Example log record:

{"ts": "2026-03-17T12:00:00Z", "event": "mcp.tool_call", "token_key": "tok_…a1b2c3d4", "tool": "person_list", "duration_ms": 142.5, "success": true}

---

Client Setup Guides

Step-by-step instructions for connecting Kolay MCP to popular AI clients.

ChatGPT (OpenAI)

ChatGPT supports remote MCP servers as Apps (formerly called "connectors"). Available on all plans including Plus, Pro, Business, Enterprise, and Education. Requires Developer Mode to add custom servers.

Important: ChatGPT connects to remote MCP servers only — it cannot run local stdio servers. Your MCP server must be reachable over HTTPS.

Step 1 — Enable Developer Mode:

1. Open chatgpt.com → click your profile icon → Settings
2. Go to Apps & Connectors → scroll to Advanced settings (bottom of the page)
3. Toggle Developer mode ON
4. You should now see a Create button at the top of the Apps & Connectors page

Step 2 — Create the connector:

1. In Settings → Apps & Connectors, click Create
2. Fill in the connector details:
   • Connector name: Kolay IK
   • Description: HR management — employees, leaves, timelogs, trainings, payroll
   • Connector URL: https://kolay.up.railway.app/mcp
3. Click Create
4. If the connection succeeds, you'll see a list of tools the server advertises

Authentication note: ChatGPT Apps support OAuth 2.1 for user-level auth. For Kolay IK, the simplest approach is to deploy with KOLAY_API_TOKEN set as an environment variable on the server (single-tenant mode), which requires no user-side auth setup. If you need per-user tokens, see the self-host option.

Step 3 — Use it in a conversation:

1. Open a new chat in ChatGPT
2. Click the + button near the message composer, then click More
3. Select Kolay IK from the list of available tools
4. Ask a question like "Show me all active employees"

ChatGPT will display tool-call payloads so you can confirm inputs and outputs. Write operations require manual confirmation.

Tip: After updating your MCP server, refresh the connector metadata: go to Settings → Apps & Connectors, click into your connector, and choose Refresh.

📖 Full docs: developers.openai.com/apps-sdk/deploy/connect-chatgpt

---

Perplexity AI

Perplexity supports remote MCP servers via Connectors. Requires a Perplexity Pro or Enterprise plan.

Important: Perplexity connects to remote MCP servers only — it does not run local stdio servers. Your MCP server must be reachable over HTTPS.

Step 1 — Open connector settings:

1. Go to perplexity.ai and sign in
2. Click your profile icon → Settings
3. Navigate to Connectors

Step 2 — Add a remote connector:

1. Click + Custom connector → select Remote
2. Fill in the connector details:
   • Name: Kolay IK
   • MCP Server URL: https://kolay.up.railway.app/mcp
   • Description (optional): HR management — employees, leaves, timelogs, trainings, payroll
   • Transport: Streamable HTTP
   • Authentication: select one of:
     • None — if the server has KOLAY_API_TOKEN set (single-tenant mode)
     • API Key — enter your Kolay IK API token if using multi-tenant mode
3. Click Save

Step 3 — Use it in a conversation:

1. Open a new thread on Perplexity
2. Make sure the Kolay IK connector is enabled (check the connectors panel)
3. Ask a question like:

   Show me all active employees in the Engineering department
   

Perplexity will automatically discover the available tools from the MCP server and invoke them as needed.

Tip: If you update or redeploy the MCP server, re-open the connector settings and verify the connection is still active.

📖 Full docs: perplexity.ai/help-center — Local and Remote MCPs

---

Mistral Le Chat

1. Open chat.mistral.ai and go to Intelligence → Connectors (or chat.mistral.ai/connections)
2. Click Add Connector → Custom MCP Connector
3. Fill in:
   • Name: Kolay IK
   • URL: https://kolay.up.railway.app/mcp
   • Description (optional): HR management tools for Kolay IK
4. For authentication, select:
   • No Authentication — if the server has KOLAY_API_TOKEN set (single-tenant)
   • HTTP Bearer Token — enter your Kolay IK API token if using multi-tenant mode
5. Click Connect
6. In any chat, make sure the Kolay IK connector is enabled (toggle it on in the connectors panel)

Now ask Le Chat:

Who are the employees in the engineering department?

Tip: Le Chat auto-detects available tools from the MCP server. You don't need to configure individual tools.

---

Claude Desktop

Automatic (recommended):

kolay mcp install

This writes the correct config to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Restart Claude Desktop.

Manual:

1. Open Claude Desktop → Settings → Developer → Edit Config
2. Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "kolay-ik": {
      "command": "kolay-mcp",
      "args": []
    }
  }
}

3. Save and restart Claude Desktop
4. You should see "kolay-ik" in the MCP servers list (🔌 icon)

Remote mode (no local install):

1. In Claude Desktop → Settings → Connectors → Add custom connector
2. Enter URL: https://kolay.up.railway.app/mcp
3. Optionally add your X-Kolay-Token in the URL as a query parameter or configure the Authorization header

---

Cursor

Automatic:

kolay mcp install

Manual (global): Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kolay-ik": {
      "command": "kolay-mcp",
      "args": []
    }
  }
}

Manual (project-level): Create .cursor/mcp.json in your project root with the same content.

Restart Cursor after saving.

---

Gemini CLI

Automatic:

kolay mcp install

Manual: Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "kolay-ik": {
      "command": "kolay-mcp",
      "args": []
    }
  }
}

---

VS Code (GitHub Copilot)

1. Open VS Code → Settings (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)")
2. Add to mcp.servers:

{
  "mcp": {
    "servers": {
      "kolay-ik": {
        "command": "kolay-mcp",
        "args": []
      }
    }
  }
}

3. Alternatively, use the remote URL via the MCP extension settings

---

Windsurf

Automatic:

kolay mcp install

Manual: Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kolay-ik": {
      "command": "kolay-mcp",
      "args": []
    }
  }
}

---

Zed

Edit ~/.config/zed/settings.json and add under "context_servers":

{
  "context_servers": {
    "kolay-ik": {
      "command": {
        "path": "kolay-mcp",
        "args": []
      }
    }
  }
}

---

Any Other MCP Client

Any client that supports the MCP standard can connect using either:

• Remote (HTTP/SSE): Point to https://kolay.up.railway.app/mcp with an X-Kolay-Token header
• Local (stdio): Run the kolay-mcp binary (installed with pip install kolay-cli)

---

How Authentication Works

AI Client --> POST /mcp --> MCP Handshake (always succeeds)
                                |
                           Tool Call
                                |
                         @require_auth checks token
                           /           \
                     token found     no token
                          |              |
                     Kolay API     401 error to AI

The MCP session always connects successfully. Authentication happens at the tool level — every HR tool checks for a valid token before accessing data. This means AI clients can discover available tools before authenticating.

Token resolution order:

1. X-Kolay-Token header (per-request, multi-tenant)
2. Authorization: Bearer <token> header
3. KOLAY_API_TOKEN environment variable (single-tenant fallback)

---

Available MCP Tools

The server exposes these tools to AI clients:

Tool	Description
validate_connection	Check if credentials are working
person_list, person_view, person_summary	Read employee data
person_leave_status	View leave balances for an employee
person_create, person_update, person_terminate	Write employee data
person_rehire, person_update_fields	Rehire or patch arbitrary fields
leave_list, leave_view, leave_create, leave_cancel	Manage leaves
request_time_off	Natural language leave creation
analyze_leave_impact	Dry-run balance check before booking leave
timelog_list, timelog_view, timelog_create, timelog_delete	Manage timelogs
training_list, training_view, training_create, training_delete	Training catalogue
person_assign_training, person_list_trainings, person_update_training	Training assignments
transaction_list, transaction_view, transaction_create, transaction_delete	Manage payroll
calendar_list, calendar_view, calendar_create, calendar_update, calendar_delete	Manage events
unit_tree	View organisational structure
approval_list	View approval workflows
employee_health_check	Cross-reference leaves, timelogs, and trainings in one call

---

MCP Prompts

Built-in prompts guide the AI through complex multi-step workflows:

Prompt	What it does
employee_snapshot	Full profile + leave balance report for one employee
burnout_analyzer	Scan a department for burnout risk based on unused annual leave
onboarding_plan	Generate welcome email, IT checklist, and meeting schedule for a new hire
offboarding_plan	Calculate leave payout, handover checklist, and exit interview questions
bulk_update_assistant	Safe bulk data cleanup with mandatory human confirmation
manager_dashboard	Morning briefing for a department manager
hr_capabilities	Guided prompt explaining all available Kolay HR AI features

---

Usage Examples (AI Conversations)

Here are real-world examples of what you can ask any AI assistant connected to Kolay MCP:

Listing Employees

You: Show me all active employees
AI:  → calls person_list(status="active", limit=20)
     Found 47 employees. Here are the first 20:
     1. Ayşe Yılmaz — Engineering — [e-mail]
     2. Mehmet Demir — Marketing — [e-mail]
     ...

Searching for Someone

You: Find the employee named Ahmet
AI:  → calls person_list(search="Ahmet")
     Found 2 matches:
     1. Ahmet Kaya (ID: abc123) — Engineering
     2. Ahmet Yıldız (ID: def456) — Sales

Viewing an Employee Profile

You: Show me Ayşe Yılmaz's full profile
AI:  → calls person_view(person_id="Ayşe Yılmaz")
     Name: Ayşe Yılmaz
     Department: Engineering
     Start Date: 2023-01-15
     Email: [e-mail]
     Phone: [phone]
     ...

Checking Leave Balances

You: How many days of annual leave does Mehmet have left?
AI:  → calls person_leave_status(person_id="Mehmet Demir")
     Annual Leave: 8.5 days remaining (out of 14)
     Sick Leave: 10 days remaining
     ...

Requesting Time Off

You: I want to take next Monday and Tuesday off as annual leave
AI:  → calls analyze_leave_impact(person_id="...", leave_type_id="...", requested_days=2)
     You have 8.5 days remaining. After this request: 6.5 days.
     Shall I go ahead and submit this?
You: Yes
AI:  → calls request_time_off(person_id="...", leave_type_id="...",
         start_date="2026-03-16", end_date="2026-03-17")
     ✅ Leave request submitted for March 16–17.

Listing Pending Leaves

You: Show me all pending leave requests
AI:  → calls leave_list(status="waiting")
     3 pending requests:
     1. Ayşe Yılmaz — Annual Leave — Mar 20–22
     2. Mehmet Demir — Sick Leave — Mar 18
     3. Zeynep Kara — Annual Leave — Apr 1–5

Creating a New Employee

You: Add a new employee: Ali Veli, [e-mail], starting April 1st
AI:  ⚠️ This will create a real employee record. Confirm?
You: Yes
AI:  → calls person_create(first_name="Ali", last_name="Veli",
         email="[e-mail]", employment_start="2026-04-01")
     ✅ Employee created: Ali Veli (ID: ghi789)

Employee Health Check

You: Give me a quick health check on Ayşe Yılmaz
AI:  → calls employee_health_check(person_id="Ayşe Yılmaz")
     📋 Upcoming leaves: Annual Leave Mar 20–22
     ⏱️ Recent timelogs: 42h this week (8h overtime)
     📚 Training: "AWS Security" — completed

Organisation Chart

You: Show me the company org chart
AI:  → calls unit_tree()
     🏢 Acme Corp
     ├── 🏗️ Engineering (12 people)
     │   ├── Backend Team (5)
     │   └── Frontend Team (4)
     ├── 📈 Marketing (8 people)
     └── 💰 Finance (5 people)

Manager Morning Briefing (using prompt)

You: Give me a morning briefing for the Engineering department
AI:  → uses manager_dashboard prompt
     📊 Engineering Department — Morning Briefing
     • 2 people on leave today (Ayşe, Mehmet)
     • 1 pending leave request to approve
     • 3 overtime entries logged yesterday
     • Training "Cloud Security 101" starts next week (4 enrolled)

---

Test with curl

# discover available tools
curl -X POST https://kolay.up.railway.app/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

---

Project Structure

src/kolay_cli/
  cli.py              # entry point, global flags
  mcp_server.py       # FastMCP server with all tools and prompts
  security.py         # token storage, validation, @require_auth
  api/
    client.py         # HTTP client (requests + retry)
    errors.py         # APIError + exit codes
  commands/           # one module per resource group
    person.py, leave.py, timelog.py, training.py,
    transaction.py, calendar.py, unit.py, approval.py, ...
  services/           # business logic (used by both CLI and MCP)
  ui/
    formatters.py     # Rich tables, spinners
    output.py         # JSON mode
    pickers.py        # interactive ID selection
    search.py         # client-side filtering

---

Development

# install with test dependencies
pip install -e ".[test,dev]"

# run tests
pytest tests/ -v

# or using uv
uv run --extra test pytest tests/ -v

---

License

MIT