openalmanac 0.2.10 → 0.2.12

package/dist/server.js

@@ -3,13 +3,24 @@ 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 { registerPeopleTools } from "./tools/people.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);
+        console.error(`
+┌──────────────────────────────────────────────────┐
+│                                                  │
+│   Welcome to OpenAlmanac                         │
+│                                                  │
+│   Try asking your agent:                         │
+│                                                  │
+│   → "Write an Almanac article about CORS"        │
+│   → "Improve the Alan Turing article"            │
+│                                                  │
+│   Docs: openalmanac.org/contribute               │
+│                                                  │
+└──────────────────────────────────────────────────┘
+`);
     }
     const server = new FastMCP({
         name: "OpenAlmanac",
@@ -24,6 +35,16 @@ export function createServer() {
             "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" +
+            "Before writing articles with entity links, read https://www.openalmanac.org/ai-linking-guidelines.md " +
+            "— it covers wikilink syntax, slug conventions, and stub creation requirements.\n\n" +
+            "## Article Linking\n\n" +
+            "Every entity mentioned in an article should have a stub or article. Use [[slug|Display Text]] " +
+            "syntax for internal links. Before writing a [[link]], confirm the slug exists via search_articles " +
+            "or create it via create_stub. Links to non-existent slugs are stripped to plain text on push.\n\n" +
+            "Workflow: For each entity mentioned → search_articles (check if exists) → if not, create_stub " +
+            "with title, entity_type, headline, and a 2-4 sentence summary → then use [[slug|Display Text]] in your article.\n\n" +
+            "For people: call search_people to find their LinkedIn-backed slug, then create_stub. " +
+            "For topics/orgs/events: use descriptive kebab-case slugs (e.g. 'reinforcement-learning', 'openai').\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. " +
@@ -37,5 +58,6 @@ export function createServer() {
     registerArticleTools(server);
     registerResearchTools(server);
     registerCommunityTools(server);
+    registerPeopleTools(server);
     return server;
 }

package/dist/tools/articles.js

@@ -98,19 +98,79 @@ function ensureArticlesDir() {
 export function registerArticleTools(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.",
+        description: "Search existing OpenAlmanac articles and stubs. Use this to check if an article or stub already exists before creating one. " +
+            "Results include a 'stub' field (true/false) and 'entity_type' field. 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)"),
+            include_stubs: z.boolean().default(true).describe("Include stub articles in results (default true)"),
         }),
-        async execute({ query, limit, page }) {
-            const resp = await request("GET", "/api/search", {
-                params: { query, limit, page },
-            });
+        async execute({ query, limit, page, include_stubs }) {
+            const params = { query, limit, page };
+            if (!include_stubs)
+                params.include_stubs = "false";
+            const resp = await request("GET", "/api/search", { params });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
+    server.addTool({
+        name: "create_stub",
+        description: "Create a stub article — a placeholder for an entity that doesn't have a full article yet. " +
+            "Use this for every entity (person, organization, topic, etc.) you mention in an article. " +
+            "Stubs should include a meaningful summary and headline. " +
+            "Idempotent: if the slug already exists, returns the existing article/stub. Requires login.",
+        parameters: z.object({
+            slug: z
+                .string()
+                .min(1)
+                .max(500)
+                .describe("Unique kebab-case identifier. For people with LinkedIn: use their vanity ID (e.g. 'john-smith-4a8b2c1'). " +
+                "For others: descriptive kebab-case (e.g. 'reinforcement-learning', 'openai')"),
+            title: z.string().describe("Display title (e.g. 'John Smith', 'Reinforcement Learning')"),
+            entity_type: z
+                .enum(["person", "organization", "topic", "event", "creative_work", "place"])
+                .optional()
+                .describe("Entity type: 'person' for individuals, 'organization' for companies/institutions/nonprofits, " +
+                "'topic' for concepts/fields/technologies, 'event' for conferences/historical events, " +
+                "'creative_work' for books/papers/films/software, 'place' for cities/countries/landmarks"),
+            headline: z
+                .string()
+                .optional()
+                .describe("Short headline (e.g. 'Professor of CS at MIT', 'AI research laboratory')"),
+            image_url: z.string().optional().describe("Image URL for the entity"),
+            summary: z
+                .string()
+                .optional()
+                .describe("2-4 sentence summary of the entity. This becomes the stub page content. " +
+                "Be informative — include key facts, dates, and context."),
+        }),
+        async execute({ slug, title, entity_type, headline, image_url, summary }) {
+            if (!SLUG_RE.test(slug)) {
+                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$`);
+            }
+            const json = { slug, title };
+            if (entity_type)
+                json.entity_type = entity_type;
+            if (headline)
+                json.headline = headline;
+            if (image_url)
+                json.image_url = image_url;
+            if (summary)
+                json.summary = summary;
+            const resp = await request("POST", "/api/articles/stub", {
+                auth: true,
+                json,
+            });
+            const data = (await resp.json());
+            const statusMsg = data.status === "created"
+                ? "Stub created."
+                : data.status === "stub_exists"
+                    ? "Stub already exists."
+                    : "Full article already exists.";
+            return `${statusMsg} Slug: ${slug}\nUse [[${slug}|${title}]] to link to this entity.\n\n${JSON.stringify(data, null, 2)}`;
+        },
+    });
     server.addTool({
         name: "pull",
         description: "Download an article from OpenAlmanac to your local working directory (~/.openalmanac/articles/). " +
@@ -130,7 +190,12 @@ export function registerArticleTools(server) {
             const { frontmatter, content } = parseFrontmatter(markdown);
             const title = frontmatter.title || "(untitled)";
             const wordCount = content.trim().split(/\s+/).filter(Boolean).length;
-            return `Pulled "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.\n\n${WRITING_GUIDE}`;
+            const isStub = frontmatter.stub === true;
+            const stubNote = isStub
+                ? "\n\nThis is a STUB article — a placeholder that hasn't been fully written yet. " +
+                    "Fill in the content body with a complete article, then push to publish."
+                : "";
+            return `Pulled "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.${stubNote}\n\n${WRITING_GUIDE}`;
         },
     });
     server.addTool({

package/dist/tools/people.d.ts

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

package/dist/tools/people.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+export function registerPeopleTools(server) {
+    server.addTool({
+        name: "search_people",
+        description: "Search for people to find their canonical slug for linking. Returns candidates with name, headline, " +
+            "image, and location. Use the returned slug when creating stubs and [[links]] for people. Requires login.",
+        parameters: z.object({
+            query: z.string().describe("Search terms (e.g. 'John Smith MIT professor')"),
+            limit: z.number().min(1).max(10).default(5).describe("Max results (1-10, default 5)"),
+        }),
+        async execute({ query, limit }) {
+            const resp = await request("GET", "/api/people/search", {
+                auth: true,
+                params: { query, limit },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+}

package/package.json

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