eassist-mcp 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# eassist-mcp
+
+MCP server for [EAssist](https://eassist.forsysinc.com) — query and manage actions & initiatives via Claude.
+
+## Setup
+
+Add to your Claude config (`claude_desktop_config.json` or MCP settings):
+
+```json
+{
+  "mcpServers": {
+    "eassist": {
+      "command": "npx",
+      "args": ["-y", "eassist-mcp"],
+      "env": {
+        "EASSIST_API_URL": "https://eassist.forsysinc.com"
+      }
+    }
+  }
+}
+```
+
+**That's it.** On first use, a browser window opens for Google login. Tokens are stored at `~/.eassist-mcp/auth.json` and refreshed automatically — you'll only ever log in once.
+
+## What you can do
+
+Just talk to Claude naturally:
+
+- *"What are the overdue actions?"*
+- *"What is Srini working on?"*
+- *"Create an action: Review Q2 budget, assign to Arpit, due June 15"*
+- *"Mark action abc123 as complete"*
+- *"Give me the executive summary"*
+- *"Show me all actions in the JananiMitra initiative"*
+- *"List all members"*
+
+## Available Tools (20)
+
+### Read / Reporting
+| Tool | Description |
+|------|-------------|
+| `get_overdue_actions` | All overdue actions across the org |
+| `get_user_actions` | Actions assigned to a specific person |
+| `get_executive_summary` | Full ELT dashboard — workload, risks, stale actions |
+| `get_executive_brief` | Short executive brief |
+| `search_actions` | Keyword search across all actions |
+| `get_action_detail` | Full detail + comments for one action |
+| `list_initiatives` | All initiatives with status and progress |
+| `get_initiative_report` | Initiative detail + all its actions |
+| `list_members` | All members across all initiatives |
+
+### Create / Update / Delete
+| Tool | Description |
+|------|-------------|
+| `create_action` | Create a new action (optional: link to initiative) |
+| `update_action` | Update title, status, priority, due date, assignees |
+| `complete_action` | Mark an action as completed |
+| `assign_action` | Assign/reassign an action |
+| `delete_action` | Delete an action permanently |
+| `bulk_update_actions` | Update multiple actions at once |
+| `add_comment` | Add a comment/update to an action |
+| `create_initiative` | Create a new initiative |
+
+### Auth / Utility
+| Tool | Description |
+|------|-------------|
+| `whoami` | Show logged-in user and API URL |
+| `logout` | Clear stored tokens (triggers re-login on next call) |
+| `refresh_cache` | Force fresh fetch of members and initiatives |
+
+## Auth details
+
+- Tokens stored at: `~/.eassist-mcp/auth.json`
+- Access token: 7-day JWT, auto-refreshed silently
+- Refresh token: 30-day, rotated on each refresh
+- If both expire: browser re-opens automatically
+
+## Requirements
+
+- Node.js 18+
+- Access to [eassist.forsysinc.com](https://eassist.forsysinc.com)

package/build/auth.d.ts

@@ -0,0 +1,14 @@
+declare class AuthManager {
+    private data;
+    private load;
+    private store;
+    private isExpired;
+    private getApiUrl;
+    getValidToken(): Promise<string>;
+    triggerOAuthFlow(): Promise<void>;
+    private findFreePort;
+    getStoredName(): string;
+    clearTokens(): void;
+}
+export declare const auth: AuthManager;
+export {};

package/build/auth.js

@@ -0,0 +1,138 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import http from 'http';
+import { URL } from 'url';
+import axios from 'axios';
+const CONFIG_DIR = path.join(os.homedir(), '.eassist-mcp');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'auth.json');
+class AuthManager {
+    data = null;
+    load() {
+        try {
+            if (!fs.existsSync(CONFIG_FILE))
+                return null;
+            return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    store(data) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2), 'utf-8');
+        this.data = data;
+    }
+    isExpired(expiresAt) {
+        // Add 60s buffer so we refresh before actual expiry
+        return new Date(expiresAt).getTime() - 60_000 < Date.now();
+    }
+    getApiUrl() {
+        const url = process.env.EASSIST_API_URL ?? this.data?.apiUrl;
+        if (!url)
+            throw new Error('EASSIST_API_URL environment variable is required');
+        return url.replace(/\/$/, '');
+    }
+    async getValidToken() {
+        if (!this.data)
+            this.data = this.load();
+        // Valid access token
+        if (this.data?.accessToken && !this.isExpired(this.data.expiresAt)) {
+            return this.data.accessToken;
+        }
+        // Try refresh
+        if (this.data?.refreshToken) {
+            try {
+                const apiUrl = this.getApiUrl();
+                const res = await axios.post(`${apiUrl}/auth/refresh`, { refreshToken: this.data.refreshToken });
+                const { token, refreshToken, expiresAt } = res.data;
+                this.store({ ...this.data, accessToken: token, refreshToken, expiresAt });
+                return token;
+            }
+            catch {
+                // Refresh failed — fall through to OAuth
+            }
+        }
+        // Full OAuth flow
+        await this.triggerOAuthFlow();
+        return this.data.accessToken;
+    }
+    async triggerOAuthFlow() {
+        const apiUrl = this.getApiUrl();
+        const port = await this.findFreePort();
+        return new Promise((resolve, reject) => {
+            const server = http.createServer((req, res) => {
+                try {
+                    const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+                    if (url.pathname !== '/callback') {
+                        res.end();
+                        return;
+                    }
+                    const token = url.searchParams.get('token');
+                    const refreshToken = url.searchParams.get('refreshToken');
+                    const expiresAt = url.searchParams.get('expiresAt');
+                    const name = url.searchParams.get('name') ?? undefined;
+                    const email = url.searchParams.get('email') ?? undefined;
+                    if (!token || !refreshToken || !expiresAt) {
+                        res.end('Missing auth params');
+                        reject(new Error('OAuth callback missing params'));
+                        server.close();
+                        return;
+                    }
+                    this.store({ apiUrl, accessToken: token, refreshToken, expiresAt, name, email });
+                    res.writeHead(200, { 'Content-Type': 'text/plain' });
+                    res.end('OK');
+                    server.close();
+                    resolve();
+                }
+                catch (err) {
+                    server.close();
+                    reject(err);
+                }
+            });
+            server.listen(port, '127.0.0.1', async () => {
+                const authUrl = `${apiUrl}/auth/mcp?port=${port}`;
+                console.error(`\n[eassist-mcp] Opening browser for authentication...\n${authUrl}\n`);
+                try {
+                    const { default: open } = await import('open');
+                    await open(authUrl);
+                }
+                catch {
+                    console.error('[eassist-mcp] Could not open browser automatically. Please open the URL above manually.');
+                }
+            });
+            server.on('error', reject);
+            // Timeout after 5 minutes
+            setTimeout(() => {
+                server.close();
+                reject(new Error('Authentication timed out. Please try again.'));
+            }, 5 * 60 * 1000);
+        });
+    }
+    findFreePort() {
+        return new Promise((resolve, reject) => {
+            const server = http.createServer();
+            server.listen(0, '127.0.0.1', () => {
+                const addr = server.address();
+                server.close(() => {
+                    if (addr && typeof addr === 'object')
+                        resolve(addr.port);
+                    else
+                        reject(new Error('Could not find free port'));
+                });
+            });
+        });
+    }
+    getStoredName() {
+        return this.data?.name ?? this.data?.email ?? 'Unknown';
+    }
+    clearTokens() {
+        try {
+            if (fs.existsSync(CONFIG_FILE))
+                fs.unlinkSync(CONFIG_FILE);
+        }
+        catch { /* ignore */ }
+        this.data = null;
+    }
+}
+export const auth = new AuthManager();

package/build/client.d.ts

@@ -0,0 +1,4 @@
+export declare function apiGet<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+export declare function apiPost<T>(path: string, body?: unknown): Promise<T>;
+export declare function apiPatch<T>(path: string, body?: unknown): Promise<T>;
+export declare function apiDelete<T>(path: string, data?: unknown): Promise<T>;

package/build/client.js

@@ -0,0 +1,28 @@
+import axios from 'axios';
+import { auth } from './auth.js';
+function getApiUrl() {
+    const url = process.env.EASSIST_API_URL;
+    if (!url)
+        throw new Error('EASSIST_API_URL environment variable is required');
+    return url.replace(/\/$/, '');
+}
+async function headers() {
+    const token = await auth.getValidToken();
+    return { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
+}
+export async function apiGet(path, params) {
+    const res = await axios.get(`${getApiUrl()}${path}`, { headers: await headers(), params });
+    return res.data;
+}
+export async function apiPost(path, body) {
+    const res = await axios.post(`${getApiUrl()}${path}`, body, { headers: await headers() });
+    return res.data;
+}
+export async function apiPatch(path, body) {
+    const res = await axios.patch(`${getApiUrl()}${path}`, body, { headers: await headers() });
+    return res.data;
+}
+export async function apiDelete(path, data) {
+    const res = await axios.delete(`${getApiUrl()}${path}`, { headers: await headers(), data });
+    return res.data;
+}

package/build/format.d.ts

@@ -0,0 +1,7 @@
+import type { Action, Initiative } from './types.js';
+export declare function fmtDate(iso: string | null | undefined): string;
+export declare function daysOverdue(dueDate: string | null): number;
+export declare function daysUntil(dueDate: string | null): string;
+export declare function fmtAction(a: Action, idx?: number): string;
+export declare function fmtActionTable(actions: Action[], extraCol?: (a: Action) => string, extraHeader?: string): string;
+export declare function fmtInitiativeTable(initiatives: Initiative[]): string;

package/build/format.js

@@ -0,0 +1,51 @@
+export function fmtDate(iso) {
+    if (!iso)
+        return '—';
+    return new Date(iso).toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: '2-digit' });
+}
+export function daysOverdue(dueDate) {
+    if (!dueDate)
+        return 0;
+    return Math.max(0, Math.floor((Date.now() - new Date(dueDate).getTime()) / 86_400_000));
+}
+export function daysUntil(dueDate) {
+    if (!dueDate)
+        return '—';
+    const d = Math.floor((new Date(dueDate).getTime() - Date.now()) / 86_400_000);
+    if (d < 0)
+        return `${Math.abs(d)}d overdue`;
+    if (d === 0)
+        return 'today';
+    return `in ${d}d`;
+}
+export function fmtAction(a, idx) {
+    const num = idx != null ? `${idx + 1}. ` : '';
+    const assignees = a.assignees.map(u => u.name).join(', ') || 'Unassigned';
+    const due = a.dueDate ? ` | Due: ${fmtDate(a.dueDate)} (${daysUntil(a.dueDate)})` : '';
+    const init = a.initiative ? ` | ${a.initiative.title}` : '';
+    return `${num}**${a.title}**\n   Status: ${a.status} | Priority: ${a.priority} | Assignee: ${assignees}${due}${init}`;
+}
+export function fmtActionTable(actions, extraCol, extraHeader) {
+    if (actions.length === 0)
+        return '_No actions found._';
+    const header = `| # | Title | Initiative | Assignee | Priority | Due | Status${extraHeader ? ` | ${extraHeader}` : ''} |`;
+    const sep = `|---|-------|-----------|----------|----------|-----|--------${extraHeader ? '|------' : ''}|`;
+    const rows = actions.map((a, i) => {
+        const assignee = a.assignees.map(u => u.name).join(', ') || 'Unassigned';
+        const init = a.initiative?.title ?? 'Standalone';
+        const extra = extraCol ? ` | ${extraCol(a)}` : '';
+        return `| ${i + 1} | ${a.title} | ${init} | ${assignee} | ${a.priority} | ${fmtDate(a.dueDate)} | ${a.status}${extra} |`;
+    });
+    return [header, sep, ...rows].join('\n');
+}
+export function fmtInitiativeTable(initiatives) {
+    if (initiatives.length === 0)
+        return '_No initiatives found._';
+    const header = '| # | Title | Status | Priority | Progress | Actions | Due |';
+    const sep = '|---|-------|--------|----------|----------|---------|-----|';
+    const rows = initiatives.map((i, idx) => {
+        const count = i._count?.actions ?? '?';
+        return `| ${idx + 1} | ${i.title} | ${i.status} | ${i.priority} | ${i.progress}% | ${count} | ${fmtDate(i.dueDate)} |`;
+    });
+    return [header, sep, ...rows].join('\n');
+}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { auth } from './auth.js';
+import { reportingToolSchemas, handleReportingTool } from './tools/reporting.js';
+import { actionToolSchemas, handleActionTool } from './tools/actions.js';
+import { initiativeToolSchemas, handleInitiativeTool } from './tools/initiatives.js';
+import { clearCache } from './resolve.js';
+const server = new McpServer({
+    name: 'eassist-mcp',
+    version: '1.0.0',
+});
+const allTools = [
+    ...reportingToolSchemas,
+    ...actionToolSchemas,
+    ...initiativeToolSchemas,
+    {
+        name: 'whoami',
+        description: 'Returns the currently authenticated user and the API URL in use.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'logout',
+        description: 'Log out of EAssist — clears stored tokens. Next tool call will prompt for login again.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'refresh_cache',
+        description: 'Clear the in-memory member and initiative cache so the next lookup fetches fresh data.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+];
+function buildZodShape(schema) {
+    const shape = {};
+    if (!schema.properties)
+        return shape;
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        if (prop.enum) {
+            shape[key] = z.enum(prop.enum).optional();
+        }
+        else if (prop.type === 'number') {
+            shape[key] = z.number().optional();
+        }
+        else if (prop.type === 'array') {
+            shape[key] = z.array(z.string()).optional();
+        }
+        else {
+            shape[key] = z.string().optional();
+        }
+    }
+    return shape;
+}
+const reportingNames = new Set(reportingToolSchemas.map(t => t.name));
+const actionNames = new Set(actionToolSchemas.map(t => t.name));
+const initiativeNames = new Set(initiativeToolSchemas.map(t => t.name));
+for (const tool of allTools) {
+    const zodShape = buildZodShape(tool.inputSchema);
+    server.tool(tool.name, tool.description, zodShape, async (args) => {
+        try {
+            const rawArgs = args;
+            let text;
+            if (reportingNames.has(tool.name)) {
+                text = await handleReportingTool(tool.name, rawArgs);
+            }
+            else if (actionNames.has(tool.name)) {
+                text = await handleActionTool(tool.name, rawArgs);
+            }
+            else if (initiativeNames.has(tool.name)) {
+                text = await handleInitiativeTool(tool.name, rawArgs);
+            }
+            else if (tool.name === 'whoami') {
+                const name = auth.getStoredName();
+                const apiUrl = process.env.EASSIST_API_URL ?? 'not set';
+                text = `**Logged in as:** ${name}\n**API:** ${apiUrl}`;
+            }
+            else if (tool.name === 'logout') {
+                auth.clearTokens();
+                text = 'Logged out. Stored tokens cleared. Next tool call will prompt for login.';
+            }
+            else if (tool.name === 'refresh_cache') {
+                clearCache();
+                text = 'Cache cleared.';
+            }
+            else {
+                text = `Unknown tool: ${tool.name}`;
+            }
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[eassist-mcp] Server started. Waiting for requests...');
+}
+main().catch(err => {
+    console.error('[eassist-mcp] Fatal error:', err);
+    process.exit(1);
+});

package/build/resolve.d.ts

@@ -0,0 +1,14 @@
+export declare function fuzzyMatch(query: string, name: string): boolean;
+export declare function resolveUser(name: string): Promise<{
+    id: string;
+    name: string;
+} | {
+    error: string;
+}>;
+export declare function resolveInitiative(name: string): Promise<{
+    id: string;
+    title: string;
+} | {
+    error: string;
+}>;
+export declare function clearCache(): void;

package/build/resolve.js

@@ -0,0 +1,61 @@
+import { apiGet } from './client.js';
+// Cache members for the session to avoid repeated API calls
+let memberCache = null;
+let initiativeCache = null;
+async function getMembers() {
+    if (memberCache)
+        return memberCache;
+    const data = await apiGet('/initiatives');
+    const seen = new Set();
+    const members = [];
+    for (const init of data.initiatives) {
+        try {
+            const m = await apiGet(`/initiatives/${init.id}/members`);
+            for (const member of m.members) {
+                if (!seen.has(member.user.id)) {
+                    seen.add(member.user.id);
+                    members.push({ id: member.user.id, name: member.user.name, email: member.user.email });
+                }
+            }
+        }
+        catch { /* skip inaccessible */ }
+    }
+    memberCache = members;
+    return members;
+}
+async function getInitiatives() {
+    if (initiativeCache)
+        return initiativeCache;
+    const data = await apiGet('/initiatives');
+    initiativeCache = data.initiatives.map(i => ({ id: i.id, title: i.title }));
+    return initiativeCache;
+}
+export function fuzzyMatch(query, name) {
+    const q = query.toLowerCase();
+    const n = name.toLowerCase();
+    return n.includes(q) || q.includes(n);
+}
+export async function resolveUser(name) {
+    const members = await getMembers();
+    const matches = members.filter(m => fuzzyMatch(name, m.name) || fuzzyMatch(name, m.email));
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0)
+        return { error: `No user found matching "${name}". Use list_members to see available users.` };
+    return { error: `Multiple users match "${name}": ${matches.map(m => m.name).join(', ')}. Please be more specific.` };
+}
+export async function resolveInitiative(name) {
+    const inits = await getInitiatives();
+    const matches = inits.filter(i => fuzzyMatch(name, i.title));
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0)
+        return { error: `No initiative found matching "${name}". Use list_initiatives to see available initiatives.` };
+    if (matches.length <= 5)
+        return { error: `Multiple initiatives match "${name}": ${matches.map(i => i.title).join(', ')}. Please be more specific.` };
+    return { error: `Too many initiatives match "${name}". Please be more specific.` };
+}
+export function clearCache() {
+    memberCache = null;
+    initiativeCache = null;
+}