openalmanac 0.2.5 → 0.2.8

package/dist/auth.d.ts

@@ -1,4 +1,4 @@
-declare const API_BASE = "https://api.openalmanac.org";
+declare const API_BASE: string;
 declare const API_KEY_PATH: string;
 declare const ARTICLES_DIR: string;
 export { API_BASE, API_KEY_PATH, ARTICLES_DIR };
@@ -6,6 +6,13 @@ export declare function getApiKey(): string | null;
 export declare function requireApiKey(): string;
 export declare function saveApiKey(key: string): void;
 export declare function removeApiKey(): boolean;
+export type AuthStatus = {
+    loggedIn: true;
+    name: string;
+} | {
+    loggedIn: false;
+};
+export declare function getAuthStatus(): Promise<AuthStatus>;
 export declare function buildAuthHeaders(): Record<string, string>;
 export declare function request(method: string, path: string, options?: {
     auth?: boolean;

package/dist/auth.js

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync } from "
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { chmodSync } from "node:fs";
-const API_BASE = "https://api.openalmanac.org";
+const API_BASE = process.env.OPENALMANAC_API_BASE || "https://openalmanac.org/api/proxy";
 const API_KEY_DIR = join(homedir(), ".openalmanac");
 const API_KEY_PATH = join(API_KEY_DIR, "api_key");
 const ARTICLES_DIR = join(homedir(), ".openalmanac", "articles");
@@ -37,6 +37,25 @@ export function removeApiKey() {
     }
     return false;
 }
+export async function getAuthStatus() {
+    const key = getApiKey();
+    if (!key)
+        return { loggedIn: false };
+    try {
+        const resp = await fetch(`${API_BASE}/api/agents/me`, {
+            headers: { Authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (resp.ok) {
+            const data = (await resp.json());
+            return { loggedIn: true, name: data.name ?? "unknown" };
+        }
+    }
+    catch {
+        // Key invalid or network error
+    }
+    return { loggedIn: false };
+}
 export function buildAuthHeaders() {
     return { Authorization: `Bearer ${requireApiKey()}` };
 }

package/dist/server.js

@@ -2,7 +2,15 @@ import { FastMCP } from "fastmcp";
 import { registerAuthTools } from "./tools/auth.js";
 import { registerArticleTools } from "./tools/articles.js";
 import { registerResearchTools } from "./tools/research.js";
+import { registerCommunityTools } from "./tools/communities.js";
+import { getApiKey } from "./auth.js";
+import { openBrowser } from "./browser.js";
+const NEXT_STEPS_URL = "https://www.openalmanac.org/contribute/next-steps";
 export function createServer() {
+    // On first run (no API key), open the next-steps page so the user knows what to do
+    if (!getApiKey()) {
+        openBrowser(NEXT_STEPS_URL);
+    }
     const server = new FastMCP({
         name: "OpenAlmanac",
         version: "0.1.0",
@@ -18,11 +26,16 @@ export function createServer() {
             "formulaic conclusions, etc.). Every sentence should contain a specific fact the reader didn't know.\n\n" +
             "After creating an article, always share the exact URL from the push response with the user. " +
             "This URL includes a celebration page for the newly created article.\n\n" +
+            "After pushing an article, call search_communities to find relevant communities. " +
+            "Analyze the article content against community names and descriptions, then suggest " +
+            "communities to the user. If the user confirms or skips, call link_article with the " +
+            "suggested community slugs. If the user picks specific ones, use those instead.\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);
     registerArticleTools(server);
     registerResearchTools(server);
+    registerCommunityTools(server);
     return server;
 }

package/dist/tools/articles.js

@@ -2,8 +2,9 @@ import { z } from "zod";
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { stringify as yamlStringify } from "yaml";
-import { request, ARTICLES_DIR } from "../auth.js";
+import { request, ARTICLES_DIR, getAuthStatus } from "../auth.js";
 import { validateArticle, parseFrontmatter } from "../validate.js";
+import { openBrowser } from "../browser.js";
 const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const WRITING_GUIDE = `
 ## Article structure
@@ -15,6 +16,7 @@ title: Article Title
 sources:
   - url: https://example.com
     title: Source Title
+    accessed_date: "2025-01-15"
 infobox:
   header:
     image_url: https://...         # optional hero image
@@ -25,34 +27,40 @@ infobox:
       - key: Occupation
         value: Scientist
     links:
-      - label: Official site
-        url: https://...
+      - https://example.com
   sections:
     - type: timeline               # chronological events
       title: Career Timeline
       items:
-        - primary: "2010"
-          value: Started company
-    - type: list                   # bullet list
+        - primary: "Started company"
+          period: "2010"
+          location: "San Francisco"
+    - type: list                   # key figures, works, features
       title: Known For
       items:
-        - value: First achievement
-        - value: Second achievement
+        - title: First achievement
+        - title: Second achievement
+          subtitle: Additional detail
     - type: tags                   # inline tags/chips
       title: Genres
       items:
-        - value: Rock
-        - value: Jazz
+        - Rock
+        - Jazz
     - type: grid                   # image grid
       title: Gallery
       items:
-        - image_url: https://...
-          value: Caption
-    - type: table                  # rows with label+value
+        - title: Caption
+          image_url: https://...
+    - type: table                  # structured comparison
       title: Statistics
       items:
-        - label: Height
-          value: "6'2\\""
+        headers:
+          - Name
+          - Value
+        rows:
+          - cells:
+              - Height
+              - "6'2\\""
     - type: key_value              # simple key-value pairs
       title: Quick Facts
       items:
@@ -189,18 +197,23 @@ export function registerArticleTools(server) {
             });
             const data = (await resp.json());
             const articleUrl = `https://www.openalmanac.org/article/${slug}?celebrate=true`;
-            return `Pushed successfully.\n${articleUrl}\n${JSON.stringify(data, null, 2)}`;
+            openBrowser(articleUrl);
+            return `Pushed successfully.\n\nArticle URL (share this exact link with the user): ${articleUrl}\n\n${JSON.stringify(data, null, 2)}`;
         },
     });
     server.addTool({
         name: "status",
-        description: "List all article files in your local working directory (~/.openalmanac/articles/). " +
-            "Shows filename, title, file size, and last modified time. No API calls.",
+        description: "Show login status and list all article files in your local working directory (~/.openalmanac/articles/). " +
+            "Shows auth state, filename, title, file size, and last modified time.",
         async execute() {
             ensureArticlesDir();
+            const auth = await getAuthStatus();
+            const authLine = auth.loggedIn
+                ? `Logged in as ${auth.name}.`
+                : "Not logged in. Use login to authenticate.";
             const files = readdirSync(ARTICLES_DIR).filter((f) => f.endsWith(".md"));
             if (files.length === 0) {
-                return `No articles in ${ARTICLES_DIR}\nUse pull to download an article or new to create one.`;
+                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use pull or new to get started)`;
             }
             const rows = [];
             for (const file of files) {
@@ -215,7 +228,7 @@ export function registerArticleTools(server) {
                 const modified = stat.mtime.toISOString().slice(0, 16).replace("T", " ");
                 rows.push(`  ${file}  —  "${title}"  (${size}, modified ${modified})`);
             }
-            return `${files.length} article(s) in ${ARTICLES_DIR}:\n${rows.join("\n")}`;
+            return `${authLine}\n\nLocal articles (${files.length} file(s) in ${ARTICLES_DIR}):\n${rows.join("\n")}`;
         },
     });
 }

package/dist/tools/communities.d.ts

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

package/dist/tools/communities.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+export function registerCommunityTools(server) {
+    server.addTool({
+        name: "search_communities",
+        description: "Search or list OpenAlmanac communities. Returns community names, descriptions, and member counts. " +
+            "Use this after pushing an article to find relevant communities for auto-linking. No authentication needed.",
+        parameters: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe("Search term (case-insensitive match on name, slug, or description). Omit to list all."),
+            sort: z
+                .enum(["popular", "newest"])
+                .default("popular")
+                .describe("Sort order (default: popular)"),
+            limit: z
+                .number()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Max results (1-100, default 20)"),
+        }),
+        async execute({ query, sort, limit }) {
+            const params = { sort, limit };
+            if (query)
+                params.query = query;
+            const resp = await request("GET", "/api/communities", { params });
+            const data = (await resp.json());
+            const communities = data.communities.map((c) => ({
+                slug: c.slug,
+                name: c.name,
+                description: c.description,
+                member_count: c.member_count,
+                created_at: c.created_at,
+            }));
+            return `Found ${data.total} communities:\n\n${JSON.stringify(communities, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "create_community",
+        description: "Create a new OpenAlmanac community. Requires login and at least 1 published article. " +
+            "Communities are spaces where articles can be curated and discussed around a topic.",
+        parameters: z.object({
+            name: z.string().min(1).max(100).describe("Community name (1-100 chars)"),
+            slug: z
+                .string()
+                .min(1)
+                .max(100)
+                .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+                .describe("Unique kebab-case identifier (e.g. 'machine-learning')"),
+            description: z
+                .string()
+                .min(1)
+                .max(2000)
+                .describe("What the community is about (1-2000 chars)"),
+        }),
+        async execute({ name, slug, description }) {
+            const resp = await request("POST", "/api/communities", {
+                auth: true,
+                json: { name, slug, description },
+            });
+            const data = (await resp.json());
+            const communityUrl = `https://www.openalmanac.org/communities/${slug}`;
+            return `Community created!\n\nURL: ${communityUrl}\n\n${JSON.stringify(data, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "create_post",
+        description: "Create a post in an OpenAlmanac community. Requires login and community membership. " +
+            "If you get a 403 error, you need to join the community first.",
+        parameters: z.object({
+            community_slug: z.string().describe("Community slug (e.g. 'machine-learning')"),
+            title: z.string().min(1).max(300).describe("Post title (1-300 chars)"),
+            body: z.string().max(10000).default("").describe("Post body (max 10000 chars)"),
+            flair: z
+                .enum(["discussion", "article-request", "question", "announcement"])
+                .optional()
+                .describe("Post flair/category"),
+        }),
+        async execute({ community_slug, title, body, flair }) {
+            const json = { title, body };
+            if (flair)
+                json.flair = flair;
+            const resp = await request("POST", `/api/communities/${community_slug}/posts`, {
+                auth: true,
+                json,
+            });
+            const data = (await resp.json());
+            const postUrl = `https://www.openalmanac.org/communities/${community_slug}/post/${data.id}`;
+            return `Post created!\n\nURL: ${postUrl}\n\n${JSON.stringify(data, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "link_article",
+        description: "Link an article to one or more communities. Use this after pushing an article to connect it " +
+            "with relevant communities. Call search_communities first to find matching communities. " +
+            "Idempotent — already-linked articles are reported but don't cause errors. Requires login.",
+        parameters: z.object({
+            article_id: z.string().describe("Article slug/ID to link (e.g. 'machine-learning')"),
+            community_slugs: z
+                .array(z.string())
+                .min(1)
+                .max(50)
+                .describe("List of community slugs to link the article to (max 50)"),
+        }),
+        async execute({ article_id, community_slugs }) {
+            const resp = await request("POST", `/api/articles/${article_id}/auto-link`, {
+                auth: true,
+                json: { community_slugs },
+            });
+            const data = (await resp.json());
+            const lines = [];
+            if (data.linked.length > 0) {
+                lines.push(`Linked to ${data.linked.length} communities: ${data.linked.join(", ")}`);
+            }
+            if (data.failed.length > 0) {
+                const failLines = data.failed.map((f) => `  ${f.slug}: ${f.reason}`);
+                lines.push(`Failed (${data.failed.length}):\n${failLines.join("\n")}`);
+            }
+            if (lines.length === 0) {
+                lines.push("No communities to link.");
+            }
+            return lines.join("\n\n");
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openalmanac",
-  "version": "0.2.5",
+  "version": "0.2.8",
   "description": "OpenAlmanac — pull, edit, and push articles to the open knowledge base",
   "type": "module",
   "bin": {