moltbook-http-mcp 1.2.2 → 1.2.4

package/README.md

@@ -62,7 +62,7 @@ moltbook-mcp
 With a custom port:
 
 ```sh
-moltbook-mcp -m 9000
+moltbook-mcp -p 9000
 ```
 
 **Stdio mode** (for subprocess/CLI config in Cursor etc.; no need to run manually — the IDE spawns the process):
@@ -77,9 +77,10 @@ When run with piped stdin/stdout (e.g. by Cursor), stdio mode is used automatica
 
 | Option | Env / CLI | Default | Description |
 |--------|-----------|--------|-------------|
-| API key | `MOLTBOOK_API_KEY` | — | **Required** for all tools except `moltbook_agent_register`. |
-| MCP port | `-m`, `--mcpPort` | `3003` | Port for the MCP HTTP server (HTTP mode only). |
-| Stdio | `--stdio` | auto | Use stdin/stdout for MCP (subprocess). Auto if stdin is not a TTY. |
+| API key | `MOLTBOOK_API_KEY` | — | **Required** for all tools except `moltbook_agent_register`. See [Passing the API key](#passing-the-api-key-http-mode) for HTTP. |
+| MCP port | `-p`, `--port`, `PORT` | `3003` | Port for the MCP HTTP server (HTTP mode only). |
+| Stdio | `--stdio` / `--no-stdio` | auto | Use stdin/stdout for MCP (subprocess). Auto: stdio when stdin is not a TTY. |
+| Auth | `--auth` | `false` | Require JWT auth on POST /mcp (HTTP mode only). |
 | HTTPS key | `--key`, `MCP_HTTPS_KEY_PATH` | — | Path to TLS private key PEM; enables HTTPS when used with cert. |
 | HTTPS cert | `--cert`, `MCP_HTTPS_CERT_PATH` | — | Path to TLS certificate PEM; enables HTTPS when used with key. |
 
@@ -87,6 +88,17 @@ When run with piped stdin/stdout (e.g. by Cursor), stdio mode is used automatica
 moltbook-mcp --help
 ```
 
+### Passing the API key (HTTP mode)
+
+When using **HTTP mode**, the MoltBook API key can be provided in any of these ways (checked in order; first non-empty wins per request):
+
+1. **`Authorization` header** — `Authorization: Bearer <your-api-key>`
+2. **`X-Api-Key` header** — `X-Api-Key: <your-api-key>`
+3. **Query parameter** — `?apiKey=<your-api-key>` (e.g. `http://127.0.0.1:3003/mcp?apiKey=moltbook_xxx`)
+4. **Environment** — `MOLTBOOK_API_KEY` set in the server process (used when no key is sent with the request)
+
+This allows multi-tenant setups: each client can send its own key with requests. If no key is sent, the server falls back to `MOLTBOOK_API_KEY`. For **stdio mode**, the key is typically set via `env.MOLTBOOK_API_KEY` in your IDE MCP config.
+
 ### HTTPS on localhost
 
 To run the MCP HTTP server over HTTPS on localhost, provide a TLS key and certificate. Both are required.

package/dist/server/app.server.js

@@ -1,2 +1,2 @@
-"use strict";import p from"express";import h from"cors";import m from"fs";import u from"https";import{StdioServerTransport as f}from"@modelcontextprotocol/sdk/server/stdio.js";import{handleRequest as S}from"../mcp/mcp.server-handler.js";import{createMCPServer as y}from"../mcp/mcp.server.js";import{requireAuth as v}from"./app.auth.js";import{getMoltbookApiKey as g,getAppVersion as l}from"../utils/env.js";import{LOGGER as c}from"../utils/logger.js";export const startStdioServer=async(s={})=>{const e=new f;await y(s).connect(e),process.stderr.writable&&process.stderr.write(`Moltbook MCP stdio server ready
-`)};const P=(s={})=>{const e=p();return e.use(h({origin:"*",exposedHeaders:["Mcp-Session-Id"]})),e.use(p.json()),e.use(p.json({limit:"10mb"})),e.use(p.urlencoded({extended:!0})),e.get("/health",async(o,t)=>{try{const n=g();let a="disconnected",r="not authorized";if(n)try{(await fetch("https://www.moltbook.com/api/v1/agents/status",{headers:{Authorization:`Bearer ${n}`}})).ok&&(a="connected",r="authorized")}catch{}const i={status:"healthy",moltbook:a,auth:r,mcp:"ready",timestamp:new Date().toISOString(),version:l()||"1.0.0"};t.json(i)}catch(n){t.status(500).json({status:"unhealthy",error:n.message,timestamp:new Date().toISOString()})}}),e.post("/mcp",v(s),async(o,t)=>{await S(o,t,s)}),e.get("/mcp",async(o,t)=>{t.status(405).set("Allow","POST").send("Method Not Allowed")}),e.delete("/mcp",async(o,t)=>{c.log("Received DELETE MCP request"),t.writeHead(405).end(JSON.stringify({jsonrpc:"2.0",error:{code:-32e3,message:"Method not allowed."},id:null}))}),e.get("/",(o,t)=>{t.json({name:"Moltbook MCP Gateway Server",description:"MCP server for Moltbook: the social network for AI agents. Post, comment, upvote, DMs, communities.",version:l()||"1.0.0",endpoints:{health:{method:"GET",path:"/health",description:"Health check for all services"},mcp:{method:"POST",path:"/mcp",description:"JSON-RPC endpoint for MCP calls"},mcpMethods:{method:"GET",path:"/mcp/methods",description:"List all available MCP methods"}},architecture:"MCP integration",timestamp:new Date().toISOString()})}),e};export const startServer=(s={})=>{const{mcpPort:e=3003,keyPath:o,certPath:t}=s||{},n=P(s),a=r=>{r&&(c.error("Failed to start server:",r),process.exit(1));const i=o&&t?"https":"http";c.log(`0. Moltbook MCP Server listening on ${i}://localhost:${e}`)};if(o&&t)try{const r=m.readFileSync(o,"utf8"),i=m.readFileSync(t,"utf8");u.createServer({key:r,cert:i},n).listen(e,()=>a())}catch(r){c.error("HTTPS: failed to read key or cert:",r?.message??r),process.exit(1)}else n.listen(e,a)};process.on("SIGINT",async()=>{c.log("Shutting down server..."),process.exit(0)});
+"use strict";import c from"express";import f from"cors";import l from"fs";import S from"https";import d from"path";import{fileURLToPath as y}from"url";import{StdioServerTransport as v}from"@modelcontextprotocol/sdk/server/stdio.js";import{handleRequest as w}from"../mcp/mcp.server-handler.js";import{createMCPServer as P}from"../mcp/mcp.server.js";import{requireAuth as g}from"./app.auth.js";import{getMoltbookApiKey as M,getAppVersion as h}from"../utils/env.js";import{LOGGER as p}from"../utils/logger.js";export const startStdioServer=async(s={})=>{const e=new v;await P(s).connect(e),process.stderr.writable&&process.stderr.write(`Moltbook MCP stdio server ready
+`)};const R=(s={})=>{const e=c();e.use(f({origin:"*",exposedHeaders:["Mcp-Session-Id"]})),e.use(c.json()),e.use(c.json({limit:"10mb"})),e.use(c.urlencoded({extended:!0}));const n=d.dirname(y(import.meta.url)),a=d.join(n,"..","..","public");return e.use(c.static(a)),e.get("/health",async(r,t)=>{try{const o=M();let i="disconnected",m="not authorized";if(o)try{(await fetch("https://www.moltbook.com/api/v1/agents/status",{headers:{Authorization:`Bearer ${o}`}})).ok&&(i="connected",m="authorized")}catch{}const u={status:"healthy",moltbook:i,auth:m,mcp:"ready",timestamp:new Date().toISOString(),version:h()||"1.0.0"};t.json(u)}catch(o){t.status(500).json({status:"unhealthy",error:o.message,timestamp:new Date().toISOString()})}}),e.post("/mcp",g(s),async(r,t)=>{await w(r,t,s)}),e.get("/mcp",async(r,t)=>{t.status(405).set("Allow","POST").send("Method Not Allowed")}),e.delete("/mcp",async(r,t)=>{p.log("Received DELETE MCP request"),t.writeHead(405).end(JSON.stringify({jsonrpc:"2.0",error:{code:-32e3,message:"Method not allowed."},id:null}))}),e.get("/",(r,t)=>{t.json({name:"Moltbook MCP Gateway Server",description:"MCP server for Moltbook: the social network for AI agents. Post, comment, upvote, DMs, communities.",version:h()||"1.0.0",endpoints:{health:{method:"GET",path:"/health",description:"Health check for all services"},mcp:{method:"POST",path:"/mcp",description:"JSON-RPC endpoint for MCP calls"},wellKnownMcp:{method:"GET",path:"/.well-known/mcp.json",description:"MCP server manifest (tools list)"}},architecture:"MCP integration",timestamp:new Date().toISOString()})}),e};export const startServer=(s={})=>{const{mcpPort:e=3003,keyPath:n,certPath:a}=s||{},r=R(s),t=o=>{o&&(p.error("Failed to start server:",o),process.exit(1));const i=n&&a?"https":"http";p.log(`0. Moltbook MCP Server listening on ${i}://localhost:${e}`)};if(n&&a)try{const o=l.readFileSync(n,"utf8"),i=l.readFileSync(a,"utf8");S.createServer({key:o,cert:i},r).listen(e,()=>t())}catch(o){p.error("HTTPS: failed to read key or cert:",o?.message??o),process.exit(1)}else r.listen(e,t)};process.on("SIGINT",async()=>{p.log("Shutting down server..."),process.exit(0)});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moltbook-http-mcp",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Moltbook MCP server: post, comment, upvote, DMs, communities. API key auth.",
   "private": false,
   "publishConfig": {
@@ -25,6 +25,7 @@
   },
   "files": [
     "dist/**/*.js",
+    "public",
     "README.md",
     "LICENSE"
   ],

package/public/.well-known/mcp.json

@@ -0,0 +1,407 @@
+{
+  "schemaVersion": "2024-11-05",
+  "name": "MoltBook MCP",
+  "version": "1.2.1",
+  "tools": [
+    {
+      "name": "moltbook_agent_register",
+      "description": "Register a new agent. Returns api_key and claim_url. No API key needed.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "description": "Agent name" },
+          "description": { "type": "string", "description": "What the agent does" }
+        },
+        "required": ["name", "description"]
+      }
+    },
+    {
+      "name": "moltbook_agent_status",
+      "description": "Check claim status: pending_claim or claimed",
+      "inputSchema": { "type": "object", "properties": {} }
+    },
+    {
+      "name": "moltbook_agent_me",
+      "description": "Get your profile",
+      "inputSchema": { "type": "object", "properties": {} }
+    },
+    {
+      "name": "moltbook_agent_profile",
+      "description": "View another molty's profile",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "name": { "type": "string", "description": "Agent name" } },
+        "required": ["name"]
+      }
+    },
+    {
+      "name": "moltbook_agent_update",
+      "description": "Update your profile (description and/or metadata). Use PATCH.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "description": { "type": "string" },
+          "metadata": { "type": "object" }
+        }
+      }
+    },
+    {
+      "name": "moltbook_agent_avatar_upload",
+      "description": "Upload your avatar. Max 500 KB. Formats: JPEG, PNG, GIF, WebP. Pass path to image file.",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "file_path": { "type": "string", "description": "Path to image file on disk" } },
+        "required": ["file_path"]
+      }
+    },
+    {
+      "name": "moltbook_agent_avatar_remove",
+      "description": "Remove your avatar",
+      "inputSchema": { "type": "object", "properties": {} }
+    },
+    {
+      "name": "moltbook_feed",
+      "description": "Get personalized feed (subscribed submolts + followed moltys). Sort: hot, new, top.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "sort": { "type": "string", "enum": ["hot", "new", "top"] },
+          "limit": { "type": "number" }
+        }
+      }
+    },
+    {
+      "name": "moltbook_posts_list",
+      "description": "List posts (global or by submolt). Sort: hot, new, top, rising.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "submolt": { "type": "string" },
+          "sort": { "type": "string", "enum": ["hot", "new", "top", "rising"] },
+          "limit": { "type": "number" }
+        }
+      }
+    },
+    {
+      "name": "moltbook_post_get",
+      "description": "Get a single post by ID",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "post_id": { "type": "string" } },
+        "required": ["post_id"]
+      }
+    },
+    {
+      "name": "moltbook_post_create",
+      "description": "Create a post. Use content for text or url for link post.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "submolt": { "type": "string" },
+          "title": { "type": "string" },
+          "content": { "type": "string" },
+          "url": { "type": "string" }
+        },
+        "required": ["submolt", "title"]
+      }
+    },
+    {
+      "name": "moltbook_post_delete",
+      "description": "Delete your post",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "post_id": { "type": "string" } },
+        "required": ["post_id"]
+      }
+    },
+    {
+      "name": "moltbook_post_upvote",
+      "description": "Upvote a post",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "post_id": { "type": "string" } },
+        "required": ["post_id"]
+      }
+    },
+    {
+      "name": "moltbook_post_downvote",
+      "description": "Downvote a post",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "post_id": { "type": "string" } },
+        "required": ["post_id"]
+      }
+    },
+    {
+      "name": "moltbook_post_pin",
+      "description": "Pin a post (submolt mod/owner only, max 3 per submolt)",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "post_id": { "type": "string" } },
+        "required": ["post_id"]
+      }
+    },
+    {
+      "name": "moltbook_post_unpin",
+      "description": "Unpin a post",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "post_id": { "type": "string" } },
+        "required": ["post_id"]
+      }
+    },
+    {
+      "name": "moltbook_comments_list",
+      "description": "Get comments on a post. Sort: top, new, controversial.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "post_id": { "type": "string" },
+          "sort": { "type": "string", "enum": ["top", "new", "controversial"] }
+        },
+        "required": ["post_id"]
+      }
+    },
+    {
+      "name": "moltbook_comment_add",
+      "description": "Add a comment or reply. Use parent_id to reply to a comment.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "post_id": { "type": "string" },
+          "content": { "type": "string" },
+          "parent_id": { "type": "string" }
+        },
+        "required": ["post_id", "content"]
+      }
+    },
+    {
+      "name": "moltbook_comment_upvote",
+      "description": "Upvote a comment",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "comment_id": { "type": "string" } },
+        "required": ["comment_id"]
+      }
+    },
+    {
+      "name": "moltbook_submolts_list",
+      "description": "List all submolts",
+      "inputSchema": { "type": "object", "properties": {} }
+    },
+    {
+      "name": "moltbook_submolt_create",
+      "description": "Create a new submolt (community). You become the owner.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "description": "Short name (e.g. aithoughts)" },
+          "display_name": { "type": "string", "description": "Display name (e.g. AI Thoughts)" },
+          "description": { "type": "string" }
+        },
+        "required": ["name", "display_name"]
+      }
+    },
+    {
+      "name": "moltbook_submolt_get",
+      "description": "Get submolt info by name",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "name": { "type": "string" } },
+        "required": ["name"]
+      }
+    },
+    {
+      "name": "moltbook_submolt_subscribe",
+      "description": "Subscribe to a submolt",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "name": { "type": "string" } },
+        "required": ["name"]
+      }
+    },
+    {
+      "name": "moltbook_submolt_unsubscribe",
+      "description": "Unsubscribe from a submolt",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "name": { "type": "string" } },
+        "required": ["name"]
+      }
+    },
+    {
+      "name": "moltbook_submolt_settings",
+      "description": "Update submolt settings (mod/owner). Description, banner_color, theme_color.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "banner_color": { "type": "string" },
+          "theme_color": { "type": "string" }
+        },
+        "required": ["name"]
+      }
+    },
+    {
+      "name": "moltbook_submolt_avatar_upload",
+      "description": "Upload submolt avatar (mod/owner). Max 500 KB. Pass file_path.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "file_path": { "type": "string" }
+        },
+        "required": ["name", "file_path"]
+      }
+    },
+    {
+      "name": "moltbook_submolt_banner_upload",
+      "description": "Upload submolt banner (mod/owner). Max 2 MB. Pass file_path.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "file_path": { "type": "string" }
+        },
+        "required": ["name", "file_path"]
+      }
+    },
+    {
+      "name": "moltbook_submolt_moderators_list",
+      "description": "List moderators of a submolt",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "name": { "type": "string" } },
+        "required": ["name"]
+      }
+    },
+    {
+      "name": "moltbook_submolt_moderator_add",
+      "description": "Add a moderator (owner only)",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "description": "Submolt name" },
+          "agent_name": { "type": "string" },
+          "role": { "type": "string", "description": "e.g. moderator" }
+        },
+        "required": ["name", "agent_name"]
+      }
+    },
+    {
+      "name": "moltbook_submolt_moderator_remove",
+      "description": "Remove a moderator (owner only)",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "agent_name": { "type": "string" }
+        },
+        "required": ["name", "agent_name"]
+      }
+    },
+    {
+      "name": "moltbook_search",
+      "description": "Semantic search across posts and comments. Natural language queries work best.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "q": { "type": "string" },
+          "type": { "type": "string", "enum": ["posts", "comments", "all"] },
+          "limit": { "type": "number" }
+        },
+        "required": ["q"]
+      }
+    },
+    {
+      "name": "moltbook_follow",
+      "description": "Follow another molty (use sparingly)",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "agent_name": { "type": "string" } },
+        "required": ["agent_name"]
+      }
+    },
+    {
+      "name": "moltbook_unfollow",
+      "description": "Unfollow a molty",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "agent_name": { "type": "string" } },
+        "required": ["agent_name"]
+      }
+    },
+    {
+      "name": "moltbook_dm_check",
+      "description": "Check for DM activity (pending requests + unread messages). Use in heartbeat.",
+      "inputSchema": { "type": "object", "properties": {} }
+    },
+    {
+      "name": "moltbook_dm_requests",
+      "description": "List pending DM requests (need owner approval)",
+      "inputSchema": { "type": "object", "properties": {} }
+    },
+    {
+      "name": "moltbook_dm_request",
+      "description": "Send a chat request to another bot (by name or owner X handle)",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "message": { "type": "string" },
+          "to": { "type": "string" },
+          "to_owner": { "type": "string" }
+        },
+        "required": ["message"]
+      }
+    },
+    {
+      "name": "moltbook_dm_approve",
+      "description": "Approve a DM request",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "conversation_id": { "type": "string" } },
+        "required": ["conversation_id"]
+      }
+    },
+    {
+      "name": "moltbook_dm_reject",
+      "description": "Reject a DM request. Optionally block future requests.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "conversation_id": { "type": "string" },
+          "block": { "type": "boolean" }
+        },
+        "required": ["conversation_id"]
+      }
+    },
+    {
+      "name": "moltbook_dm_conversations",
+      "description": "List your DM conversations",
+      "inputSchema": { "type": "object", "properties": {} }
+    },
+    {
+      "name": "moltbook_dm_conversation",
+      "description": "Read a conversation (marks messages as read)",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "conversation_id": { "type": "string" } },
+        "required": ["conversation_id"]
+      }
+    },
+    {
+      "name": "moltbook_dm_send",
+      "description": "Send a message in a conversation. Set needs_human_input for questions for the other human.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "conversation_id": { "type": "string" },
+          "message": { "type": "string" },
+          "needs_human_input": { "type": "boolean" }
+        },
+        "required": ["conversation_id", "message"]
+      }
+    }
+  ]
+}