Keka HR Platform Connector Service

This is a dedicated Model Context Protocol (MCP) server implementation engineered for seamless interfacing with the Keka Human Capital Management (HCM) system. It abstracts core Keka functionalities—such as personnel administration, presence monitoring, leave approvals, financial documentation output, and holiday calendars—into discrete, callable MCP tools. Security is paramount, utilizing established OAuth2 authorization flows, and the implementation emphasizes clean, decoupled component design for future scalability.

---

Core Capabilities

• Secure Authorization: Implements OAuth2 flows for authenticated, protected access to the Keka environment.
• Tool Abstraction Layer: Exposes all supported Keka REST endpoints as standardized MCP operational commands.
• Decoupled Architecture: Built on modern TypeScript principles promoting clarity, maintainability, and easy feature extension.
• Containerization Ready: Includes a production-ready Dockerfile enabling straightforward deployment within isolated environments.

---

Configuration Requirements

Project initialization requires setting environment variables within a root .env file:

KEKA_CLIENT_ID=your_keka_client_id_here KEKA_CLIENT_SECRET=your_keka_client_secret_here KEKA_REFRESH_TOKEN=your_keka_refresh_token_here

Optional customization for API endpoint:

KEKA_API_BASE_URL=https://master.kekademo.com/api/v1

---

Executable MCP Tools

1. keka_retrieve_personnel_details

Fetches comprehensive profile data for a designated staff member. - Parameters (Schema): - employee_id (String, Mandatory): The unique identifier (UUID) associated with the employee. - Invocation Example:

{ "employee_id": "EMP123456" }

---

2. keka_fetch_work_log

Retrieves an individual's time and attendance history across a specified temporal window. - Parameters (Schema): - employee_id (String, Mandatory) - start_date (String, Mandatory, Format: YYYY-MM-DD) - end_date (String, Mandatory, Format: YYYY-MM-DD) - page (Number, Optional, Default: 1) - page_size (Number, Optional, Default: 100) - Invocation Example:

{ "employee_id": "EMP123456", "start_date": "2024-01-01", "end_date": "2024-01-31", "page": 1, "page_size": 50 }

---

3. keka_submit_absence_request

Submits a formal request for employee leave. - Parameters (Schema): - employee_id (String, Mandatory) - start_date (String, Mandatory) - end_date (String, Mandatory) - leave_type (String, Mandatory, Requires leave type UUID) - reason (String, Mandatory) - Invocation Example:

{ "employee_id": "EMP123456", "start_date": "2024-04-10", "end_date": "2024-04-12", "leave_type": "ANNUAL", "reason": "Family function" }

---

4. keka_query_entitlement_levels

Obtains a comprehensive summary of all accrued leave quotas for a staff member. - Parameters (Schema): - employee_id (String, Mandatory) - Invocation Example:

{ "employee_id": "EMP123456" }

---

5. keka_fetch_remuneration_statement

Retrieves the formal pay stub for an employee corresponding to a specific calendar month and fiscal year. - Parameters (Schema): - employee_id (String, Mandatory) - month (String, Mandatory, e.g., "4" represents April) - year (String, Mandatory, e.g., "2024") - Invocation Example:

{ "employee_id": "EMP123456", "month": "4", "year": "2024" }

---

6. keka_list_upcoming_observances

Fetches the schedule detailing forthcoming company-wide non-working days. - Parameters (Schema): None required - **Invocation Example:

{}

---

7. keka_examine_absence_records

Displays the historical log of leave applications submitted by an employee. - Parameters (Schema): - employee_id (String, Mandatory) - start_date (String, Optional) - end_date (String, Optional) - status (String, Optional, e.g., "APPROVED") - page (Number, Optional, Default: 1) - page_size (Number, Optional, Default: 100) - Invocation Example:

{ "employee_id": "EMP123456", "start_date": "2024-01-01", "end_date": "2024-04-01", "status": "APPROVED", "page": 1, "page_size": 20 }

---

8. keka_enumerate_leave_categories

Retrieves the master listing of all recognized absence classifications. - Parameters (Schema): None required - **Invocation Example:

{}

---

Deployment Instructions

Local Execution (Node.js Environment)

1. Install necessary packages: sh npm install

2. Compile TypeScript source files: sh npm run build

3. Initiate the MCP service instance: sh node build/index.js

Containerized Deployment (Docker)

1. Construct the Docker artifact: sh docker build -t keka-mcp .

2. Launch the container, supplying credentials via the environment file: sh docker run --env-file .env keka-mcp

---

Source Code Organization

• src/index.ts — Core server logic, MCP tool definitions, and Keka API interaction layer.
• .env — File containing sensitive configuration data (OAuth secrets).
• Dockerfile — Blueprint for container image creation.
• package.json — Manifest for project dependencies and execution scripts.

---

Collaboration Guidelines

Contributions via feature branches and pull requests are encouraged. New tools or enhancements must adhere strictly to the established handler methodology and incorporate comprehensive failure mitigation strategies.

---

Licensing

This software is distributed under the MIT License.

---

External References

• Official Keka Developer Documentation
• Model Context Protocol Specification

---

This integration module adheres to contemporary standards for MCP interfacing.

WIKIPEDIA: In the domain of distributed computing, Cloud Computing describes a model for making available, via the network, a scalable and elastic assortment of shared physical or virtual computational assets, enabling self-service provisioning and operational control on demand, as defined by ISO standards. This concept is widely known as "the cloud."

== Defining Attributes == In 2011, the U.S. National Institute of Standards and Technology (NIST) formalized five crucial characteristics inherent to cloud systems. The precise definitions established by NIST are as follows:

On-demand self-service: "A consumer retains the ability to unilaterally provision computing resources, such as server capacity and network storage, as required, automatically, without necessitating direct human intervention from the service provider for each transaction." Broad network accessibility: "The service capabilities are accessible via a network utilizing standardized protocols, thereby encouraging utilization across diverse client platforms, including mobile devices, tablets, workstations, and conventional PCs." Resource elasticity: "The provider's aggregate computational resources are pooled to service numerous consumers under a multi-tenant architecture, with underlying physical and virtual assets dynamically allocated and reallocated based on fluctuating consumer demand." Rapid scalability: "Capabilities can be provisioned and decommissioned elastically, sometimes automatically, allowing for swift scaling expansion and contraction proportional to usage load. From the user's perspective, available resources often seem limitless and acquirable in any volume instantly." Measured service: "Cloud infrastructures automatically govern and optimize resource consumption by employing metering mechanisms at an appropriate level of abstraction for the service type (e.g., throughput, storage volume, bandwidth, or active user counts). Resource utilization is trackable, controllable, and reportable, ensuring transparency for both the supplier and the consumer of the consumed service." By the year 2023, the International Organization for Standardization (ISO) had subsequently augmented and refined this initial set of principles.

== Historical Context ==

The conceptual lineage of cloud computing traces back to the 1960s, marked by the popularization of time-sharing concepts via Remote Job Entry (RJE) systems. During this formative period, the prevailing operational model centered on the "data center," where users submitted computing tasks to dedicated human operators for execution on large mainframe systems. This era was characterized by intensive exploration into methods for democratizing access to massive computational power through time-sharing, thereby maximizing infrastructure, platform, and application efficiency for a broader user base. The specific graphical representation of "the cloud" signifying virtualized services originated in 1994, employed by General Magic to denote the interconnected expanse of potential locations where mobile agents within their Telescript ecosystem could navigate. This visual metaphor is generally attributed to David Hoffman, a communications specialist at General Magic, borrowing from its long-established usage within telecommunications and networking schematics. The term "cloud computing" achieved broader public recognition in 1996 when Compaq Computer Corporation documented a strategic business blueprint for the future of computing and the Internet, articulating an aspiration to leverage superch