@llmpedia/mcp 0.2.0

package/README.md

@@ -0,0 +1,66 @@
+# @llmpedia/mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets your own AI agent
+(Claude, Codex, …) create and maintain your [LLMpedia](https://api.llmpedia.org) wiki
+page. It is a thin layer over the LLMpedia public REST API — every tool is an
+authenticated HTTP call using your API key. No database access, no secrets beyond
+your key.
+
+## Setup
+
+Get your API key from **Dashboard → Connect your AI agent** (`/dashboard/api`).
+
+Add to your agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "llmpedia": {
+      "command": "npx",
+      "args": ["-y", "@llmpedia/mcp"],
+      "env": {
+        "LLMPEDIA_API_KEY": "llmp_sk_...",
+        "LLMPEDIA_BASE_URL": "https://api.llmpedia.org"
+      }
+    }
+  }
+}
+```
+
+`LLMPEDIA_BASE_URL` is optional (defaults to `https://api.llmpedia.org`).
+
+## Tools
+
+### Page tools
+
+| Tool | Description |
+|---|---|
+| `whoami` | Account, plan, topic quota, write budget. |
+| `list_pages` | Your pages (id, slug, title, status, language). |
+| `get_page` | One page's full structured content (by id or slug). |
+| `create_page` | Create a page from researched, structured content. |
+| `update_page` | Replace a page's content (maintenance). |
+| `publish_page` | Validate + publish. |
+| `unpublish_page` | Back to draft. |
+
+### Post tools
+
+| Tool | Description |
+|---|---|
+| `list_posts` | A page's blog/news/update posts (id = page id or slug). |
+| `get_post` | One post's full content (by post id). |
+| `create_post` | Create a blog/news/update post under a page, structured for AEO/GEO. |
+| `update_post` | Replace a post's content (slug/kind stay fixed to the target). |
+| `publish_post` | Validate + publish. |
+| `unpublish_post` | Back to draft. |
+
+Both the page and post content schemas are documented (with examples) at
+`<base-url>/api/v1/docs` — fetch it to see every field.
+
+## Develop
+
+```bash
+npm install
+npm run build      # compile to dist/
+LLMPEDIA_API_KEY=llmp_sk_... npm run dev
+```

package/dist/index.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+/**
+ * LLMpedia MCP server — thin tool layer over the public REST API (/api/v1). It
+ * holds NO database access and no app internals: every tool is an authenticated
+ * HTTP call using the user's API key. Configure it with:
+ *
+ *   LLMPEDIA_API_KEY   (required)  the user's llmpedia_key_… key
+ *   LLMPEDIA_BASE_URL  (optional)  defaults to https://llmpedia.org
+ */
+const API_KEY = process.env.LLMPEDIA_API_KEY;
+const BASE_URL = (process.env.LLMPEDIA_BASE_URL || "https://api.llmpedia.org").replace(/\/+$/, "");
+if (!API_KEY) {
+    console.error("LLMPEDIA_API_KEY is required. Get your key + docs at <site>/dashboard.");
+    process.exit(1);
+}
+async function api(method, path, body) {
+    const res = await fetch(`${BASE_URL}/api/v1${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "content-type": "application/json",
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    let data = text;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        /* keep raw text */
+    }
+    return { ok: res.ok, status: res.status, data };
+}
+function result(r) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }],
+        isError: !r.ok,
+    };
+}
+function withLanguage(path, language) {
+    return language ? `${path}?language=${encodeURIComponent(language)}` : path;
+}
+/** The page content object (mirrors GET /api/v1/docs). Lenient: extra keys pass. */
+const pageObject = z
+    .object({
+    title: z.string().describe("Canonical entity name."),
+    slug: z.string().optional().describe("URL slug; defaults from the title."),
+    language: z.string().optional().describe('Edition: "en" or "ko" (default "en").'),
+    entityType: z.string().optional().describe('Primary Schema.org type, e.g. "Organization".'),
+    schemaTypes: z.array(z.string()).optional(),
+    summary: z.string().describe("3–5 sentence canonical, citable summary."),
+    canonicalFacts: z
+        .array(z.object({
+        label: z.string(),
+        value: z.string(),
+        sourceUrl: z.string().nullable().optional(),
+    }))
+        .optional()
+        .describe("Quantified facts, each ideally with a deep source URL."),
+    sections: z
+        .array(z.object({
+        heading: z.string(),
+        body: z.string(),
+        sortOrder: z.number().optional(),
+    }))
+        .optional()
+        .describe("Prose sections (answer-first)."),
+    faqs: z
+        .array(z.object({ question: z.string(), answer: z.string() }))
+        .optional(),
+    aliases: z.array(z.string()).optional(),
+    sameAs: z.array(z.string()).optional().describe("Authoritative identity URLs."),
+    references: z
+        .array(z.object({
+        url: z.string(),
+        title: z.string().optional(),
+        supports: z.string().optional(),
+    }))
+        .optional()
+        .describe("Deep source URLs you used."),
+    disambiguation: z.array(z.string()).optional(),
+    seo: z
+        .object({ title: z.string().optional(), description: z.string().optional() })
+        .optional(),
+    aeo: z
+        .object({
+        answerSummary: z.string().optional(),
+        questionTargets: z.array(z.string()).optional(),
+    })
+        .optional(),
+    geo: z
+        .object({
+        llmSummary: z.string().optional(),
+        citationReadyClaims: z.array(z.string()).optional(),
+    })
+        .optional(),
+    schemaProperties: z.record(z.string(), z.any()).optional(),
+    sourceUrls: z.array(z.string()).optional(),
+    translationGroupId: z.string().optional(),
+})
+    .passthrough();
+const server = new McpServer({ name: "llmpedia", version: "0.1.0" });
+server.registerTool("whoami", {
+    title: "Who am I",
+    description: "Return the authenticated account, plan, topic quota, and write budget.",
+    inputSchema: {},
+}, async () => result(await api("GET", "/me")));
+server.registerTool("list_pages", {
+    title: "List pages",
+    description: "List the pages you own (id, slug, title, status, language).",
+    inputSchema: {},
+}, async () => result(await api("GET", "/pages")));
+server.registerTool("get_page", {
+    title: "Get page",
+    description: "Read one page's full structured content by id or by slug.",
+    inputSchema: {
+        id: z.string().describe("Page id (uuid) or slug."),
+        language: z.string().optional().describe('Required only when id is a slug. "en" | "ko".'),
+    },
+}, async ({ id, language }) => result(await api("GET", withLanguage(`/pages/${encodeURIComponent(id)}`, language))));
+server.registerTool("create_page", {
+    title: "Create page",
+    description: "Create a page from researched, structured content. See whoami for quota first.",
+    inputSchema: { page: pageObject },
+}, async ({ page }) => result(await api("POST", "/pages", page)));
+server.registerTool("update_page", {
+    title: "Update page",
+    description: "Replace a page's content (for maintenance). slug/language stay fixed.",
+    inputSchema: {
+        id: z.string().describe("Page id (uuid) or slug."),
+        language: z.string().optional().describe('Required only when id is a slug.'),
+        page: pageObject,
+    },
+}, async ({ id, language, page }) => result(await api("PUT", withLanguage(`/pages/${encodeURIComponent(id)}`, language), page)));
+server.registerTool("publish_page", {
+    title: "Publish page",
+    description: "Validate and publish a page so AI assistants can read and cite it.",
+    inputSchema: {
+        id: z.string().describe("Page id (uuid) or slug."),
+        language: z.string().optional(),
+    },
+}, async ({ id, language }) => result(await api("POST", withLanguage(`/pages/${encodeURIComponent(id)}/publish`, language))));
+server.registerTool("unpublish_page", {
+    title: "Unpublish page",
+    description: "Move a published page back to draft.",
+    inputSchema: {
+        id: z.string().describe("Page id (uuid) or slug."),
+        language: z.string().optional(),
+    },
+}, async ({ id, language }) => result(await api("POST", withLanguage(`/pages/${encodeURIComponent(id)}/unpublish`, language))));
+/** Timeline post (blog/news/update). Lenient: extra keys pass. */
+const postObject = z
+    .object({
+    kind: z.enum(["blog", "news", "update"]).optional().describe('Post kind (default "blog").'),
+    slug: z.string().optional().describe("URL slug; defaults from the title."),
+    title: z.string().describe("Headline."),
+    summary: z.string().optional().describe("Short dek / citable abstract."),
+    body: z.string().describe("Markdown body."),
+    faqs: z.array(z.object({ question: z.string(), answer: z.string() })).optional(),
+    sources: z
+        .array(z.object({ label: z.string().optional(), url: z.string() }))
+        .optional(),
+    entityType: z.string().optional().describe("Overrides kind→@type."),
+    schemaTypes: z.array(z.string()).optional(),
+    schemaProperties: z.record(z.string(), z.any()).optional(),
+    seo: z
+        .object({ title: z.string().optional(), description: z.string().optional() })
+        .optional(),
+    aeo: z.object({ answerSummary: z.string().optional() }).optional(),
+    geo: z.object({ llmSummary: z.string().optional() }).optional(),
+    byline: z.string().optional(),
+    translationGroupId: z.string().optional(),
+})
+    .passthrough();
+function postsPath(pageId, language, kind) {
+    const qs = new URLSearchParams();
+    if (language)
+        qs.set("language", language);
+    if (kind)
+        qs.set("kind", kind);
+    const q = qs.toString();
+    return `/pages/${encodeURIComponent(pageId)}/posts${q ? `?${q}` : ""}`;
+}
+server.registerTool("list_posts", {
+    title: "List posts",
+    description: "List blog/news/update posts under a page (id = uuid or slug).",
+    inputSchema: {
+        pageId: z.string().describe("Parent page id (uuid) or slug."),
+        language: z.string().optional().describe('Required only when pageId is a slug.'),
+        kind: z.enum(["blog", "news", "update"]).optional(),
+    },
+}, async ({ pageId, language, kind }) => result(await api("GET", postsPath(pageId, language, kind))));
+server.registerTool("get_post", {
+    title: "Get post",
+    description: "Read one post's full content by post id (uuid).",
+    inputSchema: { postId: z.string().describe("Post id (uuid).") },
+}, async ({ postId }) => result(await api("GET", `/posts/${encodeURIComponent(postId)}`)));
+server.registerTool("create_post", {
+    title: "Create post",
+    description: "Create a blog/news/update post under a page, structured for AEO/GEO.",
+    inputSchema: {
+        pageId: z.string().describe("Parent page id (uuid) or slug."),
+        language: z.string().optional().describe('Required only when pageId is a slug.'),
+        post: postObject,
+    },
+}, async ({ pageId, language, post }) => result(await api("POST", postsPath(pageId, language), post)));
+server.registerTool("update_post", {
+    title: "Update post",
+    description: "Replace a post's content (slug/kind stay fixed to the target).",
+    inputSchema: { postId: z.string().describe("Post id (uuid)."), post: postObject },
+}, async ({ postId, post }) => result(await api("PUT", `/posts/${encodeURIComponent(postId)}`, post)));
+server.registerTool("publish_post", {
+    title: "Publish post",
+    description: "Validate and publish a post so AI assistants can read and cite it.",
+    inputSchema: { postId: z.string().describe("Post id (uuid).") },
+}, async ({ postId }) => result(await api("POST", `/posts/${encodeURIComponent(postId)}/publish`)));
+server.registerTool("unpublish_post", {
+    title: "Unpublish post",
+    description: "Move a published post back to draft.",
+    inputSchema: { postId: z.string().describe("Post id (uuid).") },
+}, async ({ postId }) => result(await api("POST", `/posts/${encodeURIComponent(postId)}/unpublish`)));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`llmpedia-mcp connected (base: ${BASE_URL})`);
+}
+main().catch((err) => {
+    console.error("llmpedia-mcp failed to start:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@llmpedia/mcp",
+  "version": "0.2.0",
+  "description": "MCP server for creating and maintaining LLMpedia wiki pages with your own AI agent.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "llmpedia-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "node --import tsx src/index.ts",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}