@4da/mcp-server 5.0.0 → 5.0.2

package/dist/output-manager.js

@@ -1,157 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Output Manager for Dynamic Context Discovery
- *
- * Reduces token usage by ~80% through:
- * - Writing full results to files (referenced by path)
- * - Returning compact summaries inline
- * - Providing retrieval hints for common queries
- *
- * Full results stored at: ~/.local/share/4da/context/results/
- */
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-// Base directory for 4DA context files
-const CONTEXT_DIR = join(homedir(), ".local", "share", "4da", "context");
-const RESULTS_DIR = join(CONTEXT_DIR, "results");
-/**
- * Ensure the context directories exist
- */
-function ensureDirectories() {
-    if (!existsSync(CONTEXT_DIR)) {
-        mkdirSync(CONTEXT_DIR, { recursive: true });
-    }
-    if (!existsSync(RESULTS_DIR)) {
-        mkdirSync(RESULTS_DIR, { recursive: true });
-    }
-}
-/**
- * Write full result to file and return the file path
- */
-function writeResultFile(toolName, fullResult) {
-    ensureDirectories();
-    // Generate timestamped filename
-    const timestamp = Math.floor(Date.now() / 1000);
-    const filename = `${toolName}_${timestamp}.json`;
-    const filePath = join(RESULTS_DIR, filename);
-    // Write full result to file
-    writeFileSync(filePath, JSON.stringify(fullResult, null, 2), "utf-8");
-    return filePath;
-}
-/**
- * Get the results directory path (for documentation)
- */
-export function getResultsDir() {
-    return RESULTS_DIR;
-}
-export function createDailyBriefingCompact(result) {
-    const topTheme = result.themes[0]?.name || "general";
-    return {
-        summary: `${result.summary.total_items_analyzed} items analyzed, ${result.summary.high_relevance_count} high-priority. Top theme: ${topTheme}. ${result.ai_synthesis ? "AI synthesis included." : ""}`,
-        key_data: {
-            total_items: result.summary.total_items_analyzed,
-            high_priority: result.summary.high_relevance_count,
-            top_theme: result.themes[0]?.name || "none",
-            tldr: result.summary.tldr,
-            executive_brief: result.ai_synthesis?.executive_brief,
-        },
-        full_result_path: writeResultFile("daily_briefing", result),
-        retrieval_hints: [
-            "jq '.notable_items' - get high-priority items",
-            "jq '.themes' - get topic breakdown",
-            "jq '.recommendations' - get action items",
-            "jq '.ai_synthesis.executive_brief' - get AI summary",
-        ],
-    };
-}
-export function createTrendAnalysisCompact(result) {
-    const anomalyNote = result.anomalies.length > 0 ? ` ${result.anomalies.length} anomalies detected.` : "";
-    return {
-        summary: `Volume ${result.summary.volume_trend}. Rising: ${result.summary.top_rising_topic || "none"}. Falling: ${result.summary.top_falling_topic || "none"}.${anomalyNote}`,
-        key_data: {
-            total_items: result.summary.total_items,
-            volume_trend: result.summary.volume_trend,
-            top_rising: result.summary.top_rising_topic,
-            top_falling: result.summary.top_falling_topic,
-            anomaly_count: result.anomalies.length,
-            narrative: result.ai_interpretation?.narrative,
-        },
-        full_result_path: writeResultFile("trend_analysis", result),
-        retrieval_hints: [
-            "jq '.topic_trends' - get all topic trends",
-            "jq '.volume_by_day' - get daily volume data",
-            "jq '.anomalies' - get detected anomalies",
-            "jq '.ai_interpretation.forecast' - get predictions",
-        ],
-    };
-}
-export function createScoreAutopsyCompact(result) {
-    const topComponent = result.components.sort((a, b) => b.contribution - a.contribution)[0];
-    const assessment = result.ai_analysis?.score_assessment || "unanalyzed";
-    return {
-        summary: `"${result.item.title.substring(0, 40)}..." scored ${Math.round(result.final_score * 100)}%. Assessment: ${assessment}. Top contributor: ${topComponent?.name || "unknown"}.`,
-        key_data: {
-            item_title: result.item.title,
-            final_score: result.final_score,
-            score_assessment: result.ai_analysis?.score_assessment,
-            top_contributor: topComponent?.name || "unknown",
-            verdict: result.ai_analysis?.verdict,
-        },
-        full_result_path: writeResultFile("score_autopsy", result),
-        retrieval_hints: [
-            "jq '.components' - get score breakdown",
-            "jq '.matching_context' - get what matched",
-            "jq '.similar_items' - get comparison items",
-            "jq '.recommendations' - get improvement suggestions",
-        ],
-    };
-}
-export function createContextAnalysisCompact(result) {
-    const quality = Math.round(result.quality_score.overall * 100);
-    return {
-        summary: `Context quality: ${quality}%. ${result.context_summary.interests_count} interests, ${result.context_summary.tech_stack_count} tech. ${result.coverage_gaps.length} gaps found.`,
-        key_data: {
-            quality_score: result.quality_score.overall,
-            interests_count: result.context_summary.interests_count,
-            tech_count: result.context_summary.tech_stack_count,
-            gap_count: result.coverage_gaps.length,
-            top_recommendation: result.recommendations[0]?.action || "No recommendations",
-            personalized_advice: result.ai_advice?.personalized_recommendations,
-        },
-        full_result_path: writeResultFile("context_analysis", result),
-        retrieval_hints: [
-            "jq '.quality_score.dimensions' - get quality breakdown",
-            "jq '.coverage_gaps' - get what's missing",
-            "jq '.recommendations' - get all suggestions",
-            "jq '.top_affinities' - get learned preferences",
-        ],
-    };
-}
-export function createTopicConnectionsCompact(result) {
-    const topEdge = result.edges[0];
-    const connectionNote = topEdge
-        ? `Strongest: ${topEdge.from} ↔ ${topEdge.to}.`
-        : "No strong connections.";
-    return {
-        summary: `${result.nodes.length} topics, ${result.edges.length} connections. Central: ${result.central_topics.slice(0, 3).join(", ")}. ${connectionNote}`,
-        key_data: {
-            items_analyzed: result.analysis_period.items_analyzed,
-            node_count: result.nodes.length,
-            edge_count: result.edges.length,
-            central_topics: result.central_topics.slice(0, 5),
-            top_connection: topEdge
-                ? { from: topEdge.from, to: topEdge.to, strength: topEdge.co_occurrences }
-                : null,
-            graph_narrative: result.ai_insights?.graph_narrative,
-        },
-        full_result_path: writeResultFile("topic_connections", result),
-        retrieval_hints: [
-            "jq '.nodes' - get all topic nodes",
-            "jq '.edges' - get all connections",
-            "jq '.clusters' - get topic clusters",
-            "jq '.path' - get path between topics (if requested)",
-        ],
-    };
-}
-//# sourceMappingURL=output-manager.js.map

package/dist/scheduler/core.d.ts

@@ -1,25 +0,0 @@
-/**
- * Scheduler core — the cadence engine (S1).
- *
- * A minimal, dependency-free job scheduler: register named jobs with an interval, tick them
- * manually (tests, one-shots) or let start()/stop() drive them on timers. The one hard rule:
- * the SAME job never overlaps itself — a tick that arrives while the job's fn is still
- * running resolves as a no-op instead of double-running the pull.
- */
-type JobFn = () => Promise<void>;
-export interface SchedulerJobView {
-    name: string;
-    intervalMs: number;
-    lastRun: number | null;
-}
-export interface Scheduler {
-    register(name: string, intervalMs: number, fn: JobFn): void;
-    start(): void;
-    stop(): void;
-    tick(name: string): Promise<void>;
-    jobs(): SchedulerJobView[];
-    jobCount(): number;
-}
-export declare function createScheduler(): Scheduler;
-export {};
-//# sourceMappingURL=core.d.ts.map

package/dist/scheduler/core.js

@@ -1,61 +0,0 @@
-/**
- * Scheduler core — the cadence engine (S1).
- *
- * A minimal, dependency-free job scheduler: register named jobs with an interval, tick them
- * manually (tests, one-shots) or let start()/stop() drive them on timers. The one hard rule:
- * the SAME job never overlaps itself — a tick that arrives while the job's fn is still
- * running resolves as a no-op instead of double-running the pull.
- */
-export function createScheduler() {
-    const jobs = new Map();
-    async function tick(name) {
-        const job = jobs.get(name);
-        if (!job) {
-            throw new Error(`scheduler: no job registered under "${name}"`);
-        }
-        if (job.running) {
-            return; // the same job never overlaps — a concurrent tick is a no-op
-        }
-        job.running = true;
-        try {
-            await job.fn();
-            job.lastRun = Date.now();
-        }
-        finally {
-            job.running = false;
-        }
-    }
-    return {
-        register(name, intervalMs, fn) {
-            jobs.set(name, { name, intervalMs, fn, lastRun: null, running: false, timer: null });
-        },
-        start() {
-            for (const job of jobs.values()) {
-                if (job.timer)
-                    continue;
-                job.timer = setInterval(() => {
-                    void tick(job.name).catch(() => {
-                        // a failing scheduled run must never take the process down; the job's
-                        // freshness simply doesn't advance, which is the observable signal
-                    });
-                }, job.intervalMs);
-            }
-        },
-        stop() {
-            for (const job of jobs.values()) {
-                if (job.timer) {
-                    clearInterval(job.timer);
-                    job.timer = null;
-                }
-            }
-        },
-        tick,
-        jobs() {
-            return [...jobs.values()].map(({ name, intervalMs, lastRun }) => ({ name, intervalMs, lastRun }));
-        },
-        jobCount() {
-            return jobs.size;
-        },
-    };
-}
-//# sourceMappingURL=core.js.map

package/dist/scheduler/freshness.d.ts

@@ -1,17 +0,0 @@
-/**
- * Freshness watermarks (S2) — when was each named feed last refreshed, and is it stale?
- *
- * A tiny persistent map: mark a name fresh at a moment, ask how stale it is against a budget.
- * Persistence is an explicit save()/load() to a JSON file so the scheduler can survive a
- * restart without inventing freshness it does not have — a missing file simply means
- * "nothing is known", which reads as stale (the honest default).
- */
-export interface Freshness {
-    markFresh(name: string, at?: number): void;
-    lastFresh(name: string): number | null;
-    isStale(name: string, maxAgeMs: number, now?: number): boolean;
-    save(): void;
-    load(): void;
-}
-export declare function createFreshness(filePath?: string): Freshness;
-//# sourceMappingURL=freshness.d.ts.map

package/dist/scheduler/freshness.js

@@ -1,41 +0,0 @@
-/**
- * Freshness watermarks (S2) — when was each named feed last refreshed, and is it stale?
- *
- * A tiny persistent map: mark a name fresh at a moment, ask how stale it is against a budget.
- * Persistence is an explicit save()/load() to a JSON file so the scheduler can survive a
- * restart without inventing freshness it does not have — a missing file simply means
- * "nothing is known", which reads as stale (the honest default).
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-export function createFreshness(filePath) {
-    let marks = new Map();
-    return {
-        markFresh(name, at) {
-            marks.set(name, at ?? Date.now());
-        },
-        lastFresh(name) {
-            return marks.get(name) ?? null;
-        },
-        isStale(name, maxAgeMs, now) {
-            const last = marks.get(name);
-            if (last === undefined) {
-                return true; // never refreshed is the stalest state there is
-            }
-            return (now ?? Date.now()) - last > maxAgeMs;
-        },
-        save() {
-            if (!filePath)
-                return;
-            mkdirSync(dirname(filePath), { recursive: true });
-            writeFileSync(filePath, JSON.stringify(Object.fromEntries(marks)), "utf8");
-        },
-        load() {
-            if (!filePath || !existsSync(filePath))
-                return;
-            const raw = JSON.parse(readFileSync(filePath, "utf8"));
-            marks = new Map(Object.entries(raw));
-        },
-    };
-}
-//# sourceMappingURL=freshness.js.map

package/dist/scheduler/index.d.ts

@@ -1,21 +0,0 @@
-/**
- * Scheduler composition (S4) — wire core + freshness + refreshers into one switchable unit.
- *
- * The whole scheduler is OFF unless explicitly enabled (fail-safe: an MCP server must never
- * grow background network activity by surprise). Enabled, it registers every refresh unit on
- * the cadence engine, starts the timers, and exposes a status view the server (or a future
- * `scheduler_status` tool) can render: every unit, its cadence, and when it last ran.
- */
-import { type SchedulerJobView } from "./core.js";
-export interface InitSchedulerOpts {
-    enabled: boolean;
-    pull: Record<string, () => Promise<void>>;
-    freshnessPath?: string;
-}
-export interface RunningScheduler {
-    started: boolean;
-    status(): SchedulerJobView[];
-    stop(): void;
-}
-export declare function initScheduler(opts: InitSchedulerOpts): RunningScheduler;
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/index.js

@@ -1,32 +0,0 @@
-/**
- * Scheduler composition (S4) — wire core + freshness + refreshers into one switchable unit.
- *
- * The whole scheduler is OFF unless explicitly enabled (fail-safe: an MCP server must never
- * grow background network activity by surprise). Enabled, it registers every refresh unit on
- * the cadence engine, starts the timers, and exposes a status view the server (or a future
- * `scheduler_status` tool) can render: every unit, its cadence, and when it last ran.
- */
-import { createScheduler } from "./core.js";
-import { createFreshness } from "./freshness.js";
-import { buildRefreshers } from "./refreshers.js";
-export function initScheduler(opts) {
-    if (!opts.enabled) {
-        return { started: false, status: () => [], stop: () => { } };
-    }
-    const freshness = createFreshness(opts.freshnessPath);
-    freshness.load();
-    const scheduler = createScheduler();
-    for (const unit of buildRefreshers({ pull: opts.pull, freshness })) {
-        scheduler.register(unit.name, unit.intervalMs, () => unit.run());
-    }
-    scheduler.start();
-    return {
-        started: true,
-        status: () => scheduler.jobs(),
-        stop: () => {
-            scheduler.stop();
-            freshness.save();
-        },
-    };
-}
-//# sourceMappingURL=index.js.map

package/dist/scheduler/refreshers.d.ts

@@ -1,21 +0,0 @@
-/**
- * Refresh adapters (S3) — wrap each named data pull into a schedulable refresh unit.
- *
- * Pure dependency injection: the pulls and the freshness sink are handed in, nothing is
- * imported from the fetcher layer and nothing touches the network here. A refresh unit runs
- * its pull and only THEN marks freshness — a failing pull rethrows and leaves the watermark
- * untouched, so staleness stays honest.
- */
-export interface RefreshDeps {
-    pull: Record<string, () => Promise<void>>;
-    freshness: {
-        markFresh(name: string, at?: number): void;
-    };
-}
-export interface RefreshUnit {
-    name: string;
-    intervalMs: number;
-    run(): Promise<void>;
-}
-export declare function buildRefreshers(deps: RefreshDeps): RefreshUnit[];
-//# sourceMappingURL=refreshers.d.ts.map

package/dist/scheduler/refreshers.js

@@ -1,21 +0,0 @@
-/**
- * Refresh adapters (S3) — wrap each named data pull into a schedulable refresh unit.
- *
- * Pure dependency injection: the pulls and the freshness sink are handed in, nothing is
- * imported from the fetcher layer and nothing touches the network here. A refresh unit runs
- * its pull and only THEN marks freshness — a failing pull rethrows and leaves the watermark
- * untouched, so staleness stays honest.
- */
-/** Default cadence per refresh unit; callers can re-register with their own interval. */
-const DEFAULT_INTERVAL_MS = 15 * 60 * 1000; // 15 minutes — fresh enough for feed data, kind to upstreams
-export function buildRefreshers(deps) {
-    return Object.entries(deps.pull).map(([name, pull]) => ({
-        name,
-        intervalMs: DEFAULT_INTERVAL_MS,
-        async run() {
-            await pull(); // a throw propagates — freshness must NOT advance on a failed pull
-            deps.freshness.markFresh(name);
-        },
-    }));
-}
-//# sourceMappingURL=refreshers.js.map