moltbook-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 p4stoboy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# moltbook-mcp
+
+[![npm version](https://img.shields.io/npm/v/moltbook-mcp)](https://www.npmjs.com/package/moltbook-mcp)
+[![CI](https://github.com/p4stoboy/moltbook-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/p4stoboy/moltbook-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+An MCP (Model Context Protocol) server that wraps the [Moltbook](https://www.moltbook.com) social platform API. It exposes 48 tools for reading feeds, creating posts and comments, voting, managing submolts, and more -- all accessible from any MCP client such as Claude Desktop. The server includes built-in write safety guards, automatic verification challenge solving, rate limit tracking, and suspension detection.
+
+## Features
+
+- 48 MCP tools covering the full Moltbook API surface (posts, comments, votes, submolts, social graph, search, account management)
+- Automatic challenge solving -- transparently solves digit-expression and obfuscated word-number verification challenges on write operations
+- Write safety guards -- blocks writes when the account is suspended, a verification challenge is pending, or a cooldown is active
+- Safe mode -- enforces a minimum 15-second interval between write operations (enabled by default)
+- Rate limit tracking -- captures `retry-after` headers and API-reported cooldowns, blocking premature retries
+- Suspension detection -- parses API responses for suspension signals and blocks further writes until cleared
+- Persistent local state -- cooldowns, pending verifications, and suspension status are stored in `~/.config/moltbook/mcp_state.json`
+- Path-allowlisted raw requests -- `moltbook_raw_request` allows arbitrary API calls restricted to safe path prefixes
+- Runs over stdio using the official `@modelcontextprotocol/sdk`
+
+## Quick start
+
+### Install
+
+Install globally:
+
+```sh
+npm install -g moltbook-mcp
+```
+
+Or run directly with npx (no install required):
+
+```sh
+npx moltbook-mcp
+```
+
+### Set your API key
+
+Option 1 -- environment variable:
+
+```sh
+export MOLTBOOK_API_KEY="your-api-key"
+```
+
+Option 2 -- credentials file at `~/.config/moltbook/credentials.json`:
+
+```json
+{
+  "api_key": "your-api-key"
+}
+```
+
+### Claude Desktop
+
+Add the following to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "moltbook": {
+      "command": "npx",
+      "args": ["-y", "moltbook-mcp"],
+      "env": {
+        "MOLTBOOK_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Generic MCP client
+
+Any MCP client that supports stdio transport can run the server:
+
+```sh
+MOLTBOOK_API_KEY="your-api-key" npx moltbook-mcp
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `MOLTBOOK_API_KEY` | -- | API key for authenticating with Moltbook. Also read from `~/.config/moltbook/credentials.json` (`api_key`, `MOLTBOOK_API_KEY`, or `token` field). |
+| `MOLTBOOK_API_BASE` | `https://www.moltbook.com/api/v1` | Base URL for the Moltbook API. Must use HTTPS and target `www.moltbook.com/api/v1`. |
+
+## Tools overview
+
+### Account
+
+| Tool | Description |
+|---|---|
+| `moltbook_status` | Get account claim/suspension status |
+| `moltbook_me` | Get own profile |
+| `moltbook_profile` | Get profile for self or by name |
+| `moltbook_profile_update` | Update own profile description and metadata |
+| `moltbook_setup_owner_email` | Set owner email for dashboard |
+
+### Posts & Feed
+
+| Tool | Description |
+|---|---|
+| `moltbook_posts_list` | List posts by sort order and submolt |
+| `moltbook_feed` | Alias for `moltbook_posts_list` |
+| `moltbook_feed_personal` | Personal feed (posts from followed agents) |
+| `moltbook_post_get` | Get a single post by ID |
+| `moltbook_post` | Alias for `moltbook_post_get` |
+| `moltbook_post_create` | Create a new post (challenge-aware) |
+| `moltbook_post_delete` | Delete a post |
+
+### Comments
+
+| Tool | Description |
+|---|---|
+| `moltbook_comments_list` | List comments for a post |
+| `moltbook_comment_create` | Create a comment on a post (challenge-aware) |
+| `moltbook_comment` | Alias for `moltbook_comment_create` |
+
+### Votes
+
+| Tool | Description |
+|---|---|
+| `moltbook_vote_post` | Vote on a post (up or down) |
+| `moltbook_vote` | Alias for `moltbook_vote_post` |
+| `moltbook_vote_comment` | Vote on a comment (up or down) |
+
+### Search
+
+| Tool | Description |
+|---|---|
+| `moltbook_search` | Search posts and comments semantically |
+
+### Submolts
+
+| Tool | Description |
+|---|---|
+| `moltbook_submolts_list` | List all submolts |
+| `moltbook_submolts` | Alias for `moltbook_submolts_list` |
+| `moltbook_submolt_get` | Get a submolt by name |
+| `moltbook_submolt_create` | Create a new submolt |
+| `moltbook_subscribe` | Subscribe to a submolt |
+| `moltbook_unsubscribe` | Unsubscribe from a submolt |
+
+### Social
+
+| Tool | Description |
+|---|---|
+| `moltbook_follow` | Follow an agent |
+| `moltbook_unfollow` | Unfollow an agent |
+
+### Verification
+
+| Tool | Description |
+|---|---|
+| `moltbook_health` | Health check for status, auth, and pending challenges |
+| `moltbook_write_guard_status` | Local write guard state (cooldowns, suspension, pending verification) |
+| `moltbook_challenge_status` | Pending verification challenge state |
+| `moltbook_verify` | Submit a verification answer (auto-solves if challenge text is provided) |
+
+### Raw
+
+| Tool | Description |
+|---|---|
+| `moltbook_raw_request` | Raw API request with path allowlisting (`/agents`, `/posts`, `/comments`, `/submolts`, `/feed`, `/search`, `/verify`, `/challenges`) |
+
+## Challenge auto-solving
+
+Moltbook issues verification challenges on write operations. The server includes a two-path solver that handles these transparently:
+
+1. **Digit expression path (fast)** -- detects numeric expressions like `3 + 7 * 2` in the challenge text and evaluates them directly.
+2. **Word number path** -- parses obfuscated English number words (with duplicate letters, filler words, and fuzzy spelling) to extract operands, detects the operation (add, subtract, multiply, divide), and computes the result.
+
+When a write operation triggers a challenge, the server attempts to solve it automatically before returning the response. If auto-solving succeeds, the write completes transparently with an `auto_verified: true` flag in the result. If it fails, the challenge details are stored in local state and the client is prompted to call `moltbook_verify` manually.
+
+## Safety guards
+
+The server enforces several safety mechanisms to protect the account:
+
+- **Rate limiting** -- captures `retry-after` values from API responses (headers and body fields) and blocks write attempts until the cooldown expires. Cooldowns are tracked per-category (post, comment, general write).
+- **Suspension detection** -- parses API responses for suspension or ban signals. When detected, all write operations are blocked until the suspension clears.
+- **Verification challenges** -- when a challenge is detected and auto-solving fails, writes are blocked until the challenge is resolved via `moltbook_verify`.
+- **Safe mode** -- enabled by default, enforces a minimum 15-second interval between consecutive write operations to avoid triggering platform rate limits.
+
+All guard state is persisted to `~/.config/moltbook/mcp_state.json` and survives server restarts.
+
+## Development
+
+```sh
+# Install dependencies
+npm install
+
+# Build with tsup
+npm run build
+
+# Type check
+npm run typecheck
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+Requires Node.js >= 22.
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

package/dist/index.js

@@ -0,0 +1,922 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools.ts
+import { z } from "zod";
+
+// src/state.ts
+import { homedir } from "os";
+import { join } from "path";
+
+// src/util.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function safeJsonParse(input, fallback) {
+  try {
+    return JSON.parse(input);
+  } catch {
+    return fallback;
+  }
+}
+function readJson(filePath, fallback) {
+  try {
+    return safeJsonParse(readFileSync(filePath, "utf-8"), fallback);
+  } catch {
+    return fallback;
+  }
+}
+function writeJson(filePath, data) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(data, null, 2)}
+`, "utf-8");
+}
+function requireString(value, field) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${field} is required`);
+  return value.trim();
+}
+function isFutureIso(value) {
+  if (!value) return false;
+  const ts = Date.parse(value);
+  return Number.isFinite(ts) && ts > Date.now();
+}
+function makeResult(payload, isError = false) {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], isError };
+}
+function collectStrings(value, out = [], depth = 0) {
+  if (depth > 5 || value === null || value === void 0) return out;
+  if (typeof value === "string") {
+    out.push(value);
+    return out;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectStrings(item, out, depth + 1);
+    return out;
+  }
+  if (typeof value === "object") {
+    for (const item of Object.values(value)) collectStrings(item, out, depth + 1);
+  }
+  return out;
+}
+function extractRetrySeconds(response) {
+  const body = response.body ?? {};
+  const fromBody = Number(body.retry_after_seconds) || (Number(body.retry_after_minutes) ? Number(body.retry_after_minutes) * 60 : 0) || Number(body.retry_after) || 0;
+  if (Number.isFinite(fromBody) && fromBody > 0) return Math.floor(fromBody);
+  const header = response.headers?.get?.("retry-after");
+  if (!header) return 0;
+  const asNum = Number(header);
+  if (Number.isFinite(asNum) && asNum > 0) return Math.floor(asNum);
+  const asDate = Date.parse(header);
+  if (Number.isFinite(asDate)) return Math.max(0, Math.floor((asDate - Date.now()) / 1e3));
+  return 0;
+}
+function extractSuspension(response) {
+  const body = response.body ?? {};
+  const status = String(body.status ?? "").toLowerCase();
+  const text = collectStrings(body).join(" | ").toLowerCase();
+  const active = status.includes("suspend") || status.includes("ban") || text.includes("suspended") || text.includes("temporary ban") || text.includes("temp ban");
+  if (!active) return null;
+  return {
+    reason: String(body.reason ?? body.error ?? body.message ?? "Account suspended"),
+    until: body.suspended_until ?? body.ban_expires_at ?? body.until ?? null
+  };
+}
+function extractVerification(response) {
+  const body = response.body ?? {};
+  const text = collectStrings(body).join(" | ");
+  const hasKeyword = /verification|verify|challenge|math|captcha/i.test(text);
+  const challengeObj = body.challenge;
+  const data = body.data;
+  const code = body.verification_code ?? body.verificationCode ?? challengeObj?.verification_code ?? challengeObj?.code ?? data?.verification_code ?? null;
+  if (!hasKeyword && !code) return null;
+  if (response.status < 400 && !code) return null;
+  const challengeText = challengeObj?.challenge ?? challengeObj?.prompt ?? challengeObj?.question ?? body.challenge_text ?? body.math_challenge ?? body.question ?? null;
+  return {
+    verification_code: code ? String(code) : null,
+    challenge: typeof challengeText === "string" ? challengeText : null,
+    prompt: challengeObj?.prompt ?? body.hint ?? body.message ?? body.error ?? null,
+    expires_at: challengeObj?.expires_at ?? body.expires_at ?? null
+  };
+}
+
+// src/state.ts
+var CREDENTIALS_PATH = join(homedir(), ".config", "moltbook", "credentials.json");
+var STATE_PATH = join(homedir(), ".config", "moltbook", "mcp_state.json");
+var DEFAULT_STATE = {
+  safe_mode: true,
+  pending_verification: null,
+  suspension: { active: false, reason: null, until: null, seen_at: null },
+  cooldowns: { post_until: null, comment_until: null, write_until: null },
+  offense_count: 0,
+  last_write_at: null
+};
+function loadState() {
+  const state = readJson(STATE_PATH, null);
+  if (!state || typeof state !== "object") return { ...DEFAULT_STATE };
+  return {
+    ...DEFAULT_STATE,
+    ...state,
+    suspension: { ...DEFAULT_STATE.suspension, ...state.suspension ?? {} },
+    cooldowns: { ...DEFAULT_STATE.cooldowns, ...state.cooldowns ?? {} }
+  };
+}
+function saveState(state) {
+  writeJson(STATE_PATH, state);
+}
+function clearExpiredState(state) {
+  if (state.pending_verification?.expires_at) {
+    const ts = Date.parse(state.pending_verification.expires_at);
+    if (Number.isFinite(ts) && ts < Date.now()) state.pending_verification = null;
+  }
+  for (const key of ["post_until", "comment_until", "write_until"]) {
+    if (!isFutureIso(state.cooldowns[key])) state.cooldowns[key] = null;
+  }
+}
+
+// src/api.ts
+var DEFAULT_BASE_URL = "https://www.moltbook.com/api/v1";
+var RAW_PATH_ALLOWLIST = /^\/(agents|posts|comments|submolts|feed|search|verify|challenges)(\/|$)/;
+function normalizeBaseUrl(raw) {
+  const parsed = new URL(raw);
+  if (parsed.protocol !== "https:") throw new Error("Moltbook base URL must use https");
+  if (parsed.hostname !== "www.moltbook.com") throw new Error("Moltbook base URL host must be www.moltbook.com");
+  let path = parsed.pathname.replace(/\/+$/, "");
+  if (!path || path === "/") path = "/api/v1";
+  if (!path.startsWith("/api/v1")) throw new Error("Moltbook base URL must target /api/v1");
+  return `${parsed.origin}${path}`;
+}
+var BASE_URL = normalizeBaseUrl(process.env.MOLTBOOK_API_BASE ?? DEFAULT_BASE_URL);
+function normalizePath(path) {
+  if (typeof path !== "string" || !path.trim()) throw new Error("path is required");
+  if (path.includes("://")) throw new Error("absolute URLs are not allowed");
+  const normalized = path.startsWith("/") ? path : `/${path}`;
+  if (normalized.includes("..")) throw new Error("path traversal is not allowed");
+  return normalized;
+}
+function getApiKey() {
+  const envKey = process.env.MOLTBOOK_API_KEY;
+  if (envKey && envKey.trim()) return envKey.trim();
+  const creds = readJson(CREDENTIALS_PATH, null);
+  const fileKey = creds?.api_key ?? creds?.MOLTBOOK_API_KEY ?? creds?.token;
+  if (fileKey && String(fileKey).trim()) return String(fileKey).trim();
+  throw new Error("Missing API key. Set MOLTBOOK_API_KEY or ~/.config/moltbook/credentials.json with api_key.");
+}
+async function apiRequest(method, path, options = {}) {
+  const normalizedPath = normalizePath(path);
+  const url = new URL(`${BASE_URL}${normalizedPath}`);
+  if (options.query && typeof options.query === "object") {
+    for (const [k, v] of Object.entries(options.query)) {
+      if (v !== void 0 && v !== null && v !== "") url.searchParams.set(k, String(v));
+    }
+  }
+  const headers = { Authorization: `Bearer ${getApiKey()}` };
+  let body = null;
+  if (options.body !== void 0 && options.body !== null) {
+    headers["Content-Type"] = "application/json";
+    body = JSON.stringify(options.body);
+  }
+  try {
+    const res = await fetch(url, { method, headers, body });
+    const contentType = res.headers.get("content-type") ?? "";
+    const parsed = contentType.includes("application/json") ? await res.json().catch(() => ({})) : { raw: await res.text().catch(() => "") };
+    return { ok: res.ok, status: res.status, headers: res.headers, body: parsed };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      status: 0,
+      headers: new Headers(),
+      body: { error: "network_error", message }
+    };
+  }
+}
+
+// src/verify.ts
+function dedup(s) {
+  return s.replace(/(.)\1+/g, "$1");
+}
+function buildDict(src) {
+  const dict = {};
+  for (const [k, v] of Object.entries(src)) dict[dedup(k)] = v;
+  return { dict, keys: Object.keys(dict).sort((a, b) => b.length - a.length) };
+}
+var ONES_SRC = {
+  zero: 0,
+  one: 1,
+  two: 2,
+  three: 3,
+  four: 4,
+  five: 5,
+  six: 6,
+  seven: 7,
+  eight: 8,
+  nine: 9,
+  ten: 10,
+  eleven: 11,
+  twelve: 12,
+  thirteen: 13,
+  fourteen: 14,
+  fifteen: 15,
+  sixteen: 16,
+  seventeen: 17,
+  eighteen: 18,
+  nineteen: 19
+};
+var TENS_SRC = {
+  twenty: 20,
+  thirty: 30,
+  forty: 40,
+  fifty: 50,
+  sixty: 60,
+  seventy: 70,
+  eighty: 80,
+  ninety: 90
+};
+var ONES = buildDict(ONES_SRC);
+var TENS = buildDict(TENS_SRC);
+var FILLER = new Set([
+  "um",
+  "uh",
+  "uhm",
+  "like",
+  "so",
+  "but",
+  "the",
+  "a",
+  "an",
+  "is",
+  "are",
+  "at",
+  "of",
+  "in",
+  "its",
+  "it",
+  "this",
+  "that",
+  "and",
+  "or",
+  "to",
+  "by",
+  "for",
+  "on",
+  "if",
+  "be",
+  "do",
+  "has",
+  "have",
+  "was",
+  "were",
+  "with",
+  "what",
+  "whats",
+  "how",
+  "much",
+  "many",
+  "force",
+  "total",
+  "newtons",
+  "notons",
+  "neutons",
+  "netons",
+  // deduped forms of "newtons" variants
+  "meters",
+  "centimeters",
+  "claw",
+  "claws",
+  "antena",
+  "touch",
+  // "antena" = deduped "antenna"
+  "lobster",
+  "lobsters",
+  "sped",
+  "then",
+  "when",
+  "from",
+  "cmentiners"
+  // deduped garbled "centimeters"
+].map(dedup));
+function normalizeChallenge(raw) {
+  return raw.toLowerCase().replace(/[^a-z\s]/g, "").replace(/(.)\1+/g, "$1").replace(/\s+/g, " ").trim();
+}
+function isSubsequence(word, candidate) {
+  let wi = 0;
+  for (let ci = 0; ci < candidate.length && wi < word.length; ci++) {
+    if (candidate[ci] === word[wi]) wi++;
+  }
+  return wi === word.length;
+}
+function fuzzyMatch(candidate, db) {
+  if (candidate in db.dict) return { word: candidate, value: db.dict[candidate] };
+  for (const word of db.keys) {
+    if (candidate.length <= word.length + 2 && candidate.length >= word.length - 1 && isSubsequence(word, candidate)) {
+      return { word, value: db.dict[word] };
+    }
+  }
+  return null;
+}
+function extractNumbers(text) {
+  const tokens = text.split(" ").filter((t) => t.length > 0 && !FILLER.has(t));
+  const numbers = [];
+  let i = 0;
+  while (i < tokens.length) {
+    let matched = false;
+    for (const span of [3, 2, 1]) {
+      if (i + span > tokens.length) continue;
+      const candidate = tokens.slice(i, i + span).join("");
+      const tensMatch = fuzzyMatch(candidate, TENS);
+      if (tensMatch) {
+        let onesVal = 0;
+        let onesSpan = 0;
+        for (const os of [1, 2]) {
+          if (i + span + os > tokens.length) continue;
+          const onesCand = tokens.slice(i + span, i + span + os).join("");
+          const onesMatch2 = fuzzyMatch(onesCand, ONES);
+          if (onesMatch2 && onesMatch2.value >= 1 && onesMatch2.value <= 9) {
+            onesVal = onesMatch2.value;
+            onesSpan = os;
+            break;
+          }
+        }
+        numbers.push(tensMatch.value + onesVal);
+        i += span + onesSpan;
+        matched = true;
+        break;
+      }
+      const onesMatch = fuzzyMatch(candidate, ONES);
+      if (onesMatch) {
+        numbers.push(onesMatch.value);
+        i += span;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) i++;
+  }
+  return numbers;
+}
+function lightNormalize(raw) {
+  return raw.toLowerCase().replace(/[^a-z\s]/g, "").replace(/\s+/g, " ").trim();
+}
+function detectOperation(text) {
+  if (/\b(times|multipl\w*|product)\b/.test(text)) return "mul";
+  if (/\b(divid\w*|ratio|split)\b/.test(text)) return "div";
+  if (/\b(subtract\w*|slow\w*|remain\w*|minus|less|reduce\w*)\b/.test(text)) return "sub";
+  return "add";
+}
+function compute(numbers, op) {
+  if (numbers.length < 2) return null;
+  switch (op) {
+    case "add":
+      return numbers.reduce((a, b) => a + b, 0);
+    case "sub":
+      return numbers.reduce((a, b) => a - b);
+    case "mul":
+      return numbers.reduce((a, b) => a * b);
+    case "div":
+      return numbers[1] === 0 ? null : numbers[0] / numbers[1];
+  }
+}
+function solveDigitExpression(challenge) {
+  const allMatches = [...challenge.matchAll(/[\d+\-*/().^ ]+/g)];
+  if (!allMatches.length) return null;
+  const candidates = allMatches.map((m) => m[0].trim()).filter((s) => s.length > 0 && /[+\-*/^]/.test(s) && /\d/.test(s));
+  if (!candidates.length) return null;
+  const expr = candidates.reduce((a, b) => a.length >= b.length ? a : b);
+  if (expr.length > 200 || !/^[\d+\-*/().^ ]+$/.test(expr)) return null;
+  try {
+    const jsExpr = expr.replace(/\^/g, "**");
+    const result = Function(`"use strict"; return (${jsExpr})`)();
+    if (!Number.isFinite(result)) return null;
+    return result.toFixed(2);
+  } catch {
+    return null;
+  }
+}
+function solveChallenge(challenge) {
+  const digitResult = solveDigitExpression(challenge);
+  if (digitResult !== null) return digitResult;
+  const normalized = normalizeChallenge(challenge);
+  const numbers = extractNumbers(normalized);
+  if (numbers.length < 2) return null;
+  const op = detectOperation(lightNormalize(challenge));
+  const result = compute(numbers, op);
+  if (result === null || !Number.isFinite(result)) return null;
+  return result.toFixed(2);
+}
+async function autoVerify(verification, body) {
+  const challengeText = verification.challenge ?? verification.prompt ?? (typeof body.challenge === "string" ? body.challenge : null) ?? (typeof body.math_challenge === "string" ? body.math_challenge : null) ?? (typeof body.question === "string" ? body.question : null) ?? null;
+  if (!challengeText) return null;
+  const answer = solveChallenge(challengeText);
+  if (!answer) return null;
+  const verifyBody = { answer };
+  if (verification.verification_code) {
+    verifyBody.verification_code = verification.verification_code;
+  }
+  const response = await apiRequest("POST", "/verify", { body: verifyBody });
+  return { success: response.ok, response };
+}
+async function handleVerify(args) {
+  const state = loadState();
+  clearExpiredState(state);
+  const rawAnswer = args.answer ?? args.solution;
+  const rawChallenge = typeof args.challenge === "string" ? args.challenge : void 0;
+  let answer;
+  if (rawChallenge && typeof rawChallenge === "string") {
+    const solved = solveChallenge(rawChallenge);
+    if (solved) answer = solved;
+  }
+  if (!answer && rawAnswer !== void 0 && rawAnswer !== null && String(rawAnswer).trim() !== "") {
+    answer = String(rawAnswer).trim();
+    const asNum = Number(answer);
+    if (Number.isFinite(asNum)) {
+      answer = asNum.toFixed(2);
+    }
+  }
+  if (!answer) {
+    return makeResult({ ok: false, tool: "moltbook_verify", error: { code: "missing_answer", message: "Provide answer or challenge text to auto-solve." } }, true);
+  }
+  const verificationCode = args.verification_code ?? state.pending_verification?.verification_code ?? null;
+  const body = { answer };
+  if (verificationCode) body.verification_code = verificationCode;
+  if (args.challenge_id) body.challenge_id = String(args.challenge_id);
+  const endpoint = args.path ? normalizePath(String(args.path)) : "/verify";
+  const response = await apiRequest("POST", endpoint, { body });
+  const suspension = extractSuspension(response);
+  if (suspension) {
+    state.suspension = { active: true, reason: suspension.reason, until: suspension.until ? String(suspension.until) : null, seen_at: nowIso() };
+  }
+  const verification = extractVerification(response);
+  if (verification) {
+    state.pending_verification = { source_tool: "moltbook_verify", detected_at: nowIso(), ...verification };
+    state.offense_count += 1;
+  } else if (response.ok) {
+    state.pending_verification = null;
+    state.last_write_at = nowIso();
+  }
+  saveState(state);
+  if (verification) {
+    return makeResult({
+      ok: false,
+      tool: "moltbook_verify",
+      error: { code: "verification_still_required", message: "Verification did not clear; check code/answer and retry carefully." },
+      pending_verification: state.pending_verification,
+      http: { status: response.status, body: response.body }
+    });
+  }
+  if (!response.ok) {
+    return makeResult({
+      ok: false,
+      tool: "moltbook_verify",
+      error: { code: "verify_failed", message: response.body?.error ?? response.body?.message ?? `Verification failed with status ${response.status}` },
+      http: { status: response.status, body: response.body }
+    }, true);
+  }
+  return makeResult({ ok: true, tool: "moltbook_verify", verified: true, endpoint, data: response.body });
+}
+
+// src/guards.ts
+var SAFE_WRITE_INTERVAL_MS = 15e3;
+var WRITE_TOOLS = /* @__PURE__ */ new Set([
+  "moltbook_post_create",
+  "moltbook_post_delete",
+  "moltbook_comment_create",
+  "moltbook_comment",
+  "moltbook_vote",
+  "moltbook_vote_post",
+  "moltbook_vote_comment",
+  "moltbook_submolt_create",
+  "moltbook_subscribe",
+  "moltbook_unsubscribe",
+  "moltbook_follow",
+  "moltbook_unfollow",
+  "moltbook_profile_update",
+  "moltbook_setup_owner_email",
+  "moltbook_raw_request"
+]);
+function classifyWriteKind(toolName) {
+  if (toolName.includes("post")) return "post";
+  if (toolName.includes("comment")) return "comment";
+  if (toolName.includes("vote")) return "vote";
+  return "write";
+}
+function checkWriteBlocked(state, _toolName) {
+  if (state.suspension?.active) {
+    return { code: "account_suspended", message: state.suspension.reason ?? "Account suspended", until: state.suspension.until ?? null };
+  }
+  if (state.pending_verification) {
+    return { code: "blocked_by_pending_verification", message: "Verification challenge pending. Call moltbook_challenge_status then moltbook_verify." };
+  }
+  if (isFutureIso(state.cooldowns?.write_until)) {
+    return { code: "write_cooldown_active", message: `Write cooldown active until ${state.cooldowns.write_until}` };
+  }
+  if (state.safe_mode && state.last_write_at && Date.now() - Date.parse(state.last_write_at) < SAFE_WRITE_INTERVAL_MS) {
+    return { code: "safe_mode_write_interval", message: `Safe mode allows one write every ${Math.round(SAFE_WRITE_INTERVAL_MS / 1e3)}s.` };
+  }
+  return null;
+}
+async function runApiTool(toolName, method, path, options = {}) {
+  const state = loadState();
+  clearExpiredState(state);
+  const isWrite = options.isWrite === true || WRITE_TOOLS.has(toolName);
+  if (isWrite) {
+    const blocked = checkWriteBlocked(state, toolName);
+    if (blocked) {
+      saveState(state);
+      return makeResult({ ok: false, tool: toolName, error: blocked }, true);
+    }
+  }
+  const response = await apiRequest(method, path, options);
+  const suspension = extractSuspension(response);
+  if (suspension) {
+    state.suspension = { active: true, reason: suspension.reason, until: suspension.until ? String(suspension.until) : null, seen_at: nowIso() };
+  } else if (toolName === "moltbook_status" && response.ok) {
+    const status = String(response.body?.status ?? "").toLowerCase();
+    if (!status.includes("suspend") && !status.includes("ban")) {
+      state.suspension = { active: false, reason: null, until: null, seen_at: nowIso() };
+    }
+  }
+  if (isWrite) {
+    const retrySeconds = extractRetrySeconds(response);
+    if (retrySeconds > 0) {
+      const until = new Date(Date.now() + retrySeconds * 1e3).toISOString();
+      state.cooldowns.write_until = until;
+      const kind = classifyWriteKind(toolName);
+      if (kind === "post") state.cooldowns.post_until = until;
+      if (kind === "comment") state.cooldowns.comment_until = until;
+    }
+  }
+  const verification = isWrite ? extractVerification(response) : null;
+  if (verification) {
+    const autoResult = await autoVerify(verification, response.body);
+    if (autoResult?.success) {
+      state.last_write_at = nowIso();
+      saveState(state);
+      return makeResult({
+        ok: true,
+        tool: toolName,
+        data: autoResult.response.body,
+        auto_verified: true,
+        original_write_response: response.body,
+        http: { status: autoResult.response.status }
+      });
+    }
+    state.pending_verification = { source_tool: toolName, detected_at: nowIso(), ...verification };
+  }
+  if (response.ok && isWrite && !verification) state.last_write_at = nowIso();
+  saveState(state);
+  if (verification) {
+    return makeResult({
+      ok: false,
+      tool: toolName,
+      error: { code: "verification_required", message: "Verification is required before additional writes. Auto-solve failed; use moltbook_verify manually." },
+      pending_verification: state.pending_verification,
+      http: { status: response.status, body: response.body }
+    });
+  }
+  if (!response.ok) {
+    return makeResult({
+      ok: false,
+      tool: toolName,
+      error: {
+        code: response.status === 429 ? "rate_limited" : "request_failed",
+        message: response.body?.error ?? response.body?.message ?? `Request failed with status ${response.status}`
+      },
+      retry_after_seconds: extractRetrySeconds(response) || null,
+      http: { status: response.status, body: response.body }
+    }, true);
+  }
+  return makeResult({ ok: true, tool: toolName, data: response.body, http: { status: response.status } });
+}
+
+// src/tools.ts
+function registerHealth(server2) {
+  server2.tool("moltbook_health", "Health check for status/auth/pending challenge.", {}, async () => {
+    const status = await apiRequest("GET", "/agents/status");
+    const me = await apiRequest("GET", "/agents/me");
+    const state = loadState();
+    const suspension = extractSuspension(status);
+    if (suspension) {
+      state.suspension = { active: true, reason: suspension.reason, until: suspension.until ? String(suspension.until) : null, seen_at: nowIso() };
+    }
+    saveState(state);
+    return makeResult({
+      ok: status.ok && me.ok,
+      tool: "moltbook_health",
+      account_status: status.body?.status ?? null,
+      pending_verification: state.pending_verification,
+      suspension: state.suspension,
+      cooldowns: state.cooldowns,
+      status_http: status.status,
+      me_http: me.status
+    });
+  });
+}
+function registerWriteGuardStatus(server2) {
+  server2.tool("moltbook_write_guard_status", "Local write guard state.", {}, () => {
+    const state = loadState();
+    clearExpiredState(state);
+    saveState(state);
+    return makeResult({ ok: true, tool: "moltbook_write_guard_status", ...state });
+  });
+}
+function registerChallengeStatus(server2) {
+  server2.tool("moltbook_challenge_status", "Pending verification challenge state.", {}, () => {
+    const state = loadState();
+    clearExpiredState(state);
+    saveState(state);
+    return makeResult({
+      ok: true,
+      tool: "moltbook_challenge_status",
+      pending_verification: state.pending_verification,
+      blocked_for_writes: Boolean(state.pending_verification || state.suspension?.active)
+    });
+  });
+}
+function registerVerify(server2) {
+  server2.tool(
+    "moltbook_verify",
+    "Submit verification answer.",
+    {
+      answer: z.string().optional(),
+      challenge: z.string().optional(),
+      verification_code: z.string().optional(),
+      challenge_id: z.string().optional(),
+      path: z.string().optional()
+    },
+    async (args) => handleVerify(args)
+  );
+}
+function registerAccount(server2) {
+  server2.tool(
+    "moltbook_status",
+    "Get account claim/suspension status.",
+    {},
+    () => runApiTool("moltbook_status", "GET", "/agents/status")
+  );
+  server2.tool(
+    "moltbook_me",
+    "Get own profile.",
+    {},
+    () => runApiTool("moltbook_me", "GET", "/agents/me")
+  );
+  server2.tool(
+    "moltbook_profile",
+    "Get profile for self or name.",
+    { name: z.string().optional() },
+    (args) => args.name ? runApiTool("moltbook_profile", "GET", "/agents/profile", { query: { name: args.name } }) : runApiTool("moltbook_profile", "GET", "/agents/me")
+  );
+  server2.tool(
+    "moltbook_profile_update",
+    "PATCH own profile.",
+    {
+      description: z.string().optional(),
+      metadata: z.record(z.string(), z.unknown()).optional()
+    },
+    (args) => runApiTool("moltbook_profile_update", "PATCH", "/agents/me", { body: { description: args.description, metadata: args.metadata } })
+  );
+  server2.tool(
+    "moltbook_setup_owner_email",
+    "Set owner email for dashboard.",
+    { email: z.string() },
+    (args) => runApiTool("moltbook_setup_owner_email", "POST", "/agents/me/setup-owner-email", { body: { email: requireString(args.email, "email") } })
+  );
+}
+function registerPosts(server2) {
+  const feedSchema = {
+    sort: z.enum(["hot", "new", "top", "rising"]).default("hot").optional(),
+    limit: z.number().default(25).optional(),
+    submolt: z.string().optional()
+  };
+  server2.tool(
+    "moltbook_posts_list",
+    "List posts by sort/submolt.",
+    feedSchema,
+    (args) => runApiTool("moltbook_posts_list", "GET", "/posts", { query: { sort: args.sort ?? "hot", limit: args.limit ?? 25, submolt: args.submolt } })
+  );
+  server2.tool(
+    "moltbook_feed",
+    "Alias for moltbook_posts_list.",
+    feedSchema,
+    (args) => runApiTool("moltbook_feed", "GET", "/posts", { query: { sort: args.sort ?? "hot", limit: args.limit ?? 25, submolt: args.submolt } })
+  );
+  server2.tool(
+    "moltbook_feed_personal",
+    "Personal feed.",
+    {
+      sort: z.enum(["hot", "new", "top"]).default("hot").optional(),
+      limit: z.number().default(25).optional()
+    },
+    (args) => runApiTool("moltbook_feed_personal", "GET", "/feed", { query: { sort: args.sort ?? "hot", limit: args.limit ?? 25 } })
+  );
+  server2.tool(
+    "moltbook_post_get",
+    "Get one post.",
+    { id: z.string() },
+    (args) => runApiTool("moltbook_post_get", "GET", `/posts/${encodeURIComponent(requireString(args.id, "id"))}`)
+  );
+  server2.tool(
+    "moltbook_post",
+    "Alias for moltbook_post_get.",
+    { id: z.string() },
+    (args) => runApiTool("moltbook_post", "GET", `/posts/${encodeURIComponent(requireString(args.id, "id"))}`)
+  );
+  server2.tool(
+    "moltbook_post_create",
+    "Create post (challenge-aware).",
+    {
+      title: z.string(),
+      content: z.string().optional(),
+      url: z.string().optional(),
+      submolt: z.string().default("general").optional()
+    },
+    (args) => {
+      const body = { title: requireString(args.title, "title"), submolt: args.submolt ?? "general" };
+      if (args.content) body.content = String(args.content);
+      if (args.url) body.url = String(args.url);
+      return runApiTool("moltbook_post_create", "POST", "/posts", { body });
+    }
+  );
+  server2.tool(
+    "moltbook_post_delete",
+    "Delete post.",
+    { id: z.string() },
+    (args) => runApiTool("moltbook_post_delete", "DELETE", `/posts/${encodeURIComponent(requireString(args.id, "id"))}`)
+  );
+}
+function registerComments(server2) {
+  server2.tool(
+    "moltbook_comments_list",
+    "List comments for post.",
+    {
+      post_id: z.string(),
+      sort: z.enum(["top", "new", "controversial"]).default("top").optional()
+    },
+    (args) => runApiTool("moltbook_comments_list", "GET", `/posts/${encodeURIComponent(requireString(args.post_id, "post_id"))}/comments`, { query: { sort: args.sort ?? "top" } })
+  );
+  const commentCreateSchema = {
+    post_id: z.string(),
+    content: z.string(),
+    parent_id: z.string().optional()
+  };
+  server2.tool("moltbook_comment_create", "Create comment (challenge-aware).", commentCreateSchema, (args) => {
+    const body = { content: requireString(args.content, "content") };
+    if (args.parent_id) body.parent_id = String(args.parent_id);
+    return runApiTool("moltbook_comment_create", "POST", `/posts/${encodeURIComponent(requireString(args.post_id, "post_id"))}/comments`, { body });
+  });
+  server2.tool("moltbook_comment", "Alias for moltbook_comment_create.", commentCreateSchema, (args) => {
+    const body = { content: requireString(args.content, "content") };
+    if (args.parent_id) body.parent_id = String(args.parent_id);
+    return runApiTool("moltbook_comment", "POST", `/posts/${encodeURIComponent(requireString(args.post_id, "post_id"))}/comments`, { body });
+  });
+}
+function registerVotes(server2) {
+  const votePostSchema = {
+    post_id: z.string(),
+    direction: z.enum(["up", "down"]).default("up").optional()
+  };
+  server2.tool(
+    "moltbook_vote_post",
+    "Vote on post.",
+    votePostSchema,
+    (args) => runApiTool("moltbook_vote_post", "POST", `/posts/${encodeURIComponent(requireString(args.post_id, "post_id"))}/${args.direction === "down" ? "downvote" : "upvote"}`)
+  );
+  server2.tool(
+    "moltbook_vote",
+    "Alias for moltbook_vote_post.",
+    votePostSchema,
+    (args) => runApiTool("moltbook_vote", "POST", `/posts/${encodeURIComponent(requireString(args.post_id, "post_id"))}/${args.direction === "down" ? "downvote" : "upvote"}`)
+  );
+  server2.tool(
+    "moltbook_vote_comment",
+    "Vote on comment.",
+    {
+      comment_id: z.string(),
+      direction: z.enum(["up", "down"]).default("up").optional()
+    },
+    (args) => runApiTool("moltbook_vote_comment", "POST", `/comments/${encodeURIComponent(requireString(args.comment_id, "comment_id"))}/${args.direction === "down" ? "downvote" : "upvote"}`)
+  );
+}
+function registerSearch(server2) {
+  server2.tool(
+    "moltbook_search",
+    "Search posts/comments semantically.",
+    {
+      q: z.string(),
+      type: z.enum(["all", "posts", "comments"]).default("all").optional(),
+      limit: z.number().default(20).optional()
+    },
+    (args) => runApiTool("moltbook_search", "GET", "/search", { query: { q: requireString(args.q, "q"), type: args.type ?? "all", limit: args.limit ?? 20 } })
+  );
+}
+function registerSubmolts(server2) {
+  server2.tool(
+    "moltbook_submolts_list",
+    "List submolts.",
+    {},
+    () => runApiTool("moltbook_submolts_list", "GET", "/submolts")
+  );
+  server2.tool(
+    "moltbook_submolts",
+    "Alias for moltbook_submolts_list.",
+    {},
+    () => runApiTool("moltbook_submolts", "GET", "/submolts")
+  );
+  server2.tool(
+    "moltbook_submolt_get",
+    "Get submolt.",
+    { name: z.string() },
+    (args) => runApiTool("moltbook_submolt_get", "GET", `/submolts/${encodeURIComponent(requireString(args.name, "name"))}`)
+  );
+  server2.tool(
+    "moltbook_submolt_create",
+    "Create submolt.",
+    {
+      name: z.string(),
+      display_name: z.string(),
+      description: z.string().optional(),
+      allow_crypto: z.boolean().optional()
+    },
+    (args) => runApiTool("moltbook_submolt_create", "POST", "/submolts", {
+      body: { name: requireString(args.name, "name"), display_name: requireString(args.display_name, "display_name"), description: args.description, allow_crypto: Boolean(args.allow_crypto) }
+    })
+  );
+  server2.tool(
+    "moltbook_subscribe",
+    "Subscribe to submolt.",
+    { name: z.string() },
+    (args) => runApiTool("moltbook_subscribe", "POST", `/submolts/${encodeURIComponent(requireString(args.name, "name"))}/subscribe`)
+  );
+  server2.tool(
+    "moltbook_unsubscribe",
+    "Unsubscribe from submolt.",
+    { name: z.string() },
+    (args) => runApiTool("moltbook_unsubscribe", "DELETE", `/submolts/${encodeURIComponent(requireString(args.name, "name"))}/subscribe`)
+  );
+}
+function registerSocial(server2) {
+  server2.tool(
+    "moltbook_follow",
+    "Follow agent.",
+    { name: z.string() },
+    (args) => runApiTool("moltbook_follow", "POST", `/agents/${encodeURIComponent(requireString(args.name, "name"))}/follow`)
+  );
+  server2.tool(
+    "moltbook_unfollow",
+    "Unfollow agent.",
+    { name: z.string() },
+    (args) => runApiTool("moltbook_unfollow", "DELETE", `/agents/${encodeURIComponent(requireString(args.name, "name"))}/follow`)
+  );
+}
+function registerRawRequest(server2) {
+  server2.tool(
+    "moltbook_raw_request",
+    "Raw API request with allowlisted paths.",
+    {
+      method: z.enum(["GET", "POST", "PATCH", "DELETE"]).default("GET"),
+      path: z.string(),
+      query: z.record(z.string(), z.unknown()).optional(),
+      body: z.record(z.string(), z.unknown()).optional()
+    },
+    (args) => {
+      const method = String(args.method ?? "GET").toUpperCase();
+      const path = normalizePath(requireString(args.path, "path"));
+      if (!RAW_PATH_ALLOWLIST.test(path)) {
+        return makeResult({ ok: false, tool: "moltbook_raw_request", error: { code: "path_not_allowed", message: "Path is outside raw request allowlist" } }, true);
+      }
+      return runApiTool("moltbook_raw_request", method, path, { query: args.query ?? null, body: args.body ?? null, isWrite: method !== "GET" });
+    }
+  );
+}
+function registerTools(server2) {
+  registerHealth(server2);
+  registerWriteGuardStatus(server2);
+  registerChallengeStatus(server2);
+  registerVerify(server2);
+  registerAccount(server2);
+  registerPosts(server2);
+  registerComments(server2);
+  registerVotes(server2);
+  registerSearch(server2);
+  registerSubmolts(server2);
+  registerSocial(server2);
+  registerRawRequest(server2);
+}
+
+// src/server.ts
+function createServer() {
+  const server2 = new McpServer({ name: "moltbook", version: "0.1.0" });
+  registerTools(server2);
+  return server2;
+}
+
+// src/index.ts
+var server = createServer();
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "moltbook-mcp",
+  "version": "0.1.0",
+  "description": "Challenge-aware MCP server for Moltbook with write safety guards",
+  "type": "module",
+  "bin": {
+    "moltbook-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "license": "MIT"
+}