mcp-astgl-knowledge 1.0.2 → 1.1.0

package/dist/knowledge-db.js

@@ -0,0 +1,156 @@
+/**
+ * Knowledge database module for incremental updates.
+ * Provides UPSERT operations against knowledge.db without
+ * destroying existing data (unlike ingest.ts's DROP/CREATE).
+ */
+import { join } from "path";
+import { existsSync, mkdirSync } from "fs";
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
+const DB_PATH = join(import.meta.dirname, "..", "data", "knowledge.db");
+let db = null;
+// WHAT: Open knowledge.db and run idempotent schema migrations
+// WHY: Adds columns needed by the structuring pipeline without breaking existing data
+export function initKnowledgeDb() {
+    const dataDir = join(import.meta.dirname, "..", "data");
+    if (!existsSync(dataDir))
+        mkdirSync(dataDir, { recursive: true });
+    if (!existsSync(DB_PATH)) {
+        throw new Error(`Knowledge database not found at ${DB_PATH}. Run 'npm run ingest' first to create the base schema.`);
+    }
+    db = new Database(DB_PATH);
+    sqliteVec.load(db);
+    runMigrations(db);
+    return db;
+}
+// WHAT: Add new columns and tables needed by the structuring pipeline
+// WHY: ALTER TABLE with try/catch is idempotent — safe to re-run after ingest.ts rebuilds
+function runMigrations(database) {
+    const alterColumns = [
+        "ALTER TABLE articles ADD COLUMN source_url TEXT",
+        "ALTER TABLE articles ADD COLUMN content_type TEXT DEFAULT 'article'",
+        "ALTER TABLE articles ADD COLUMN json_ld TEXT",
+        "ALTER TABLE articles ADD COLUMN processed_at TEXT",
+        "ALTER TABLE articles ADD COLUMN pub_date TEXT",
+        "ALTER TABLE articles ADD COLUMN last_reviewed_at TEXT",
+        "ALTER TABLE articles ADD COLUMN freshness_status TEXT DEFAULT 'current'",
+    ];
+    for (const sql of alterColumns) {
+        try {
+            database.exec(sql);
+        }
+        catch {
+            // Column already exists — expected after first run
+        }
+    }
+    database.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_articles_url ON articles(url)");
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS article_qa (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      article_url TEXT NOT NULL,
+      question TEXT NOT NULL,
+      answer TEXT NOT NULL,
+      UNIQUE(article_url, question)
+    )
+  `);
+    // WHAT: Track ecosystem versions for freshness detection
+    // WHY: Comparing current vs previous version detects when articles may be outdated
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS ecosystem_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      check_type TEXT NOT NULL,
+      package_name TEXT NOT NULL,
+      current_version TEXT NOT NULL,
+      previous_version TEXT,
+      checked_at TEXT NOT NULL,
+      UNIQUE(check_type, package_name)
+    )
+  `);
+}
+// WHAT: Insert or replace an article in knowledge.db
+// WHY: Keyed on url so discovered content can coexist with local articles
+export function upsertArticle(database, article) {
+    const existing = database
+        .prepare("SELECT id FROM articles WHERE url = ?")
+        .get(article.url);
+    if (existing) {
+        database
+            .prepare(`UPDATE articles SET title = ?, description = ?, slug = ?,
+         source_url = ?, content_type = ?, json_ld = ?, processed_at = ?,
+         pub_date = COALESCE(?, pub_date)
+         WHERE id = ?`)
+            .run(article.title, article.description, article.slug, article.sourceUrl, article.contentType, article.jsonLd, article.processedAt, article.pubDate || null, existing.id);
+    }
+    else {
+        database
+            .prepare(`INSERT INTO articles (title, description, url, slug, source_url, content_type, json_ld, processed_at, pub_date)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(article.title, article.description, article.url, article.slug, article.sourceUrl, article.contentType, article.jsonLd, article.processedAt, article.pubDate || null);
+    }
+}
+// WHAT: Update freshness status for an article
+// WHY: Freshness checker sets status without re-processing the full article
+export function updateFreshnessStatus(database, articleUrl, status, reviewedAt) {
+    if (reviewedAt) {
+        database
+            .prepare("UPDATE articles SET freshness_status = ?, last_reviewed_at = ? WHERE url = ?")
+            .run(status, reviewedAt, articleUrl);
+    }
+    else {
+        database
+            .prepare("UPDATE articles SET freshness_status = ? WHERE url = ?")
+            .run(status, articleUrl);
+    }
+}
+// WHAT: Delete existing chunks + vectors for an article, insert new ones
+// WHY: sqlite-vec doesn't support INSERT OR REPLACE — delete-then-insert in a transaction
+export function replaceChunksForArticle(database, articleUrl, chunks, embeddings) {
+    const replaceAll = database.transaction(() => {
+        // Find existing chunk IDs for this article
+        const existingChunks = database
+            .prepare("SELECT id FROM chunks WHERE article_url = ?")
+            .all(articleUrl);
+        // Delete vectors for those chunks
+        const deleteVec = database.prepare("DELETE FROM vec_chunks WHERE chunk_id = ?");
+        for (const chunk of existingChunks) {
+            deleteVec.run(chunk.id);
+        }
+        // Delete the chunks themselves
+        database
+            .prepare("DELETE FROM chunks WHERE article_url = ?")
+            .run(articleUrl);
+        // Insert new chunks and vectors
+        const insertChunk = database.prepare(`INSERT INTO chunks (article_title, article_url, article_order, section_heading, chunk_type, content)
+       VALUES (?, ?, ?, ?, ?, ?)`);
+        const insertVec = database.prepare("INSERT INTO vec_chunks (chunk_id, embedding) VALUES (?, ?)");
+        for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            const result = insertChunk.run(chunk.articleTitle, chunk.articleUrl, chunk.articleOrder, chunk.sectionHeading, chunk.chunkType, chunk.content);
+            const chunkId = result.lastInsertRowid;
+            insertVec.run(BigInt(chunkId), new Float32Array(embeddings[i]));
+        }
+    });
+    replaceAll();
+}
+// WHAT: Insert extracted Q&A pairs for an article
+// WHY: Normalizes Q&A data for potential future querying
+export function upsertQaPairs(database, articleUrl, pairs) {
+    // Clear existing pairs for this article
+    database
+        .prepare("DELETE FROM article_qa WHERE article_url = ?")
+        .run(articleUrl);
+    const insert = database.prepare("INSERT OR IGNORE INTO article_qa (article_url, question, answer) VALUES (?, ?, ?)");
+    const insertAll = database.transaction(() => {
+        for (const pair of pairs) {
+            insert.run(articleUrl, pair.question, pair.answer);
+        }
+    });
+    insertAll();
+}
+export function closeKnowledgeDb() {
+    if (db) {
+        db.close();
+        db = null;
+    }
+}
+//# sourceMappingURL=knowledge-db.js.map

package/dist/knowledge-db.js.map

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

package/dist/pipeline.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+/**
+ * Unified content pipeline: Discovery → Structuring → Indexed.
+ *
+ * WHAT: Runs discover.ts then structure.ts in sequence with smart skipping
+ * WHY: Single entry point for the full publish → queryable pipeline,
+ *       skips structuring when no new content saves LLM compute
+ *
+ * Usage: npm run pipeline
+ * Designed to run as a single OpenClaw cron job (every 6 hours).
+ */
+export {};

package/dist/pipeline.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env tsx
+/**
+ * Unified content pipeline: Discovery → Structuring → Indexed.
+ *
+ * WHAT: Runs discover.ts then structure.ts in sequence with smart skipping
+ * WHY: Single entry point for the full publish → queryable pipeline,
+ *       skips structuring when no new content saves LLM compute
+ *
+ * Usage: npm run pipeline
+ * Designed to run as a single OpenClaw cron job (every 6 hours).
+ */
+import { execSync } from "child_process";
+import { join } from "path";
+const PROJECT_DIR = join(import.meta.dirname, "..");
+// WHAT: Run a script and capture its JSON stdout
+// WHY: Each step is its own process — isolates DB handles and crashes
+function runStep(script) {
+    return execSync(`tsx ${script}`, {
+        cwd: PROJECT_DIR,
+        encoding: "utf-8",
+        // WHAT: Pipe stdout (JSON) back, let stderr flow to console
+        // WHY: stderr has progress logs, stdout has the structured summary
+        stdio: ["pipe", "pipe", "inherit"],
+        timeout: 300_000, // 5 min per step
+    });
+}
+async function main() {
+    const pipelineStart = performance.now();
+    console.error("=== Content Pipeline Started ===\n");
+    const summary = {
+        timestamp: new Date().toISOString(),
+        discovery: { error: "not run" },
+        structuring: { skipped: true, reason: "not run" },
+        duration_ms: 0,
+    };
+    // --- Step 1: Discovery ---
+    console.error("--- Step 1: Content Discovery ---");
+    let newItems = 0;
+    try {
+        const discoveryOutput = runStep("src/discover.ts");
+        const discoveryResult = JSON.parse(discoveryOutput);
+        summary.discovery = discoveryResult;
+        newItems = discoveryResult.totals.new;
+        console.error(`\nDiscovery complete: ${newItems} new, ${discoveryResult.totals.updated} updated, ${discoveryResult.totals.skipped} skipped\n`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`\nDiscovery FAILED: ${message}\n`);
+        summary.discovery = { error: message };
+    }
+    // --- Step 2: Structuring (conditional) ---
+    if (newItems > 0) {
+        console.error("--- Step 2: Content Structuring ---");
+        try {
+            const structuringOutput = runStep("src/structure.ts");
+            const structuringResult = JSON.parse(structuringOutput);
+            summary.structuring = structuringResult;
+            console.error(`\nStructuring complete: ${structuringResult.processed} processed, ${structuringResult.failed} failed\n`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`\nStructuring FAILED: ${message}\n`);
+            summary.structuring = { error: message };
+        }
+    }
+    else if ("error" in summary.discovery) {
+        console.error("--- Step 2: Skipped (discovery failed) ---\n");
+        summary.structuring = { skipped: true, reason: "discovery failed" };
+    }
+    else {
+        console.error("--- Step 2: Skipped (no new content) ---\n");
+        summary.structuring = { skipped: true, reason: "no new content discovered" };
+    }
+    summary.duration_ms = Math.round(performance.now() - pipelineStart);
+    console.error(`=== Content Pipeline Complete (${(summary.duration_ms / 1000).toFixed(1)}s) ===`);
+    // JSON summary to stdout for OpenClaw logging
+    console.log(JSON.stringify(summary, null, 2));
+}
+main().catch((err) => {
+    console.error("Pipeline fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

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

package/dist/query-log.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Query logging module for MCP analytics.
+ *
+ * WHAT: Logs every MCP tool invocation with timing, params, and cited content
+ * WHY: Enables analytics on what users ask, which content gets cited, and response quality
+ *
+ * Performance:
+ *   Entries are buffered in memory and flushed to SQLite in batches
+ *   (every 5 seconds or when buffer hits 20 entries) to avoid blocking responses.
+ */
+import Database from "better-sqlite3";
+import type { QueryLogEntry } from "./types.js";
+export declare function initQueryLog(): InstanceType<typeof Database>;
+export declare function logQuery(entry: QueryLogEntry): void;
+export declare function closeQueryLog(): void;

package/dist/query-log.js

@@ -0,0 +1,93 @@
+/**
+ * Query logging module for MCP analytics.
+ *
+ * WHAT: Logs every MCP tool invocation with timing, params, and cited content
+ * WHY: Enables analytics on what users ask, which content gets cited, and response quality
+ *
+ * Performance:
+ *   Entries are buffered in memory and flushed to SQLite in batches
+ *   (every 5 seconds or when buffer hits 20 entries) to avoid blocking responses.
+ */
+import { join } from "path";
+import { existsSync, mkdirSync } from "fs";
+import Database from "better-sqlite3";
+const LOG_DB_PATH = join(import.meta.dirname, "..", "data", "query-log.db");
+const FLUSH_INTERVAL_MS = 5_000;
+const FLUSH_BATCH_SIZE = 20;
+let logDb = null;
+let buffer = [];
+let flushTimer = null;
+export function initQueryLog() {
+    const dataDir = join(import.meta.dirname, "..", "data");
+    if (!existsSync(dataDir))
+        mkdirSync(dataDir, { recursive: true });
+    logDb = new Database(LOG_DB_PATH);
+    logDb.exec(`
+    CREATE TABLE IF NOT EXISTS query_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp TEXT NOT NULL,
+      client_id TEXT NOT NULL,
+      tool_name TEXT NOT NULL,
+      query_params TEXT NOT NULL,
+      content_cited TEXT,
+      response_time_ms INTEGER NOT NULL,
+      confidence_score REAL
+    )
+  `);
+    // WHAT: Index on timestamp + tool_name for common analytics queries
+    // WHY: Most reports filter by date range and/or tool
+    logDb.exec("CREATE INDEX IF NOT EXISTS idx_query_log_ts ON query_log(timestamp)");
+    logDb.exec("CREATE INDEX IF NOT EXISTS idx_query_log_tool ON query_log(tool_name)");
+    // WHAT: Start periodic flush timer
+    // WHY: Ensures buffered entries are written even during low-traffic periods
+    flushTimer = setInterval(flushBuffer, FLUSH_INTERVAL_MS);
+    flushTimer.unref(); // Don't keep process alive just for logging
+    // WHAT: Flush on process exit
+    // WHY: Don't lose buffered entries when the MCP server shuts down
+    process.on("beforeExit", flushBuffer);
+    return logDb;
+}
+// WHAT: Buffer log entries and flush when threshold is reached
+// WHY: Removes ~1-5ms synchronous INSERT from every tool response
+export function logQuery(entry) {
+    if (!logDb)
+        return;
+    buffer.push(entry);
+    if (buffer.length >= FLUSH_BATCH_SIZE) {
+        flushBuffer();
+    }
+}
+// WHAT: Write all buffered entries to SQLite in a single transaction
+// WHY: Batch INSERT in a transaction is ~10x faster than individual INSERTs
+function flushBuffer() {
+    if (!logDb || buffer.length === 0)
+        return;
+    const entries = buffer.splice(0);
+    try {
+        const insert = logDb.prepare(`INSERT INTO query_log (timestamp, client_id, tool_name, query_params, content_cited, response_time_ms, confidence_score)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`);
+        const insertAll = logDb.transaction(() => {
+            for (const entry of entries) {
+                insert.run(entry.timestamp, entry.clientId, entry.toolName, entry.queryParams, entry.contentCited, entry.responseTimeMs, entry.confidenceScore);
+            }
+        });
+        insertAll();
+    }
+    catch (err) {
+        // WHAT: Log error but don't crash — analytics loss is acceptable
+        // WHY: Query logging should never block or crash the MCP server
+        console.error(`Query log flush failed (${entries.length} entries lost):`, err instanceof Error ? err.message : err);
+    }
+}
+export function closeQueryLog() {
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+    flushBuffer(); // Final flush
+    if (logDb) {
+        logDb.close();
+        logDb = null;
+    }
+}
+//# sourceMappingURL=query-log.js.map

package/dist/query-log.js.map

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

package/dist/rate-limit.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Rate limiting and registration module.
+ *
+ * WHAT: Enforces per-client daily query limits with public/registered tiers
+ * WHY: Protects server resources while incentivizing email registration for higher limits
+ *
+ * Tiers:
+ *   Public:     50 queries/day (anonymous, persistent client ID)
+ *   Registered: 500 queries/day (API key via ASTGL_API_KEY env var)
+ */
+export type Tier = "public" | "registered";
+export interface RateLimitResult {
+    allowed: boolean;
+    tier: Tier;
+    clientId: string;
+    used: number;
+    limit: number;
+    remaining: number;
+}
+export interface RegistrationResult {
+    success: boolean;
+    apiKey?: string;
+    email?: string;
+    message: string;
+}
+export declare function resolveClient(): {
+    clientId: string;
+    tier: Tier;
+};
+export declare function initRateLimitDb(): void;
+export declare function checkRateLimit(clientId: string, tier: Tier): RateLimitResult;
+export declare function rateLimitMessage(result: RateLimitResult): string;
+export declare function registerClient(email: string): RegistrationResult;
+export declare function closeRateLimitDb(): void;

package/dist/rate-limit.js

@@ -0,0 +1,206 @@
+/**
+ * Rate limiting and registration module.
+ *
+ * WHAT: Enforces per-client daily query limits with public/registered tiers
+ * WHY: Protects server resources while incentivizing email registration for higher limits
+ *
+ * Tiers:
+ *   Public:     50 queries/day (anonymous, persistent client ID)
+ *   Registered: 500 queries/day (API key via ASTGL_API_KEY env var)
+ */
+import { join } from "path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { randomUUID, createHash } from "crypto";
+import Database from "better-sqlite3";
+const DATA_DIR = join(import.meta.dirname, "..", "data");
+const RATE_DB_PATH = join(DATA_DIR, "query-log.db");
+const CLIENT_ID_FILE = join(homedir(), ".astgl-client-id");
+const PUBLIC_LIMIT = 50;
+const REGISTERED_LIMIT = 500;
+let rateLimitDb = null;
+// --- Client Identity ---
+// WHAT: Get or create a persistent anonymous client ID
+// WHY: MCP stdio servers are ephemeral — need a stable ID across sessions for rate limiting
+function getOrCreateAnonymousId() {
+    if (existsSync(CLIENT_ID_FILE)) {
+        const id = readFileSync(CLIENT_ID_FILE, "utf-8").trim();
+        if (id)
+            return id;
+    }
+    const id = `anon_${randomUUID()}`;
+    try {
+        writeFileSync(CLIENT_ID_FILE, id, "utf-8");
+    }
+    catch {
+        // WHAT: Fall back to hostname-based ID if file write fails
+        // WHY: Some environments restrict home directory writes (containers, CI)
+        return `anon_${createHash("sha256").update(homedir()).digest("hex").slice(0, 16)}`;
+    }
+    return id;
+}
+// WHAT: Resolve the effective client ID and tier
+// WHY: API key takes precedence over anonymous ID; determines rate limit tier
+export function resolveClient() {
+    const apiKey = process.env.ASTGL_API_KEY;
+    if (apiKey && apiKey.startsWith("astgl_")) {
+        // Validate API key against registrations
+        if (rateLimitDb) {
+            const reg = rateLimitDb
+                .prepare("SELECT email FROM registrations WHERE api_key = ?")
+                .get(apiKey);
+            if (reg) {
+                return { clientId: apiKey, tier: "registered" };
+            }
+        }
+        // Invalid key — fall through to anonymous
+        console.error(`Warning: ASTGL_API_KEY provided but not found in registrations.`);
+    }
+    return { clientId: getOrCreateAnonymousId(), tier: "public" };
+}
+// --- Rate Limiting ---
+export function initRateLimitDb() {
+    if (!existsSync(DATA_DIR))
+        mkdirSync(DATA_DIR, { recursive: true });
+    // WHAT: Reuse query-log.db for rate limit tracking
+    // WHY: Query counts are already there — just need a registrations table
+    rateLimitDb = new Database(RATE_DB_PATH);
+    // Ensure query_log table exists (may not if server hasn't been used yet)
+    rateLimitDb.exec(`
+    CREATE TABLE IF NOT EXISTS query_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp TEXT NOT NULL,
+      client_id TEXT NOT NULL,
+      tool_name TEXT NOT NULL,
+      query_params TEXT NOT NULL,
+      content_cited TEXT,
+      response_time_ms INTEGER NOT NULL,
+      confidence_score REAL
+    )
+  `);
+    rateLimitDb.exec("CREATE INDEX IF NOT EXISTS idx_query_log_ts ON query_log(timestamp)");
+    rateLimitDb.exec("CREATE INDEX IF NOT EXISTS idx_query_log_tool ON query_log(tool_name)");
+    rateLimitDb.exec("CREATE INDEX IF NOT EXISTS idx_query_log_client ON query_log(client_id)");
+    rateLimitDb.exec(`
+    CREATE TABLE IF NOT EXISTS registrations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      email TEXT NOT NULL UNIQUE,
+      api_key TEXT NOT NULL UNIQUE,
+      created_at TEXT NOT NULL
+    )
+  `);
+}
+// --- Rate Limit Cache ---
+// WHAT: Cache rate limit results for 5 seconds per client
+// WHY: At 500 queries/day (~1 every 3 min), a 5s cache has zero practical
+//      accuracy impact but eliminates a COUNT(*) query from most requests
+const RATE_CACHE_TTL_MS = 5_000;
+const rateLimitCache = new Map();
+// WHAT: Check if a client has queries remaining today
+// WHY: Enforces tier-based daily limits without blocking the server
+export function checkRateLimit(clientId, tier) {
+    const limit = tier === "registered" ? REGISTERED_LIMIT : PUBLIC_LIMIT;
+    if (!rateLimitDb) {
+        return { allowed: true, tier, clientId, used: 0, limit, remaining: limit };
+    }
+    // Check cache first
+    const cacheKey = `${clientId}:${tier}`;
+    const cached = rateLimitCache.get(cacheKey);
+    if (cached && cached.expiry > Date.now()) {
+        return cached.result;
+    }
+    // WHAT: Count queries for this client today (UTC)
+    // WHY: Daily reset at midnight UTC keeps limits predictable
+    const today = new Date().toISOString().split("T")[0];
+    const todayStart = `${today}T00:00:00.000Z`;
+    const tomorrowStart = `${today}T23:59:59.999Z`;
+    const row = rateLimitDb
+        .prepare(`SELECT COUNT(*) as count FROM query_log
+       WHERE client_id = ? AND timestamp >= ? AND timestamp <= ?`)
+        .get(clientId, todayStart, tomorrowStart);
+    const used = row.count;
+    const remaining = Math.max(0, limit - used);
+    const result = {
+        allowed: used < limit,
+        tier,
+        clientId,
+        used,
+        limit,
+        remaining,
+    };
+    rateLimitCache.set(cacheKey, {
+        result,
+        expiry: Date.now() + RATE_CACHE_TTL_MS,
+    });
+    return result;
+}
+// WHAT: Format a rate limit exceeded message for the AI client
+// WHY: Clear messaging helps the AI explain the situation and suggest registration
+export function rateLimitMessage(result) {
+    if (result.tier === "public") {
+        return [
+            `Rate limit exceeded: ${result.used}/${result.limit} queries used today (public tier).`,
+            "",
+            "To get 500 queries/day, register with your email using the `register` tool.",
+            "Then add the API key to your MCP config as ASTGL_API_KEY.",
+            "",
+            "Rate limits reset at midnight UTC.",
+        ].join("\n");
+    }
+    return [
+        `Rate limit exceeded: ${result.used}/${result.limit} queries used today (registered tier).`,
+        "",
+        "Rate limits reset at midnight UTC.",
+    ].join("\n");
+}
+// --- Registration ---
+// WHAT: Register an email and generate an API key
+// WHY: Email capture builds an audience; API key enables higher rate limits
+export function registerClient(email) {
+    if (!rateLimitDb) {
+        return { success: false, message: "Registration database not available." };
+    }
+    // Basic email validation
+    if (!email || !email.includes("@") || !email.includes(".")) {
+        return { success: false, message: "Please provide a valid email address." };
+    }
+    const normalized = email.trim().toLowerCase();
+    // Check if already registered
+    const existing = rateLimitDb
+        .prepare("SELECT api_key FROM registrations WHERE email = ?")
+        .get(normalized);
+    if (existing) {
+        return {
+            success: true,
+            apiKey: existing.api_key,
+            email: normalized,
+            message: `Already registered. Your API key: ${existing.api_key}`,
+        };
+    }
+    // Generate API key
+    const apiKey = `astgl_${randomUUID().replace(/-/g, "")}`;
+    rateLimitDb
+        .prepare("INSERT INTO registrations (email, api_key, created_at) VALUES (?, ?, ?)")
+        .run(normalized, apiKey, new Date().toISOString());
+    return {
+        success: true,
+        apiKey,
+        email: normalized,
+        message: [
+            `Registered successfully! Your API key: ${apiKey}`,
+            "",
+            "Add it to your MCP server config to unlock 500 queries/day:",
+            "",
+            '```json',
+            '"env": { "ASTGL_API_KEY": "' + apiKey + '" }',
+            '```',
+        ].join("\n"),
+    };
+}
+export function closeRateLimitDb() {
+    if (rateLimitDb) {
+        rateLimitDb.close();
+        rateLimitDb = null;
+    }
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

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

package/dist/related-articles.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env tsx
+/**
+ * Internal linking automation via vector similarity.
+ *
+ * WHAT: Computes pairwise article similarity and injects related article links
+ * WHY: Cross-referencing boosts SEO, AI discoverability, and reader engagement
+ *
+ * Usage:
+ *   npm run related                        Compute + print JSON map
+ *   npm run related -- --inject            Also inject into Astro markdown frontmatter
+ *   npm run related -- --top 3             Number of related articles per article (default: 3)
+ *
+ * Requires: Ollama running with nomic-embed-text
+ */
+export {};