@beaconcue/mcp 1.0.0

package/dist/index.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * BeaconCue MCP Server
+ *
+ * Environment variables:
+ *   BEACONCUE_API_KEY       — your bck_... API key (from Settings → API Keys)
+ *   BEACONCUE_BASE_URL      — optional, defaults to https://beaconcue.com
+ *
+ * Usage (stdio transport — for Claude Desktop):
+ *   node dist/index.js
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const API_KEY = process.env.BEACONCUE_API_KEY;
+const BASE_URL = (process.env.BEACONCUE_BASE_URL || 'https://beaconcue.com').replace(/\/$/, '');
+if (!API_KEY) {
+    console.error('BEACONCUE_API_KEY environment variable is required');
+    process.exit(1);
+}
+async function api(path, options = {}) {
+    const url = `${BASE_URL}/api/mcp${path}`;
+    const res = await fetch(url, {
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${API_KEY}`,
+            ...(options.headers ?? {}),
+        },
+    });
+    const json = await res.json();
+    if (!res.ok)
+        throw new Error(json.error || `API error ${res.status}`);
+    return json;
+}
+const server = new McpServer({
+    name: 'beaconcue',
+    version: '1.0.0',
+});
+// ── Employees ─────────────────────────────────────────────────────────────────
+server.tool('list_employees', 'List all employees in the BeaconCue workspace', {}, async () => {
+    const data = await api('/employees');
+    return { content: [{ type: 'text', text: JSON.stringify(data.employees, null, 2) }] };
+});
+server.tool('add_employee', 'Add a new employee to the workspace', {
+    name: z.string().describe('Full name'),
+    email: z.string().email().describe('Work email'),
+    role: z.string().optional().describe('Job title e.g. "Backend Engineer"'),
+    department: z.string().optional().describe('Department e.g. "Engineering"'),
+    location: z.string().optional().describe('Office location name'),
+    joining_date: z.string().optional().describe('ISO date e.g. 2026-07-01'),
+    manager_id: z.string().optional().describe('Employee ID of direct manager'),
+}, async (args) => {
+    const data = await api('/employees', {
+        method: 'POST',
+        body: JSON.stringify(args),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data.employee, null, 2) }] };
+});
+server.tool('update_employee', 'Update an existing employee record', {
+    id: z.string().describe('Employee ID'),
+    name: z.string().optional(),
+    role: z.string().optional().describe('Job title'),
+    department: z.string().optional(),
+    location: z.string().optional(),
+    status: z.enum(['active', 'suspended']).optional(),
+    joining_date: z.string().optional(),
+    manager_id: z.string().nullable().optional(),
+}, async (args) => {
+    const data = await api('/employees', {
+        method: 'PATCH',
+        body: JSON.stringify(args),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data.employee, null, 2) }] };
+});
+// ── Tickets ───────────────────────────────────────────────────────────────────
+server.tool('list_tickets', 'List tickets in the workspace. Filter by status, assigneeId, or releaseId.', {
+    status: z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done']).optional(),
+    assigneeId: z.string().optional().describe('Employee ID to filter by assignee'),
+    releaseId: z.string().optional().describe('Release ID to filter by release'),
+}, async (args) => {
+    const params = new URLSearchParams();
+    if (args.status)
+        params.set('status', args.status);
+    if (args.assigneeId)
+        params.set('assigneeId', args.assigneeId);
+    if (args.releaseId)
+        params.set('releaseId', args.releaseId);
+    const data = await api(`/tickets?${params}`);
+    return { content: [{ type: 'text', text: JSON.stringify(data.tickets, null, 2) }] };
+});
+server.tool('create_ticket', 'Create a new ticket', {
+    title: z.string().describe('Ticket title'),
+    status: z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done']).optional(),
+    priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+    ticket_type: z.enum(['story', 'feature', 'bug', 'customer_request']).optional(),
+    assignee_id: z.string().optional().describe('Employee ID'),
+    story_points: z.number().optional(),
+    release_id: z.string().optional(),
+    description: z.string().optional(),
+}, async (args) => {
+    const data = await api('/tickets', {
+        method: 'POST',
+        body: JSON.stringify(args),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data.ticket, null, 2) }] };
+});
+server.tool('update_ticket', 'Update a ticket (status, priority, assignee, etc.)', {
+    id: z.string().describe('Ticket ID'),
+    title: z.string().optional(),
+    status: z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done']).optional(),
+    priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+    ticket_type: z.enum(['story', 'feature', 'bug', 'customer_request']).optional(),
+    assignee_id: z.string().nullable().optional(),
+    story_points: z.number().nullable().optional(),
+    release_id: z.string().nullable().optional(),
+}, async (args) => {
+    const data = await api('/tickets', {
+        method: 'PATCH',
+        body: JSON.stringify(args),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data.ticket, null, 2) }] };
+});
+// ── OKRs ──────────────────────────────────────────────────────────────────────
+server.tool('list_okrs', 'List all objectives and key results in the workspace', {}, async () => {
+    const data = await api('/okrs');
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ objectives: data.objectives, keyResults: data.keyResults }, null, 2),
+            }],
+    };
+});
+server.tool('update_kr_progress', 'Update the current value (progress) of a key result', {
+    id: z.string().describe('Key Result ID'),
+    current_value: z.number().describe('New current value'),
+}, async (args) => {
+    const data = await api('/okrs', {
+        method: 'PATCH',
+        body: JSON.stringify(args),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data.keyResult, null, 2) }] };
+});
+// ── Releases ──────────────────────────────────────────────────────────────────
+server.tool('list_releases', 'List all releases in the workspace', {}, async () => {
+    const data = await api('/releases');
+    return { content: [{ type: 'text', text: JSON.stringify(data.releases, null, 2) }] };
+});
+// ── Members ───────────────────────────────────────────────────────────────────
+server.tool('list_members', 'List workspace members with their system roles', {}, async () => {
+    const data = await api('/members');
+    return { content: [{ type: 'text', text: JSON.stringify(data.members, null, 2) }] };
+});
+// ── Recognition ───────────────────────────────────────────────────────────────
+server.tool('list_recognitions', 'List recent recognitions (shout-outs)', {
+    limit: z.number().optional().describe('Max results, default 20'),
+}, async (args) => {
+    const params = new URLSearchParams();
+    if (args.limit)
+        params.set('limit', String(args.limit));
+    const data = await api(`/recognition?${params}`);
+    return { content: [{ type: 'text', text: JSON.stringify(data.recognitions, null, 2) }] };
+});
+server.tool('send_recognition', 'Send a recognition (ecard) from one employee to another', {
+    from_employee_id: z.string().describe('Employee ID of the sender'),
+    to_employee_id: z.string().describe('Employee ID of the recipient'),
+    ecard_type: z.enum(['above_beyond', 'savior', 'fixer', 'team_player', 'achiever']),
+    message: z.string().optional().describe('Personal message'),
+}, async (args) => {
+    const data = await api('/recognition', {
+        method: 'POST',
+        body: JSON.stringify(args),
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(data.recognition, null, 2) }] };
+});
+// ── Time off ──────────────────────────────────────────────────────────────────
+server.tool('list_timeoff', 'List leave/time-off requests', {
+    employeeId: z.string().optional().describe('Filter by employee ID'),
+    status: z.enum(['pending', 'approved', 'rejected', 'cancelled']).optional(),
+    year: z.string().optional().describe('4-digit year e.g. "2026"'),
+}, async (args) => {
+    const params = new URLSearchParams();
+    if (args.employeeId)
+        params.set('employeeId', args.employeeId);
+    if (args.status)
+        params.set('status', args.status);
+    if (args.year)
+        params.set('year', args.year);
+    const data = await api(`/timeoff?${params}`);
+    return { content: [{ type: 'text', text: JSON.stringify(data.leaves, null, 2) }] };
+});
+// ── Start server ──────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@beaconcue/mcp",
+  "version": "1.0.0",
+  "description": "BeaconCue MCP server — control your BeaconCue workspace from Claude",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "beaconcue-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "beaconcue",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "work-management",
+    "hr",
+    "okr"
+  ],
+  "author": "BeaconCue",
+  "license": "MIT",
+  "homepage": "https://beaconcue.com",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}