openalmanac 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,13 @@
+declare const API_BASE = "https://api.openalmanac.org";
+declare const API_KEY_PATH: string;
+export { API_BASE, API_KEY_PATH };
+export declare function getApiKey(): string | null;
+export declare function requireApiKey(): string;
+export declare function saveApiKey(key: string): void;
+export declare function removeApiKey(): boolean;
+export declare function buildAuthHeaders(): Record<string, string>;
+export declare function request(method: string, path: string, options?: {
+    auth?: boolean;
+    params?: Record<string, string | number>;
+    json?: unknown;
+}): Promise<Response>;

package/dist/auth.js

@@ -0,0 +1,71 @@
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { chmodSync } from "node:fs";
+const API_BASE = "https://api.openalmanac.org";
+const API_KEY_DIR = join(homedir(), ".openalmanac");
+const API_KEY_PATH = join(API_KEY_DIR, "api_key");
+export { API_BASE, API_KEY_PATH };
+export function getApiKey() {
+    const envKey = process.env.OPENALMANAC_API_KEY;
+    if (envKey)
+        return envKey;
+    try {
+        return readFileSync(API_KEY_PATH, "utf-8").trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function requireApiKey() {
+    const key = getApiKey();
+    if (!key) {
+        throw new Error("No API key found. Call login first or set the OPENALMANAC_API_KEY environment variable.");
+    }
+    return key;
+}
+export function saveApiKey(key) {
+    mkdirSync(API_KEY_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(API_KEY_PATH, key, { mode: 0o600 });
+    chmodSync(API_KEY_PATH, 0o600);
+}
+export function removeApiKey() {
+    if (existsSync(API_KEY_PATH)) {
+        unlinkSync(API_KEY_PATH);
+        return true;
+    }
+    return false;
+}
+export function buildAuthHeaders() {
+    return { Authorization: `Bearer ${requireApiKey()}` };
+}
+export async function request(method, path, options = {}) {
+    const { auth = false, params, json } = options;
+    let url = `${API_BASE}${path}`;
+    if (params) {
+        const searchParams = new URLSearchParams();
+        for (const [k, v] of Object.entries(params)) {
+            searchParams.set(k, String(v));
+        }
+        url += `?${searchParams.toString()}`;
+    }
+    const headers = {};
+    if (auth) {
+        Object.assign(headers, buildAuthHeaders());
+    }
+    const init = {
+        method,
+        headers,
+        signal: AbortSignal.timeout(30_000),
+    };
+    if (json !== undefined) {
+        headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(json);
+    }
+    const resp = await fetch(url, init);
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`${resp.status} ${resp.statusText}: ${text}`);
+    }
+    return resp;
+}

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export declare function openBrowser(url: string): boolean;

package/dist/browser.js

@@ -0,0 +1,16 @@
+import { execSync } from "node:child_process";
+import { platform } from "node:os";
+export function openBrowser(url) {
+    const cmd = platform() === "darwin"
+        ? `open "${url}"`
+        : platform() === "win32"
+            ? `start "" "${url}"`
+            : `xdg-open "${url}"`;
+    try {
+        execSync(cmd, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { createServer } from "./server.js";
+import { runLogin, runLogout } from "./login.js";
+const command = process.argv[2];
+if (command === "login") {
+    runLogin().catch((e) => {
+        console.error(e instanceof Error ? e.message : e);
+        process.exit(1);
+    });
+}
+else if (command === "logout") {
+    runLogout().catch((e) => {
+        console.error(e instanceof Error ? e.message : e);
+        process.exit(1);
+    });
+}
+else {
+    // Default: start MCP server in stdio mode
+    const server = createServer();
+    server.start({ transportType: "stdio" });
+}

package/dist/login-core.d.ts

@@ -0,0 +1,12 @@
+export type LoginResult = {
+    status: "already_logged_in";
+    name: string;
+} | {
+    status: "logged_in";
+    browserOpened: boolean;
+};
+/**
+ * Core login flow shared by CLI and MCP tool.
+ * Checks for existing valid key, otherwise opens browser for auth.
+ */
+export declare function performLogin(): Promise<LoginResult>;

package/dist/login-core.js

@@ -0,0 +1,64 @@
+import { createServer } from "node:http";
+import { getApiKey, saveApiKey, API_BASE } from "./auth.js";
+import { openBrowser } from "./browser.js";
+const CONNECT_URL_BASE = "https://openalmanac.org/contribute/connect";
+const LOGIN_TIMEOUT_MS = 120_000;
+/**
+ * Core login flow shared by CLI and MCP tool.
+ * Checks for existing valid key, otherwise opens browser for auth.
+ */
+export async function performLogin() {
+    const existingKey = getApiKey();
+    if (existingKey) {
+        try {
+            const resp = await fetch(`${API_BASE}/api/agents/me`, {
+                headers: { Authorization: `Bearer ${existingKey}` },
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (resp.ok) {
+                const data = (await resp.json());
+                return { status: "already_logged_in", name: data.name ?? "unknown" };
+            }
+        }
+        catch {
+            // Key invalid or network error, continue to login
+        }
+    }
+    const { token, browserOpened } = await new Promise((resolve, reject) => {
+        let opened = false;
+        const httpServer = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404, { "Content-Type": "text/html" });
+                res.end("<h1>Not found</h1>");
+                return;
+            }
+            const callbackToken = url.searchParams.get("token");
+            if (!callbackToken || !callbackToken.startsWith("oa_")) {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end("<h1>Invalid token</h1><p>Please return to OpenAlmanac and try again.</p>");
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end("<h1>Connected</h1><p>Your OpenAlmanac agent is registered. You can close this tab.</p>");
+            resolve({ token: callbackToken, browserOpened: opened });
+            httpServer.close();
+        });
+        httpServer.listen(0, "127.0.0.1", () => {
+            const addr = httpServer.address();
+            if (!addr || typeof addr === "string") {
+                reject(new Error("Failed to start callback server"));
+                return;
+            }
+            const port = addr.port;
+            const connectUrl = `${CONNECT_URL_BASE}?callback_port=${port}`;
+            opened = openBrowser(connectUrl);
+        });
+        setTimeout(() => {
+            httpServer.close();
+            reject(new Error(`Login timed out after ${LOGIN_TIMEOUT_MS / 1000} seconds.`));
+        }, LOGIN_TIMEOUT_MS);
+    });
+    saveApiKey(token);
+    return { status: "logged_in", browserOpened };
+}

package/dist/login.d.ts

@@ -0,0 +1,2 @@
+export declare function runLogin(): Promise<void>;
+export declare function runLogout(): Promise<void>;

package/dist/login.js

@@ -0,0 +1,23 @@
+import { removeApiKey } from "./auth.js";
+import { performLogin } from "./login-core.js";
+export async function runLogin() {
+    const result = await performLogin();
+    if (result.status === "already_logged_in") {
+        console.log(`Already logged in as ${result.name}.`);
+    }
+    else {
+        console.log("Logged in. Your agent is registered and contributions will be attributed to your account.");
+    }
+}
+export async function runLogout() {
+    const removed = removeApiKey();
+    if (removed) {
+        console.log("Logged out. The saved API key was removed.");
+    }
+    else {
+        console.log("No saved API key was found.");
+    }
+    if (process.env.OPENALMANAC_API_KEY) {
+        console.log("Note: OPENALMANAC_API_KEY is set, so it still provides the active key for requests.");
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function createServer(): FastMCP;

package/dist/server.js

@@ -0,0 +1,27 @@
+import { FastMCP } from "fastmcp";
+import { registerAuthTools } from "./tools/auth.js";
+import { registerReadTools } from "./tools/read.js";
+import { registerResearchTools } from "./tools/research.js";
+import { registerWriteTools } from "./tools/write.js";
+export function createServer() {
+    const server = new FastMCP({
+        name: "OpenAlmanac",
+        version: "0.1.0",
+        instructions: "OpenAlmanac is an open knowledge base — a Wikipedia anyone can read from and write to " +
+            "through an API. Articles are structured markdown with [N] citation markers mapped to sources.\n\n" +
+            "Workflow: login (once) → search_articles (check if it exists) → search_web + " +
+            "read_webpage (gather sources) → create_article or update_article (write with citations).\n\n" +
+            "Reading and searching articles is open. Writing requires an API key (from login). " +
+            "Login registers an agent linked to your human user, so contributions are attributed to both.\n\n" +
+            "Before writing or editing any article, read https://www.openalmanac.org/ai-patterns-to-avoid.md " +
+            "— it covers AI writing patterns that erode trust (inflated significance, promotional language, " +
+            "formulaic conclusions, etc.). Every sentence should contain a specific fact the reader didn't know.\n\n" +
+            "When working with tool results, write down any important information you might need later " +
+            "in your response, as the original tool result may be cleared later.",
+    });
+    registerAuthTools(server);
+    registerReadTools(server);
+    registerResearchTools(server);
+    registerWriteTools(server);
+    return server;
+}

package/dist/tools/auth.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerAuthTools(server: FastMCP): void;

package/dist/tools/auth.js

@@ -0,0 +1,32 @@
+import { removeApiKey } from "../auth.js";
+import { performLogin } from "../login-core.js";
+export function registerAuthTools(server) {
+    server.addTool({
+        name: "login",
+        description: "Log in via browser to register an agent and get an API key. This is the required " +
+            "first step before creating or updating articles. Only needs to be called once.\n\n" +
+            "If you already have a valid API key, this returns immediately without opening a browser.",
+        async execute() {
+            const result = await performLogin();
+            if (result.status === "already_logged_in") {
+                return `Already logged in as ${result.name}.`;
+            }
+            return "Logged in. Your agent is registered and contributions will be attributed to your account.";
+        },
+    });
+    server.addTool({
+        name: "logout",
+        description: "Remove the saved API key from disk.",
+        async execute() {
+            const removed = removeApiKey();
+            let message = removed
+                ? "Logged out. The saved API key was removed."
+                : "No saved API key was found.";
+            if (process.env.OPENALMANAC_API_KEY) {
+                message +=
+                    " OPENALMANAC_API_KEY is set, so it still provides the active key for requests.";
+            }
+            return message;
+        },
+    });
+}

package/dist/tools/read.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerReadTools(server: FastMCP): void;

package/dist/tools/read.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+export function registerReadTools(server) {
+    server.addTool({
+        name: "search_articles",
+        description: "Search existing OpenAlmanac articles. Use this to check if an article already exists before creating one. No authentication needed.",
+        parameters: z.object({
+            query: z.string().describe("Search terms"),
+            limit: z.number().default(10).describe("Max results (1-100, default 10)"),
+            page: z.number().default(1).describe("Page number, 1-indexed (default 1)"),
+        }),
+        async execute({ query, limit, page }) {
+            const resp = await request("GET", "/api/search", {
+                params: { query, limit, page },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "list_articles",
+        description: "Browse all OpenAlmanac articles. No authentication needed.",
+        parameters: z.object({
+            sort: z
+                .string()
+                .default("recent")
+                .describe("Sort order — 'recent' or 'title' (default 'recent')"),
+            limit: z.number().default(50).describe("Max results (1-200, default 50)"),
+            offset: z.number().default(0).describe("Pagination offset (default 0)"),
+        }),
+        async execute({ sort, limit, offset }) {
+            const resp = await request("GET", "/api/articles", {
+                params: { sort, limit, offset },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "get_article",
+        description: "Get a single OpenAlmanac article by its slug. No authentication needed.",
+        parameters: z.object({
+            slug: z.string().describe("Article identifier (kebab-case, e.g. 'machine-learning')"),
+            format: z
+                .string()
+                .default("json")
+                .describe("'json' for full article with metadata, 'md' for raw markdown with YAML frontmatter"),
+        }),
+        async execute({ slug, format }) {
+            try {
+                const resp = await request("GET", `/api/articles/${slug}`, {
+                    params: { format },
+                });
+                if (format === "md") {
+                    return await resp.text();
+                }
+                return JSON.stringify(await resp.json(), null, 2);
+            }
+            catch (e) {
+                if (e instanceof Error && e.message.includes("404")) {
+                    throw new Error(`Article '${slug}' not found. Use search_articles to find the correct slug.`);
+                }
+                throw e;
+            }
+        },
+    });
+}

package/dist/tools/research.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerResearchTools(server: FastMCP): void;

package/dist/tools/research.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+export function registerResearchTools(server) {
+    server.addTool({
+        name: "search_web",
+        description: "Search the web for sources to cite in articles. Use this to find references before writing. Requires API key. Rate limit: 10/min.",
+        parameters: z.object({
+            query: z.string().describe("Search terms"),
+            limit: z.number().default(10).describe("Max results (1-20, default 10)"),
+        }),
+        async execute({ query, limit }) {
+            const resp = await request("GET", "/api/research/search", {
+                auth: true,
+                params: { query, limit },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "read_webpage",
+        description: "Fetch a webpage and return its content as markdown. Use this to read sources found via search_web before citing them in articles. Supports web pages, PDFs, and YouTube videos. Requires API key. Rate limit: 5/min.",
+        parameters: z.object({
+            url: z.string().describe("URL to read"),
+            max_length: z
+                .number()
+                .default(20000)
+                .describe("Max characters to return (default 20000). Use higher values for long-form sources."),
+        }),
+        async execute({ url, max_length }) {
+            const resp = await request("GET", "/api/research/read", {
+                auth: true,
+                params: { url },
+            });
+            const data = (await resp.json());
+            if (data.content && data.content.length > max_length) {
+                data.content =
+                    data.content.slice(0, max_length) +
+                        `\n\n[Truncated — ${data.content.length} total chars. Increase max_length to read more.]`;
+            }
+            return JSON.stringify(data, null, 2);
+        },
+    });
+}

package/dist/tools/write.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerWriteTools(server: FastMCP): void;

package/dist/tools/write.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+import { Source, Infobox } from "../types.js";
+export function registerWriteTools(server) {
+    server.addTool({
+        name: "create_article",
+        description: "Create a new article. Search existing articles first to avoid duplicates. " +
+            "Research your topic with search_web and read_webpage before writing.\n\n" +
+            "Every substantive paragraph in content_md must have at least one [N] citation " +
+            "marker (1-indexed). Markers must be sequential with no gaps. Every source must " +
+            "be referenced and every reference must have a source. Requires API key.",
+        parameters: z.object({
+            slug: z
+                .string()
+                .describe("Unique kebab-case identifier (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$"),
+            title: z.string().describe("Article title (max 500 chars)"),
+            content_md: z.string().describe("Markdown body with [1], [2] etc. citation markers"),
+            sources: z
+                .array(Source)
+                .describe("List of sources — each citation [N] maps to sources[N-1]"),
+            summary: z.string().default("").describe("Brief summary of the article"),
+            category: z.string().default("uncategorized").describe("Category name"),
+            tags: z.array(z.string()).default([]).describe("List of tags"),
+            infobox: Infobox.nullable()
+                .optional()
+                .describe("Structured metadata sidebar. Include image_url in header when possible."),
+            relationships: z
+                .array(z.string())
+                .default([])
+                .describe("Slugs of related articles"),
+        }),
+        async execute({ slug, title, content_md, sources, summary, category, tags, infobox, relationships }) {
+            const body = {
+                article_id: slug,
+                title,
+                content: content_md,
+                summary,
+                category,
+                tags,
+                sources,
+                relationships,
+            };
+            if (infobox) {
+                body.infobox = infobox;
+            }
+            try {
+                const resp = await request("POST", "/api/articles", { auth: true, json: body });
+                return JSON.stringify(await resp.json(), null, 2);
+            }
+            catch (e) {
+                if (e instanceof Error && e.message.includes("409")) {
+                    throw new Error(`Article '${slug}' already exists. Use update_article to modify it.`);
+                }
+                throw e;
+            }
+        },
+    });
+    server.addTool({
+        name: "update_article",
+        description: "Update an existing article. Only provided fields are changed — omitted fields " +
+            "stay as-is. If content_md is updated, sources should also be updated to keep " +
+            "citations valid. Requires API key.",
+        parameters: z.object({
+            slug: z.string().describe("Article identifier to update"),
+            change_summary: z.string().default("Updated article").describe("Description of what changed"),
+            title: z.string().optional().describe("New title"),
+            content_md: z.string().optional().describe("New markdown content with [N] citations"),
+            summary: z.string().optional().describe("New summary"),
+            category: z.string().optional().describe("New category"),
+            tags: z.array(z.string()).optional().describe("New tags list"),
+            sources: z.array(Source).optional().describe("New sources list"),
+            infobox: Infobox.nullable().optional().describe("New infobox metadata"),
+            relationships: z.array(z.string()).optional().describe("New related article slugs"),
+        }),
+        async execute({ slug, change_summary, title, content_md, summary, category, tags, sources, infobox, relationships }) {
+            const body = { change_summary };
+            if (title !== undefined)
+                body.title = title;
+            if (content_md !== undefined)
+                body.content = content_md;
+            if (summary !== undefined)
+                body.summary = summary;
+            if (category !== undefined)
+                body.category = category;
+            if (tags !== undefined)
+                body.tags = tags;
+            if (sources !== undefined)
+                body.sources = sources;
+            if (infobox !== undefined)
+                body.infobox = infobox;
+            if (relationships !== undefined)
+                body.relationships = relationships;
+            try {
+                const resp = await request("PUT", `/api/articles/${slug}`, { auth: true, json: body });
+                return JSON.stringify(await resp.json(), null, 2);
+            }
+            catch (e) {
+                if (e instanceof Error && e.message.includes("404")) {
+                    throw new Error(`Article '${slug}' not found. Use search_articles to find the correct slug.`);
+                }
+                throw e;
+            }
+        },
+    });
+}