stellar-memory 0.5.0

package/dist/engine/temporal.js

@@ -0,0 +1,283 @@
+/**
+ * temporal.ts — Temporal Awareness engine
+ *
+ * Tracks when facts become valid/invalid over time. Memories can have
+ * temporal bounds (valid_from, valid_until) and can supersede each other
+ * when a concept evolves (e.g., "Chose Redis" → "Switched to Valkey").
+ *
+ * All functions are pure (no classes), following the project style.
+ */
+import { getDatabase } from '../storage/database.js';
+import { getMemoriesAtTime, supersedMemory as queriesSupersedMemory, getSupersessionChain, } from '../storage/queries.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('temporal');
+// ---------------------------------------------------------------------------
+// Temporal bounds
+// ---------------------------------------------------------------------------
+/**
+ * Set temporal validity bounds on a memory.
+ *
+ * - validFrom:  ISO date string. If omitted, the memory is valid from creation.
+ * - validUntil: ISO date string. Setting this marks the fact as no longer current.
+ */
+export function setTemporalBounds(memoryId, validFrom, validUntil) {
+    const db = getDatabase();
+    const now = new Date().toISOString();
+    const sets = ['updated_at = ?'];
+    const values = [now];
+    if (validFrom !== undefined) {
+        sets.push('valid_from = ?');
+        values.push(validFrom);
+    }
+    if (validUntil !== undefined) {
+        sets.push('valid_until = ?');
+        values.push(validUntil);
+    }
+    values.push(memoryId);
+    db.prepare(`UPDATE memories SET ${sets.join(', ')} WHERE id = ?`).run(...values);
+    log.debug('Temporal bounds set', { memoryId, validFrom, validUntil });
+}
+// ---------------------------------------------------------------------------
+// Supersession
+// ---------------------------------------------------------------------------
+/**
+ * Mark oldMemoryId as superseded by newMemoryId.
+ *
+ * Sets the old memory's valid_until to now and records superseded_by.
+ * Uses the existing queries.supersedMemory() helper.
+ */
+export function supersedeMemory(oldMemoryId, newMemoryId) {
+    queriesSupersedMemory(oldMemoryId, newMemoryId);
+    log.debug('Memory superseded', { oldMemoryId, newMemoryId });
+}
+// ---------------------------------------------------------------------------
+// Point-in-time context
+// ---------------------------------------------------------------------------
+/**
+ * Return the set of memories that were active at the given timestamp.
+ *
+ * A memory is active if:
+ *   valid_from IS NULL OR valid_from <= timestamp
+ *   AND (valid_until IS NULL OR valid_until > timestamp)
+ *
+ * Results are sorted by importance descending.
+ */
+export function getContextAtTime(project, timestamp) {
+    const memories = getMemoriesAtTime(project, timestamp);
+    return memories.sort((a, b) => b.importance - a.importance);
+}
+// ---------------------------------------------------------------------------
+// Evolution chain
+// ---------------------------------------------------------------------------
+/**
+ * Follow the superseded_by chain forward from memoryId and also walk
+ * backward to find the earliest ancestor.
+ *
+ * Returns the full lineage in chronological order (oldest first).
+ */
+export function getEvolutionChain(memoryId) {
+    // First find the root (walk backward via content search is not feasible —
+    // we look for any memory whose superseded_by points to our target, recursively).
+    const root = findChainRoot(memoryId);
+    // Now walk forward from root using getSupersessionChain (follows superseded_by).
+    const chain = getSupersessionChain(root);
+    // Sort chronologically by created_at
+    return chain.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+/**
+ * Walk backward to find the oldest ancestor in the supersession chain.
+ * A memory is a root if no other non-deleted memory has superseded_by = its id.
+ */
+function findChainRoot(memoryId) {
+    const db = getDatabase();
+    let currentId = memoryId;
+    for (let depth = 0; depth < 50; depth++) {
+        const row = db.prepare(`
+      SELECT id FROM memories
+      WHERE superseded_by = ? AND deleted_at IS NULL
+      LIMIT 1
+    `).get(currentId);
+        if (!row)
+            break;
+        currentId = row.id;
+    }
+    return currentId;
+}
+// ---------------------------------------------------------------------------
+// Auto-detect supersession
+// ---------------------------------------------------------------------------
+/**
+ * Detect whether newMemory should supersede an existing memory.
+ *
+ * Heuristics (no LLM required):
+ *   1. Same memory type (especially 'decision')
+ *   2. High keyword overlap (>70% shared key terms)
+ *   3. Content contains a "switch" signal ("switched from", "replaced", "instead of", etc.)
+ *   4. Existing memory has not already been superseded
+ *
+ * Returns the memory that should be superseded, or null.
+ */
+export function detectSupersession(newMemory, existingMemories) {
+    const newTerms = extractKeyTerms(newMemory.content.toLowerCase());
+    const newLower = newMemory.content.toLowerCase();
+    // Detect switch signals in the new memory content
+    const SWITCH_PATTERNS = [
+        /switched?\s+from\s+(\w+)/i,
+        /replaced?\s+(\w+)/i,
+        /instead\s+of\s+(\w+)/i,
+        /moving?\s+(?:away\s+)?from\s+(\w+)/i,
+        /migrat\w+\s+from\s+(\w+)/i,
+        /no\s+longer\s+us\w+\s+(\w+)/i,
+    ];
+    for (const existing of existingMemories) {
+        // Skip already-superseded memories
+        if (existing.superseded_by)
+            continue;
+        // Skip self
+        if (existing.id === newMemory.id)
+            continue;
+        const existingLower = existing.content.toLowerCase();
+        const existingTerms = extractKeyTerms(existingLower);
+        const overlap = termOverlap(newTerms, existingTerms);
+        // Require minimum shared context
+        if (overlap < 0.4)
+            continue;
+        // Same type (especially decision) + high overlap → likely supersession
+        if (existing.type === newMemory.type && existing.type === 'decision' && overlap >= 0.7) {
+            log.debug('Supersession candidate found (decision type + high overlap)', {
+                existingId: existing.id,
+                overlap,
+            });
+            return existing;
+        }
+        // Switch signal: new memory explicitly references a transition away from something
+        for (const pattern of SWITCH_PATTERNS) {
+            const match = newLower.match(pattern);
+            if (match) {
+                const switchedFrom = match[1];
+                if (existingLower.includes(switchedFrom)) {
+                    log.debug('Supersession candidate found (switch pattern)', {
+                        existingId: existing.id,
+                        pattern: pattern.toString(),
+                        switchedFrom,
+                    });
+                    return existing;
+                }
+            }
+        }
+        // High overlap + different conclusion signals
+        if (overlap >= 0.7 && hasOppositeSignal(newLower, existingLower)) {
+            log.debug('Supersession candidate found (opposite signal)', {
+                existingId: existing.id,
+                overlap,
+            });
+            return existing;
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Temporal summary for sun context
+// ---------------------------------------------------------------------------
+/**
+ * Build a concise textual summary of temporal state for the sun resource.
+ *
+ * Includes:
+ *   - Count of active vs superseded memories
+ *   - Recent supersession events (last 5)
+ */
+export function getTemporalSummary(project) {
+    const db = getDatabase();
+    const now = new Date().toISOString();
+    // Active: not deleted, valid_from ≤ now, valid_until IS NULL or > now
+    const activeRow = db.prepare(`
+    SELECT COUNT(*) as count FROM memories
+    WHERE project = ?
+      AND deleted_at IS NULL
+      AND (valid_from IS NULL OR valid_from <= ?)
+      AND (valid_until IS NULL OR valid_until > ?)
+  `).get(project, now, now);
+    // Superseded: has superseded_by set
+    const supersededRow = db.prepare(`
+    SELECT COUNT(*) as count FROM memories
+    WHERE project = ? AND deleted_at IS NULL AND superseded_by IS NOT NULL
+  `).get(project);
+    // Recent supersessions
+    const recentRows = db.prepare(`
+    SELECT id, summary, superseded_by, updated_at FROM memories
+    WHERE project = ?
+      AND deleted_at IS NULL
+      AND superseded_by IS NOT NULL
+    ORDER BY updated_at DESC
+    LIMIT 5
+  `).all(project);
+    const lines = [
+        `Temporal: ${activeRow.count} active, ${supersededRow.count} superseded`,
+    ];
+    if (recentRows.length > 0) {
+        lines.push('Recent supersessions:');
+        for (const row of recentRows) {
+            const date = row.updated_at.slice(0, 10);
+            lines.push(`  [${date}] "${row.summary}" → superseded by ${row.superseded_by.slice(0, 8)}`);
+        }
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract meaningful key terms from lowercased text.
+ * Filters out common stop words and short tokens.
+ */
+export function extractKeyTerms(text) {
+    const STOP_WORDS = new Set([
+        'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+        'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+        'should', 'may', 'might', 'shall', 'can', 'to', 'of', 'in', 'for',
+        'on', 'with', 'at', 'by', 'from', 'as', 'into', 'through', 'during',
+        'this', 'that', 'these', 'those', 'i', 'we', 'our', 'it', 'its',
+        'and', 'or', 'but', 'not', 'no', 'so', 'if', 'then', 'than', 'also',
+    ]);
+    const terms = new Set();
+    const tokens = text.match(/[a-z0-9_\-\.]+/g) ?? [];
+    for (const token of tokens) {
+        if (token.length >= 3 && !STOP_WORDS.has(token)) {
+            terms.add(token);
+        }
+    }
+    return terms;
+}
+/**
+ * Compute Jaccard-like overlap between two term sets.
+ * Returns a value in [0, 1].
+ */
+function termOverlap(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let shared = 0;
+    for (const term of a) {
+        if (b.has(term))
+            shared++;
+    }
+    const union = new Set([...a, ...b]).size;
+    return shared / union;
+}
+/**
+ * Check if the two texts contain opposing action signals around shared terms.
+ * E.g., "use X" in old vs "not use X" or "avoid X" in new.
+ */
+function hasOppositeSignal(newText, existingText) {
+    const NEGATION_PREFIXES = ['not ', "don't ", 'avoid ', 'remove ', 'disable ', 'stop using '];
+    const ACTION_VERBS = ['use', 'enable', 'add', 'adopt', 'choose', 'select', 'implement'];
+    for (const verb of ACTION_VERBS) {
+        const existingHasVerb = existingText.includes(verb);
+        if (!existingHasVerb)
+            continue;
+        const newNegatesVerb = NEGATION_PREFIXES.some(neg => newText.includes(neg + verb));
+        if (newNegatesVerb)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=temporal.js.map

package/dist/engine/temporal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.js","sourceRoot":"","sources":["../../src/engine/temporal.ts"],"names":[],"mappings":"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"}

package/dist/engine/types.d.ts

@@ -0,0 +1,179 @@
+export type MemoryType = 'decision' | 'observation' | 'task' | 'context' | 'error' | 'milestone' | 'procedural';
+export declare const ORBIT_ZONES: {
+    readonly core: {
+        readonly min: 0.1;
+        readonly max: 1;
+        readonly label: "Core Memory";
+    };
+    readonly near: {
+        readonly min: 1;
+        readonly max: 5;
+        readonly label: "Recent Memory";
+    };
+    readonly active: {
+        readonly min: 5;
+        readonly max: 15;
+        readonly label: "Active Memory";
+    };
+    readonly archive: {
+        readonly min: 15;
+        readonly max: 40;
+        readonly label: "Stored Memory";
+    };
+    readonly fading: {
+        readonly min: 40;
+        readonly max: 70;
+        readonly label: "Fading Memory";
+    };
+    readonly forgotten: {
+        readonly min: 70;
+        readonly max: 100;
+        readonly label: "Forgotten Memory";
+    };
+};
+export type OrbitZone = keyof typeof ORBIT_ZONES;
+export declare const IMPACT_DEFAULTS: Record<MemoryType, number>;
+export declare const DEFAULT_WEIGHTS: {
+    readonly recency: 0.3;
+    readonly frequency: 0.2;
+    readonly impact: 0.3;
+    readonly relevance: 0.2;
+};
+export interface Memory {
+    id: string;
+    project: string;
+    content: string;
+    summary: string;
+    type: MemoryType;
+    tags: string[];
+    distance: number;
+    importance: number;
+    velocity: number;
+    impact: number;
+    access_count: number;
+    last_accessed_at: string | null;
+    metadata: Record<string, unknown>;
+    source: string | null;
+    source_path: string | null;
+    source_hash: string | null;
+    content_hash: string | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+    embedding?: Float32Array;
+    valid_from?: string;
+    valid_until?: string;
+    superseded_by?: string;
+    consolidated_into?: string;
+    quality_score?: number;
+    is_universal?: boolean;
+}
+export interface VectorSearchResult {
+    memoryId: string;
+    distance: number;
+}
+export interface SunState {
+    project: string;
+    content: string;
+    current_work: string;
+    recent_decisions: string[];
+    next_steps: string[];
+    active_errors: string[];
+    project_context: string;
+    token_count: number;
+    last_commit_at: string | null;
+    updated_at: string;
+}
+export interface OrbitChange {
+    memory_id: string;
+    project: string;
+    old_distance: number;
+    new_distance: number;
+    old_importance: number;
+    new_importance: number;
+    trigger: 'decay' | 'access' | 'commit' | 'manual' | 'gravity' | 'forget';
+}
+export interface ImportanceComponents {
+    recency: number;
+    frequency: number;
+    impact: number;
+    relevance: number;
+    total: number;
+}
+export type RelationType = 'uses' | 'caused_by' | 'part_of' | 'contradicts' | 'supersedes' | 'related_to' | 'depends_on' | 'derived_from';
+export interface ConstellationEdge {
+    id: string;
+    source_id: string;
+    target_id: string;
+    relation: RelationType;
+    weight: number;
+    project: string;
+    created_at: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TemporalInfo {
+    valid_from?: string;
+    valid_until?: string;
+    superseded_by?: string;
+}
+export interface MemoryConflict {
+    id: string;
+    memory_id: string;
+    conflicting_memory_id: string;
+    severity: 'high' | 'medium' | 'low';
+    description: string;
+    status: 'open' | 'resolved' | 'dismissed';
+    resolution?: string;
+    project: string;
+    created_at: string;
+    resolved_at?: string;
+}
+export interface QualityScore {
+    overall: number;
+    specificity: number;
+    actionability: number;
+    uniqueness: number;
+    freshness: number;
+}
+export interface MemoryAnalytics {
+    total_memories: number;
+    zone_distribution: Record<string, number>;
+    type_distribution: Record<string, number>;
+    avg_quality: number;
+    avg_importance: number;
+    recall_success_rate: number;
+    consolidation_count: number;
+    conflict_count: number;
+    top_tags: Array<{
+        tag: string;
+        count: number;
+    }>;
+    activity_timeline: Array<{
+        date: string;
+        created: number;
+        accessed: number;
+        forgotten: number;
+    }>;
+}
+export interface ObservationEntry {
+    id: string;
+    content: string;
+    extracted_memories: string[];
+    source: 'conversation' | 'reflection';
+    project: string;
+    created_at: string;
+}
+export interface StellarConfig {
+    dbPath: string;
+    defaultProject: string;
+    sunTokenBudget: number;
+    decayHalfLifeHours: number;
+    frequencySaturationPoint: number;
+    weights: {
+        recency: number;
+        frequency: number;
+        impact: number;
+        relevance: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/engine/types.js

@@ -0,0 +1,27 @@
+// Orbit zones
+export const ORBIT_ZONES = {
+    core: { min: 0.1, max: 1.0, label: 'Core Memory' },
+    near: { min: 1.0, max: 5.0, label: 'Recent Memory' },
+    active: { min: 5.0, max: 15.0, label: 'Active Memory' },
+    archive: { min: 15.0, max: 40.0, label: 'Stored Memory' },
+    fading: { min: 40.0, max: 70.0, label: 'Fading Memory' },
+    forgotten: { min: 70.0, max: 100.0, label: 'Forgotten Memory' },
+};
+// Default impact by memory type
+export const IMPACT_DEFAULTS = {
+    decision: 0.8,
+    milestone: 0.7,
+    error: 0.6,
+    task: 0.5,
+    context: 0.4,
+    observation: 0.3,
+    procedural: 0.5,
+};
+// Importance weights
+export const DEFAULT_WEIGHTS = {
+    recency: 0.30,
+    frequency: 0.20,
+    impact: 0.30,
+    relevance: 0.20,
+};
+//# sourceMappingURL=types.js.map

package/dist/engine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":"AAGA,cAAc;AACd,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAO,EAAE,GAAG,EAAE,GAAG,EAAG,GAAG,EAAE,GAAG,EAAG,KAAK,EAAE,aAAa,EAAE;IACzD,IAAI,EAAO,EAAE,GAAG,EAAE,GAAG,EAAG,GAAG,EAAE,GAAG,EAAG,KAAK,EAAE,eAAe,EAAE;IAC3D,MAAM,EAAK,EAAE,GAAG,EAAE,GAAG,EAAG,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,EAAE;IAC3D,OAAO,EAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,EAAE;IAC3D,MAAM,EAAK,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,EAAE;IAC3D,SAAS,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE;CACvD,CAAC;AAIX,gCAAgC;AAChC,MAAM,CAAC,MAAM,eAAe,GAA+B;IACzD,QAAQ,EAAK,GAAG;IAChB,SAAS,EAAI,GAAG;IAChB,KAAK,EAAQ,GAAG;IAChB,IAAI,EAAS,GAAG;IAChB,OAAO,EAAM,GAAG;IAChB,WAAW,EAAE,GAAG;IAChB,UAAU,EAAG,GAAG;CACjB,CAAC;AAEF,qBAAqB;AACrB,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAI,IAAI;IACf,SAAS,EAAE,IAAI;IACf,MAAM,EAAK,IAAI;IACf,SAAS,EAAE,IAAI;CACP,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,60 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createStellarServer } from './mcp/server.js';
+import { initDatabase } from './storage/database.js';
+import { getConfig } from './utils/config.js';
+import { autoCommitOnClose } from './engine/sun.js';
+/**
+ * Validate that the runtime environment meets Stellar Memory's requirements.
+ * Exits with a human-readable error message if anything is missing.
+ */
+function validateEnvironment() {
+    // Check Node.js version (requires 22+ for node:sqlite)
+    const [major] = process.versions.node.split('.').map(Number);
+    if (major < 22) {
+        console.error(`[stellar-memory] ERROR: Node.js 22 or higher is required.\n` +
+            `  Detected: Node.js ${process.versions.node}\n` +
+            `  Upgrade:  nvm install 22 && nvm use 22\n` +
+            `            or visit https://nodejs.org/en/download`);
+        process.exit(1);
+    }
+    // node:sqlite is available since Node 22.5.0 — check the minor version.
+    const nodeVersion = process.versions.node.split('.').map(Number);
+    const [, minor] = nodeVersion;
+    if (major === 22 && minor < 5) {
+        console.error(`[stellar-memory] ERROR: Node.js 22.5.0 or higher is required for node:sqlite.\n` +
+            `  Detected: Node.js ${process.versions.node}\n` +
+            `  Upgrade:  nvm install 22 && nvm use 22`);
+        process.exit(1);
+    }
+}
+async function main() {
+    validateEnvironment();
+    const config = getConfig();
+    // Initialize SQLite database (creates schema on first run)
+    initDatabase(config.dbPath);
+    // Create MCP server with all tools and resources registered
+    const server = createStellarServer();
+    // ── Shutdown handlers ────────────────────────────────────────────────────
+    // Auto-commit sun state so the next session resumes with full context.
+    let shutdownDone = false;
+    const onShutdown = () => {
+        if (shutdownDone)
+            return;
+        shutdownDone = true;
+        autoCommitOnClose(config.defaultProject);
+    };
+    process.on('exit', onShutdown);
+    process.on('SIGTERM', () => { onShutdown(); process.exit(0); });
+    process.on('SIGINT', () => { onShutdown(); process.exit(0); });
+    // Connect via stdio transport (used by Claude Code / Claude Desktop)
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[stellar-memory] Server started');
+    console.error(`[stellar-memory] Project: ${config.defaultProject}`);
+    console.error(`[stellar-memory] DB: ${config.dbPath}`);
+}
+main().catch((err) => {
+    console.error('[stellar-memory] Fatal error:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/mcp/connector-registry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * mcp/connector-registry.ts — Class-based registry for cloud connectors.
+ *
+ * Replaces the module-level `connectorRegistry` Map in the original server.ts.
+ * A class instance is passed around explicitly, making dependencies visible,
+ * enabling per-test isolation, and removing hidden global state.
+ */
+import type { CloudConnector } from '../scanner/cloud/types.js';
+export declare class ConnectorRegistry {
+    private readonly registry;
+    set(type: string, connector: CloudConnector): void;
+    get(type: string): CloudConnector | undefined;
+    has(type: string): boolean;
+    get size(): number;
+    keys(): string[];
+    values(): CloudConnector[];
+    delete(type: string): boolean;
+    clear(): void;
+}
+//# sourceMappingURL=connector-registry.d.ts.map

package/dist/mcp/connector-registry.js

@@ -0,0 +1,35 @@
+/**
+ * mcp/connector-registry.ts — Class-based registry for cloud connectors.
+ *
+ * Replaces the module-level `connectorRegistry` Map in the original server.ts.
+ * A class instance is passed around explicitly, making dependencies visible,
+ * enabling per-test isolation, and removing hidden global state.
+ */
+export class ConnectorRegistry {
+    registry = new Map();
+    set(type, connector) {
+        this.registry.set(type, connector);
+    }
+    get(type) {
+        return this.registry.get(type);
+    }
+    has(type) {
+        return this.registry.has(type);
+    }
+    get size() {
+        return this.registry.size;
+    }
+    keys() {
+        return [...this.registry.keys()];
+    }
+    values() {
+        return [...this.registry.values()];
+    }
+    delete(type) {
+        return this.registry.delete(type);
+    }
+    clear() {
+        this.registry.clear();
+    }
+}
+//# sourceMappingURL=connector-registry.js.map

package/dist/mcp/connector-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-registry.js","sourceRoot":"","sources":["../../src/mcp/connector-registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,OAAO,iBAAiB;IACX,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE9D,GAAG,CAAC,IAAY,EAAE,SAAyB;QACzC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACrC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,IAAY;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * mcp/server.ts — Thin factory that wires tool handlers to the MCP server.
+ *
+ * Responsibilities:
+ *   1. Instantiate McpServer.
+ *   2. Register the stellar://sun resource.
+ *   3. Register each tool, forwarding parsed args to the appropriate handler.
+ *
+ * Business logic lives in mcp/tools/. This file contains no logic beyond wiring.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createStellarServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map