kolay-cli

Kolay CLI and MCP Server

Disclaimer. This is an independent, community-maintained project. It is not an official product of Kolay Yazilim A.S. and carries no endorsement, warranty, or support from the company. All write operations target live HR data — there is no sandbox. You are solely responsible for your API token and the actions performed through this software.

Command-line interface and AI integration server for Kolay IK. Manage employees, leaves, timelogs, trainings, payroll, and organizational structure from the terminal or through any AI assistant that speaks Model Context Protocol.

Quick Start

# 1. Install
pipx install kolay-cli          # or: pip install kolay-cli

# 2. Authenticate
kolay setup                     # guided first-time setup

# 3. Verify
kolay doctor                    # health check

Requires Python 3.10 or later.

What This Package Provides

Binary Purpose
kolay Interactive CLI for terminal use
kolay-mcp MCP server binary for AI clients

The same pip install kolay-cli command installs both.

Documentation

Detailed guides are maintained separately for each component:

Guide Audience Contents
docs/CLI.md Terminal users, scripts, CI pipelines Full command reference, output modes, shell completion, local security
docs/MCP.md AI integrators, platform teams Client setup (ChatGPT, Claude, Gemini, Cursor, etc.), tool catalogue, architecture
docs/BOX.md Self-hosting teams, IT administrators Docker Compose deployment, GPU/CPU modes, troubleshooting
docs/SECURITY.md Security reviewers, compliance officers Encryption, PII masking, DLP, rate limiting, audit trail

Connecting AI Assistants

ChatGPT

  1. Open chatgpt.com → Settings → Apps & Connectors.
  2. Enable Developer Mode under Advanced settings.
  3. Click Create. Enter:
    • Name: Kolay IK
    • URL: https://kolay.up.railway.app/mcp
  4. Add a custom header: X-Kolay-Token → your Kolay API token.
  5. Save. Open a new chat, attach the Kolay IK app, and ask.

Claude Desktop

kolay mcp install       # writes claude_desktop_config.json automatically

Or manually add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Other Clients

Local (stdio): run kolay-mcp as a subprocess. Remote (HTTP): point to https://kolay.up.railway.app/mcp with an X-Kolay-Token header.

See docs/MCP.md for Gemini CLI, Cursor, VS Code, Windsurf, Zed, Mistral, and Perplexity instructions.

Self-Hosted AI (Kolay AI Box)

Run a fully private AI HR assistant on your own hardware. No cloud dependency.

cd box
make dev          # CPU mode (Mac, laptop)
# or
make up           # GPU mode (NVIDIA)

Open http://localhost:3000. See docs/BOX.md for full setup instructions.

Security Overview

Layer What it protects
OS keychain API token at rest (macOS Keychain, GNOME Keyring, Windows Vault)
AES-256-GCM Local config file encryption (opt-in)
TLS 1.2+ All network traffic
PII masking Names and emails replaced with pseudonyms before reaching the LLM
Egress DLP Last-mile redaction of TC Kimlik and IBAN patterns
Rate limiter Per-token sliding window to prevent abuse
Circuit breaker Stops infinite AI tool-calling loops
Audit log Local append-only log of all write operations, with 5 MB rotation

Two profiles are available via KOLAY_SECURITY_PROFILE:

Full details: docs/SECURITY.md.

Development

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

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

Stack

Exit Codes

Code Meaning
0 Success
1 General / server error
2 Bad input / validation
3 Not found
4 Auth / permission denied
5 Conflict

License

MIT

This site is open source. Improve this page.