@emplyx/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# @emplyx/mcp-server
+
+MCP (Model Context Protocol) server for Emplyx HR Platform. Exposes 346+ HR management tools to AI assistants like Claude.
+
+## Installation
+
+```bash
+npm install -g @emplyx/mcp-server
+# or use with npx
+npx @emplyx/mcp-server
+```
+
+## Configuration
+
+### 1. Get an API Key
+
+1. Log into your Emplyx admin panel
+2. Go to **Settings > API Keys**
+3. Create a new API key with the required scopes
+
+### 2. Configure Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "emplyx": {
+      "command": "npx",
+      "args": ["@emplyx/mcp-server"],
+      "env": {
+        "EMPLYX_API_KEY": "emplyx_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Configuration File Location
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `EMPLYX_API_KEY` | Yes | Your Emplyx API key (format: `emplyx_live_xxx`) |
+| `EMPLYX_API_URL` | No | API endpoint (default: production) |
+
+## Available Tools
+
+The server exposes tools based on your API key's scopes:
+
+| Scope | Tools |
+|-------|-------|
+| `employees:read` | Search employees, get employee details |
+| `employees:write` | Create, update, deactivate employees |
+| `schedules:read` | List shifts, view schedules |
+| `schedules:write` | Assign shifts, manage schedules |
+| `absences:read` | View absence requests, balances |
+| `absences:write` | Create/approve/reject absence requests |
+| `clockings:read` | View time entries, timelines |
+| `clockings:write` | Create corrections, approve requests |
+| `documents:read` | List documents |
+| `documents:write` | Upload, manage documents |
+| `*` | Full access to all 346+ tools |
+
+## Example Usage
+
+Once configured, you can ask Claude things like:
+
+- "Show me employees who are on vacation this week"
+- "Create an absence request for Juan from Feb 1-5"
+- "What are the active shifts in the company?"
+- "Search for employees named Maria"
+
+## Supported Platforms
+
+- macOS (arm64, x64)
+- Linux (x64, arm64)
+- Windows (x64)
+
+## Troubleshooting
+
+### "Invalid API Key"
+
+Ensure your API key:
+1. Starts with `emplyx_live_`
+2. Has not been revoked
+3. Has the required scopes
+
+### "Binary not found"
+
+The package includes pre-compiled binaries. If missing:
+1. Reinstall the package
+2. Check if your platform is supported
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.
+
+## Support
+
+- Documentation: https://docs.emplyx.com/mcp
+- Issues: https://github.com/emplyx/mcp-server/issues
+- Email: support@emplyx.com

package/bin/emplyx-mcp

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+/**
+ * Emplyx MCP Server CLI
+ *
+ * This script detects the current platform and executes the appropriate
+ * pre-compiled .NET binary for the Emplyx MCP server.
+ *
+ * Configuration:
+ * - EMPLYX_API_KEY: Required. Your Emplyx API key (emplyx_live_xxx)
+ * - EMPLYX_API_URL: Optional. API endpoint (default: https://api.emplyx.com)
+ */
+
+function getPlatformBinary() {
+    const platform = os.platform();
+    const arch = os.arch();
+
+    const platformMap = {
+        'darwin-arm64': 'osx-arm64',
+        'darwin-x64': 'osx-x64',
+        'linux-x64': 'linux-x64',
+        'linux-arm64': 'linux-arm64',
+        'win32-x64': 'win-x64'
+    };
+
+    const key = `${platform}-${arch}`;
+    const dir = platformMap[key];
+
+    if (!dir) {
+        console.error(`Error: Unsupported platform: ${key}`);
+        console.error('Supported platforms: darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64');
+        process.exit(1);
+    }
+
+    const ext = platform === 'win32' ? '.exe' : '';
+    const binaryName = `Emplyx.MCP${ext}`;
+    const binaryPath = path.join(__dirname, '..', 'dist', dir, binaryName);
+
+    if (!fs.existsSync(binaryPath)) {
+        console.error(`Error: Binary not found at ${binaryPath}`);
+        console.error('Please ensure the package was installed correctly.');
+        process.exit(1);
+    }
+
+    return binaryPath;
+}
+
+function checkApiKey() {
+    const apiKey = process.env.EMPLYX_API_KEY;
+
+    if (!apiKey) {
+        console.error('Error: EMPLYX_API_KEY environment variable is required');
+        console.error('');
+        console.error('To get an API key:');
+        console.error('1. Log into Emplyx admin panel');
+        console.error('2. Go to Settings > API Keys');
+        console.error('3. Create a new API key with the required scopes');
+        console.error('');
+        console.error('Usage:');
+        console.error('  EMPLYX_API_KEY=emplyx_live_xxx npx @emplyx/mcp-server');
+        process.exit(1);
+    }
+
+    if (!apiKey.startsWith('emplyx_live_')) {
+        console.error('Error: Invalid API key format');
+        console.error('API keys should start with "emplyx_live_"');
+        process.exit(1);
+    }
+}
+
+// Main
+checkApiKey();
+const binary = getPlatformBinary();
+
+// Spawn the .NET binary with inherited stdio for MCP communication
+const child = spawn(binary, process.argv.slice(2), {
+    stdio: 'inherit',
+    env: process.env
+});
+
+child.on('error', (err) => {
+    console.error(`Error starting MCP server: ${err.message}`);
+    process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+    if (signal) {
+        process.exit(1);
+    }
+    process.exit(code || 0);
+});
+
+// Handle termination signals
+process.on('SIGTERM', () => child.kill('SIGTERM'));
+process.on('SIGINT', () => child.kill('SIGINT'));

package/lib/postinstall.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const VERSION = '1.0.0';
+const GITHUB_REPO = 'ezemiz/emplyx';
+const BASE_URL = `https://github.com/${GITHUB_REPO}/releases/download/mcp-v${VERSION}`;
+
+function getPlatformInfo() {
+    const platform = os.platform();
+    const arch = os.arch();
+
+    const platformMap = {
+        'darwin-arm64': { dir: 'osx-arm64', file: 'Emplyx.MCP' },
+        'darwin-x64': { dir: 'osx-x64', file: 'Emplyx.MCP' },
+        'linux-x64': { dir: 'linux-x64', file: 'Emplyx.MCP' },
+        'linux-arm64': { dir: 'linux-arm64', file: 'Emplyx.MCP' },
+        'win32-x64': { dir: 'win-x64', file: 'Emplyx.MCP.exe' }
+    };
+
+    const key = `${platform}-${arch}`;
+    return platformMap[key];
+}
+
+function downloadFile(url, dest) {
+    return new Promise((resolve, reject) => {
+        const file = fs.createWriteStream(dest);
+
+        const request = (url) => {
+            https.get(url, (response) => {
+                if (response.statusCode === 302 || response.statusCode === 301) {
+                    // Follow redirect
+                    request(response.headers.location);
+                    return;
+                }
+
+                if (response.statusCode !== 200) {
+                    reject(new Error(`Failed to download: HTTP ${response.statusCode}`));
+                    return;
+                }
+
+                const totalSize = parseInt(response.headers['content-length'], 10);
+                let downloadedSize = 0;
+
+                response.on('data', (chunk) => {
+                    downloadedSize += chunk.length;
+                    const percent = ((downloadedSize / totalSize) * 100).toFixed(1);
+                    process.stdout.write(`\rDownloading Emplyx MCP Server... ${percent}%`);
+                });
+
+                response.pipe(file);
+
+                file.on('finish', () => {
+                    file.close();
+                    console.log('\nDownload complete!');
+                    resolve();
+                });
+            }).on('error', (err) => {
+                fs.unlink(dest, () => {});
+                reject(err);
+            });
+        };
+
+        request(url);
+    });
+}
+
+async function main() {
+    const platformInfo = getPlatformInfo();
+
+    if (!platformInfo) {
+        console.log('Unsupported platform. Skipping binary download.');
+        console.log('You can manually download the binary from:');
+        console.log(`  ${BASE_URL}`);
+        return;
+    }
+
+    const distDir = path.join(__dirname, '..', 'dist', platformInfo.dir);
+    const binaryPath = path.join(distDir, platformInfo.file);
+
+    // Check if binary already exists
+    if (fs.existsSync(binaryPath)) {
+        console.log('Emplyx MCP Server binary already installed.');
+        return;
+    }
+
+    console.log(`Installing Emplyx MCP Server for ${os.platform()}-${os.arch()}...`);
+
+    // Create dist directory
+    fs.mkdirSync(distDir, { recursive: true });
+
+    // Download binary (filename: emplyx-mcp-{platform} or emplyx-mcp-{platform}.exe)
+    const ext = os.platform() === 'win32' ? '.exe' : '';
+    const url = `${BASE_URL}/emplyx-mcp-${platformInfo.dir}${ext}`;
+
+    try {
+        await downloadFile(url, binaryPath);
+
+        // Make executable on Unix
+        if (os.platform() !== 'win32') {
+            fs.chmodSync(binaryPath, 0o755);
+        }
+
+        console.log('Emplyx MCP Server installed successfully!');
+    } catch (error) {
+        console.error(`\nFailed to download binary: ${error.message}`);
+        console.error('You can manually download from:');
+        console.error(`  https://github.com/${GITHUB_REPO}/releases`);
+        process.exit(0); // Don't fail the install
+    }
+}
+
+main().catch((err) => {
+    console.error('Installation error:', err.message);
+    process.exit(0); // Don't fail the install
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@emplyx/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server for Emplyx HR Platform - Access 346+ HR management tools via Model Context Protocol",
+  "bin": {
+    "emplyx-mcp": "./bin/emplyx-mcp"
+  },
+  "scripts": {
+    "postinstall": "node lib/postinstall.js || true"
+  },
+  "keywords": [
+    "mcp",
+    "emplyx",
+    "hr",
+    "human-resources",
+    "claude",
+    "anthropic",
+    "ai",
+    "model-context-protocol"
+  ],
+  "author": "Emplyx <dev@emplyx.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ezemiz/emplyx"
+  },
+  "homepage": "https://emplyx.com",
+  "bugs": {
+    "url": "https://github.com/ezemiz/emplyx/issues"
+  }
+}