standup-mcp 0.1.0

package/dist/sources/slack.js

@@ -0,0 +1,185 @@
+/**
+ * Live Slack source. Implements ActivitySource against the Slack Web API
+ * (https://slack.com/api) using a bearer token. Read-only: it only reads the
+ * user's own messages to build "message" activity events.
+ *
+ * Slack returns HTTP 200 with { ok: false, error } on logical failure, so a
+ * successful HTTP status is not enough. Only checkConnection surfaces failure;
+ * fetchActivity degrades to [] because Slack token scopes vary widely (a bot
+ * token cannot use search.messages, a user token may lack channel access, etc).
+ */
+import { detectTextSignals, extractWorkItemKey, truncate } from "../normalize.js";
+const API_BASE = "https://slack.com/api";
+const REQUEST_TIMEOUT_MS = 30_000;
+export class SlackSource {
+    creds;
+    id = "slack";
+    isDemo = false;
+    constructor(creds) {
+        this.creds = creds;
+    }
+    // --- HTTP plumbing -------------------------------------------------------
+    /**
+     * GET a Web API method and parse JSON. Throws on transport failure, timeout,
+     * or a logical Slack error ({ ok: false }). Callers that must not fail wrap
+     * this in their own try/catch.
+     */
+    async call(method, params = {}) {
+        const query = new URLSearchParams(params).toString();
+        const url = `${API_BASE}/${method}${query ? `?${query}` : ""}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const res = await fetch(url, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${this.creds.token}`,
+                    Accept: "application/json",
+                },
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                throw new Error(`Slack API ${res.status} ${res.statusText} for ${method}`);
+            }
+            const data = (await res.json());
+            if (!data.ok) {
+                throw new Error(data.error ?? "unknown_error");
+            }
+            return data;
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new Error(`Slack API request timed out after 30s: ${method}`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // --- ActivitySource surface ----------------------------------------------
+    async resolveIdentity() {
+        try {
+            const data = await this.call("auth.test");
+            return data.user_id;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async checkConnection() {
+        try {
+            const data = await this.call("auth.test");
+            return {
+                source: "slack",
+                ok: data.ok === true,
+                identity: data.user_id,
+                detail: `authenticated as ${data.user} in ${data.team}`,
+            };
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return {
+                source: "slack",
+                ok: false,
+                detail: `Slack error: ${reason}`,
+            };
+        }
+    }
+    /**
+     * The user's own messages in the window, as "message" events. Never throws:
+     * tries search.messages first, falls back to scanning configured channels via
+     * conversations.history, and returns [] if both yield nothing or fail.
+     */
+    async fetchActivity(window, actor) {
+        try {
+            const userId = actor.slack ?? (await this.resolveIdentity());
+            if (!userId)
+                return [];
+            // Strategy 1: search.messages. Needs a user token with search:read.
+            try {
+                const events = await this.searchMessages(userId, window);
+                // Empty matches is a valid result, not a failure: do not fall through.
+                return events;
+            }
+            catch {
+                // Fall through to channel scanning below.
+            }
+            // Strategy 2: conversations.history per configured channel.
+            if (this.creds.channels?.length) {
+                return await this.scanChannels(userId, window);
+            }
+            return [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Slack has no work items, so nothing implies upcoming work here. */
+    async fetchOpenItems(_actor) {
+        return [];
+    }
+    // --- Strategies ----------------------------------------------------------
+    async searchMessages(userId, window) {
+        const dayBefore = new Date(Date.parse(window.since) - 86_400_000)
+            .toISOString()
+            .slice(0, 10);
+        const data = await this.call("search.messages", {
+            query: `from:<@${userId}> after:${dayBefore}`,
+            count: "100",
+        });
+        const matches = data.messages?.matches ?? [];
+        return matches
+            .map((m) => this.toEvent(m, userId, m.channel?.name))
+            .filter((e) => e !== null && this.inWindow(e, window));
+    }
+    async scanChannels(userId, window) {
+        const oldest = String(Math.floor(Date.parse(window.since) / 1000));
+        const out = [];
+        for (const channelId of this.creds.channels ?? []) {
+            try {
+                const data = await this.call("conversations.history", {
+                    channel: channelId,
+                    oldest,
+                    limit: "100",
+                });
+                for (const msg of data.messages ?? []) {
+                    if (msg.user !== userId)
+                        continue;
+                    // conversations.history returns only the channel id, no name.
+                    const event = this.toEvent(msg, userId, channelId);
+                    if (event && this.inWindow(event, window))
+                        out.push(event);
+                }
+            }
+            catch {
+                // A single channel can fail (not_in_channel, etc); skip it and continue.
+                continue;
+            }
+        }
+        return out;
+    }
+    // --- Mapping -------------------------------------------------------------
+    /** Map a raw Slack message to a normalized "message" event, or null if empty. */
+    toEvent(msg, userId, channelName) {
+        if (!msg.ts)
+            return null;
+        const text = msg.text ?? "";
+        const timestamp = new Date(Math.floor(Number(msg.ts)) * 1000).toISOString();
+        return {
+            source: "slack",
+            kind: "message",
+            timestamp,
+            actor: userId,
+            title: `#${channelName ?? "dm"}: ${truncate(text, 80)}`,
+            body: text,
+            workItem: extractWorkItemKey(text),
+            signals: detectTextSignals(text),
+            ...(msg.permalink ? { url: msg.permalink } : {}),
+        };
+    }
+    /** Keep only messages at or after the window start (spec filters on `since` only). */
+    inWindow(event, window) {
+        return Date.parse(event.timestamp) >= Date.parse(window.since);
+    }
+}

package/dist/tools/blockers.js

@@ -0,0 +1,20 @@
+import { detectBlockers, formatBlockerReport } from "../analytics/blockers.js";
+import { resolveWindow } from "../window.js";
+import { handle, windowArgs } from "./util.js";
+export function registerBlockerScan(server, deps) {
+    server.registerTool("blocker_scan", {
+        title: "Blocker Scan",
+        description: "Surface what is blocking you across GitHub, Jira, Linear, and Slack, ranked by severity. Detects blockers from signals, not self-report: explicit 'blocked / waiting on / stuck' language, PRs awaiting review, in-progress tickets that have not moved, and requests for help.",
+        inputSchema: { ...windowArgs },
+    }, async ({ since, days }) => handle(async () => {
+        const now = new Date();
+        const window = resolveWindow({ since, days }, now);
+        const actor = await deps.provider.resolveActor();
+        const [events, openItems] = await Promise.all([
+            deps.provider.fetchActivity(window, actor),
+            deps.provider.fetchOpenItems(actor),
+        ]);
+        const blockers = detectBlockers(events, openItems, now.toISOString());
+        return formatBlockerReport(blockers, window, deps.provider.isDemo);
+    }));
+}

package/dist/tools/digest.js

@@ -0,0 +1,16 @@
+import { buildDigest } from "../analytics/digest.js";
+import { resolveWindow } from "../window.js";
+import { handle, windowArgs } from "./util.js";
+export function registerActivityDigest(server, deps) {
+    server.registerTool("activity_digest", {
+        title: "Activity Digest",
+        description: "A chronological digest of everything you did in a window across the configured tools, newest first, grouped by day. Use it to reconstruct what actually happened, separate from the opinionated standup framing.",
+        inputSchema: { ...windowArgs },
+    }, async ({ since, days }) => handle(async () => {
+        const now = new Date();
+        const window = resolveWindow({ since, days }, now);
+        const actor = await deps.provider.resolveActor();
+        const events = await deps.provider.fetchActivity(window, actor);
+        return buildDigest(events, window, deps.provider.isDemo);
+    }));
+}

package/dist/tools/registry.js

@@ -0,0 +1,13 @@
+import { registerStandupDraft } from "./standup.js";
+import { registerBlockerScan } from "./blockers.js";
+import { registerWeeklySummary } from "./weekly.js";
+import { registerActivityDigest } from "./digest.js";
+import { registerListSources } from "./sources.js";
+/** Wire every tool onto the server. One place to see the full tool surface. */
+export function registerAllTools(server, deps) {
+    registerStandupDraft(server, deps);
+    registerBlockerScan(server, deps);
+    registerWeeklySummary(server, deps);
+    registerActivityDigest(server, deps);
+    registerListSources(server, deps);
+}

package/dist/tools/sources.js

@@ -0,0 +1,29 @@
+import { sourceLabel } from "../format.js";
+import { handle } from "./util.js";
+export function registerListSources(server, deps) {
+    server.registerTool("list_sources", {
+        title: "List Sources",
+        description: "Show which activity sources (GitHub, Jira, Linear, Slack) are configured, or that the server is running on demo data. Does not hit the network; run the server with --check to verify live connections.",
+        inputSchema: {},
+    }, async () => handle(async () => {
+        const p = deps.provider;
+        if (p.isDemo) {
+            return [
+                "Running in **demo mode** (synthetic data, no credentials configured).",
+                "",
+                "To use your real activity, set any of these and restart:",
+                "- GitHub: GITHUB_TOKEN",
+                "- Jira: JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN",
+                "- Linear: LINEAR_API_KEY",
+                "- Slack: SLACK_TOKEN",
+                "",
+                "Then run `standup-mcp --check` to verify each connection.",
+            ].join("\n");
+        }
+        const lines = ["**Configured sources:**", ""];
+        for (const s of p.sources)
+            lines.push(`- ${sourceLabel(s)}`);
+        lines.push("", "Run `standup-mcp --check` to verify each connection live.");
+        return lines.join("\n");
+    }));
+}

package/dist/tools/standup.js

@@ -0,0 +1,26 @@
+import { buildStandupDraft } from "../analytics/draft.js";
+import { resolveWindow } from "../window.js";
+import { handle, windowArgs } from "./util.js";
+export function registerStandupDraft(server, deps) {
+    server.registerTool("standup_draft", {
+        title: "Standup Draft",
+        description: "Generate your daily standup, what should I say at standup today, from your real activity across the configured tools (GitHub, Jira, Linear, Slack). Returns Yesterday / Today / Blockers grouped by work item, not by tool, in concrete deltas. Defaults to the last working day (Monday reaches back across the weekend). Only reports observed activity; never invents work.",
+        inputSchema: { ...windowArgs },
+    }, async ({ since, days }) => handle(async () => {
+        const now = new Date();
+        const window = resolveWindow({ since, days }, now);
+        const actor = await deps.provider.resolveActor();
+        const [events, openItems] = await Promise.all([
+            deps.provider.fetchActivity(window, actor),
+            deps.provider.fetchOpenItems(actor),
+        ]);
+        return buildStandupDraft({
+            actor,
+            window,
+            events,
+            openItems,
+            nowIso: now.toISOString(),
+            isDemo: deps.provider.isDemo,
+        });
+    }));
+}

package/dist/tools/util.js

@@ -0,0 +1,35 @@
+/**
+ * Shared helpers for tool handlers: dependency injection, consistent result
+ * shaping, friendly error handling, and the window-selection input schema every
+ * activity tool accepts.
+ */
+import { z } from "zod";
+export function text(s) {
+    return { content: [{ type: "text", text: s }] };
+}
+/** Run a handler, turning any thrown error into a clean tool error result. */
+export async function handle(fn) {
+    try {
+        return text(await fn());
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `⚠️ ${message}` }],
+            isError: true,
+        };
+    }
+}
+/** Input shared by the activity tools: choose the time window. */
+export const windowArgs = {
+    since: z
+        .string()
+        .optional()
+        .describe("ISO date/time start of the window, e.g. 2026-06-16. Overrides the default. Default covers the last working day (Monday reaches back to Friday)."),
+    days: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Look back this many days from now instead of the default window."),
+};

package/dist/tools/weekly.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { buildWeeklySummary } from "../analytics/weekly.js";
+import { lastNDaysWindow } from "../window.js";
+import { handle } from "./util.js";
+export function registerWeeklySummary(server, deps) {
+    server.registerTool("weekly_summary", {
+        title: "Weekly Summary",
+        description: "Roll up a week (or any N days) of your real activity into accomplishments, grouped by work item as Shipped vs In progress, with reviews and totals. For 1:1s, weekly status, and self-reviews. Only reports observed work.",
+        inputSchema: {
+            days: z
+                .number()
+                .int()
+                .min(1)
+                .max(31)
+                .optional()
+                .describe("How many days to summarize. Default 7."),
+        },
+    }, async ({ days }) => handle(async () => {
+        const now = new Date();
+        const window = lastNDaysWindow(days ?? 7, now);
+        const actor = await deps.provider.resolveActor();
+        const events = await deps.provider.fetchActivity(window, actor);
+        return buildWeeklySummary(events, window, actor, deps.provider.isDemo);
+    }));
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Normalized activity types.
+ *
+ * Everything downstream of a source (grouping, blocker detection, the standup
+ * draft) speaks these types only. Each live source client (GitHub, Jira, Linear,
+ * Slack) and the demo provider all emit ActivityEvent, so no analytics code
+ * knows or cares which tool the activity came from. That is what lets us group
+ * by work item across tools and run the whole engine on synthetic demo data.
+ */
+export const ALL_SOURCES = ["github", "jira", "linear", "slack"];

package/dist/window.js

@@ -0,0 +1,62 @@
+/**
+ * Resolve the time window a standup or digest covers.
+ *
+ * The default answers the real question, "what happened since my last
+ * standup?", which means Monday has to reach back across the weekend to Friday.
+ * Kept pure (takes `now`) so the weekend logic is unit tested.
+ *
+ * All math is in UTC for determinism. Pass an explicit `since` for a precise
+ * local window.
+ */
+import { fmtDayDate } from "./format.js";
+const DAY_MS = 86_400_000;
+function startOfUTCDay(d) {
+    return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), 0, 0, 0, 0));
+}
+/**
+ * How many days back the default window reaches, so the previous working day
+ * (and any weekend in between) is always covered.
+ *   Mon -> 3 (Fri + Sat + Sun)   Sun -> 2 (Fri + Sat)   Sat -> 1 (Fri)
+ *   Tue..Fri -> 1 (the day before)
+ */
+export function defaultLookbackDays(now) {
+    switch (now.getUTCDay()) {
+        case 1: // Monday
+            return 3;
+        case 0: // Sunday
+            return 2;
+        default:
+            return 1;
+    }
+}
+export function resolveWindow(opts, now) {
+    const until = now.toISOString();
+    let since;
+    if (opts.since) {
+        since = new Date(opts.since).toISOString();
+    }
+    else if (opts.days && opts.days > 0) {
+        since = new Date(now.getTime() - opts.days * DAY_MS).toISOString();
+    }
+    else {
+        const back = defaultLookbackDays(now);
+        since = startOfUTCDay(new Date(now.getTime() - back * DAY_MS)).toISOString();
+    }
+    return { since, until, label: `since ${fmtDayDate(since)}` };
+}
+/** A window covering the last `days` days, for weekly summaries. */
+export function lastNDaysWindow(days, now) {
+    const since = startOfUTCDay(new Date(now.getTime() - (days - 1) * DAY_MS)).toISOString();
+    return {
+        since,
+        until: now.toISOString(),
+        label: `the last ${days} days`,
+    };
+}
+/** True if an ISO timestamp falls within [since, until). */
+export function inWindow(iso, window) {
+    const t = Date.parse(iso);
+    if (Number.isNaN(t))
+        return false;
+    return t >= Date.parse(window.since) && t < Date.parse(window.until);
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "standup-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.sathvic-kollu/standup-mcp",
+  "description": "Generate your daily standup from real activity across GitHub, Jira, Linear, and Slack. An MCP server that answers \"what should I say at standup today?\" from yesterday's commits, PRs, ticket moves, and threads. Local, read-only, model-agnostic.",
+  "type": "module",
+  "bin": {
+    "standup-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "smoke": "tsx test/smoke.ts",
+    "test": "tsx test/normalize.test.ts && tsx test/draft.test.ts && npm run build && tsx test/integration.ts",
+    "inspect": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "standup",
+    "daily-standup",
+    "scrum",
+    "github",
+    "jira",
+    "linear",
+    "slack",
+    "developer-tools",
+    "claude",
+    "ai"
+  ],
+  "author": "Sathvic Kollu <sathvickollu@gmail.com> (https://sathvickollu.com)",
+  "license": "MIT",
+  "homepage": "https://github.com/sathvic-kollu/standup-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sathvic-kollu/standup-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sathvic-kollu/standup-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}