nodebb-plugin-integration 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodebb-plugin-integration",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "AI integration layer for NodeBB forums with MCP, semantic search, RAG and Qdrant knowledge pipeline",
   "main": "library.js",
   "license": "MIT",
@@ -16,7 +16,8 @@
     "languages",
     "README.md",
     "README.ru.md",
-    "LICENSE"
+    "LICENSE",
+    "docs"
   ],
   "keywords": [
     "nodebb",

package/src/mcp/server.js

@@ -228,7 +228,7 @@ async function start(rawConfig) {
                 requestMcpServer = new Server(
                     {
                         name: "nodebb-integration-mcp",
-                        version: "0.5.0"
+                        version: "0.6.0"
                     },
                     {
                         capabilities: {

package/src/mcp/tools.js

@@ -12,24 +12,20 @@ const definitions = [
     },
     {
         name: "get_post",
-        description: "Get a forum post by its post ID. Access permissions are checked by NodeBB.",
+        description: "Get a forum post by ID. NodeBB access permissions are checked.",
         inputSchema: {
             type: "object",
-            properties: {
-                pid: { type: "integer", minimum: 1 }
-            },
+            properties: { pid: { type: "integer", minimum: 1 } },
             required: ["pid"],
             additionalProperties: false
         }
     },
     {
         name: "get_topic",
-        description: "Get a forum topic by its topic ID. Access permissions are checked by NodeBB.",
+        description: "Get a forum topic by ID. NodeBB access permissions are checked.",
         inputSchema: {
             type: "object",
-            properties: {
-                tid: { type: "integer", minimum: 1 }
-            },
+            properties: { tid: { type: "integer", minimum: 1 } },
             required: ["tid"],
             additionalProperties: false
         }
@@ -39,9 +35,7 @@ const definitions = [
         description: "Get public profile information for a forum user",
         inputSchema: {
             type: "object",
-            properties: {
-                uid: { type: "integer", minimum: 1 }
-            },
+            properties: { uid: { type: "integer", minimum: 1 } },
             required: ["uid"],
             additionalProperties: false
         }
@@ -58,66 +52,292 @@ const definitions = [
             required: ["query"],
             additionalProperties: false
         }
+    },
+    {
+        name: "create_topic",
+        description: "Create a topic in a NodeBB category as the configured MCP service user",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cid: { type: "integer", minimum: 1 },
+                title: { type: "string", minLength: 1, maxLength: 255 },
+                content: { type: "string", minLength: 1, maxLength: 20000 },
+                tags: {
+                    type: "array",
+                    maxItems: 10,
+                    items: { type: "string", minLength: 1, maxLength: 32 }
+                }
+            },
+            required: ["cid", "title", "content"],
+            additionalProperties: false
+        }
+    },
+    {
+        name: "delete_topic",
+        description: "Soft-delete a topic using NodeBB permissions and hooks",
+        inputSchema: {
+            type: "object",
+            properties: { tid: { type: "integer", minimum: 1 } },
+            required: ["tid"],
+            additionalProperties: false
+        }
+    },
+    {
+        name: "restore_topic",
+        description: "Restore a soft-deleted topic using NodeBB permissions and hooks",
+        inputSchema: {
+            type: "object",
+            properties: { tid: { type: "integer", minimum: 1 } },
+            required: ["tid"],
+            additionalProperties: false
+        }
+    },
+    {
+        name: "list_topics",
+        description: "List topics visible to the configured MCP service user",
+        inputSchema: {
+            type: "object",
+            properties: {
+                start: { type: "integer", minimum: 0 },
+                limit: { type: "integer", minimum: 1, maximum: 100 },
+                sort: {
+                    type: "string",
+                    enum: ["recent", "old", "create", "posts", "votes", "views"]
+                },
+                cid: { type: "integer", minimum: 1 }
+            },
+            additionalProperties: false
+        }
+    },
+    {
+        name: "create_post",
+        description: "Create a reply in a topic using NodeBB permissions and hooks",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tid: { type: "integer", minimum: 1 },
+                content: { type: "string", minLength: 1, maxLength: 20000 }
+            },
+            required: ["tid", "content"],
+            additionalProperties: false
+        }
+    },
+    {
+        name: "edit_post",
+        description: "Edit a post using NodeBB permissions and edit restrictions",
+        inputSchema: {
+            type: "object",
+            properties: {
+                pid: { type: "integer", minimum: 1 },
+                content: { type: "string", minLength: 1, maxLength: 20000 }
+            },
+            required: ["pid", "content"],
+            additionalProperties: false
+        }
+    },
+    {
+        name: "delete_post",
+        description: "Soft-delete a post using NodeBB permissions and hooks",
+        inputSchema: {
+            type: "object",
+            properties: { pid: { type: "integer", minimum: 1 } },
+            required: ["pid"],
+            additionalProperties: false
+        }
+    },
+    {
+        name: "restore_post",
+        description: "Restore a soft-deleted post using NodeBB permissions and hooks",
+        inputSchema: {
+            type: "object",
+            properties: { pid: { type: "integer", minimum: 1 } },
+            required: ["pid"],
+            additionalProperties: false
+        }
+    },
+    {
+        name: "delete_user_posts",
+        description: "Soft-delete up to 100 replies by a user. The first post of every topic is skipped. Use start to process subsequent batches.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                uid: { type: "integer", minimum: 1 },
+                start: { type: "integer", minimum: 0 },
+                limit: { type: "integer", minimum: 1, maximum: 100 }
+            },
+            required: ["uid"],
+            additionalProperties: false
+        }
+    },
+    {
+        name: "list_posts",
+        description: "List posts in a topic with NodeBB access filtering and pagination",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tid: { type: "integer", minimum: 1 },
+                start: { type: "integer", minimum: 0 },
+                limit: { type: "integer", minimum: 1, maximum: 100 },
+                reverse: { type: "boolean" }
+            },
+            required: ["tid"],
+            additionalProperties: false
+        }
     }
 ];
 
+const allowedArguments = {
+    get_forum_info: [],
+    get_post: ["pid"],
+    get_topic: ["tid"],
+    get_user: ["uid"],
+    search_knowledge: ["query", "limit"],
+    create_topic: ["cid", "title", "content", "tags"],
+    delete_topic: ["tid"],
+    restore_topic: ["tid"],
+    list_topics: ["start", "limit", "sort", "cid"],
+    create_post: ["tid", "content"],
+    edit_post: ["pid", "content"],
+    delete_post: ["pid"],
+    restore_post: ["pid"],
+    delete_user_posts: ["uid", "start", "limit"],
+    list_posts: ["tid", "start", "limit", "reverse"]
+};
+
+function requireId(args, key) {
+    if (!Number.isSafeInteger(args[key]) || args[key] < 1) {
+        throw new Error(`Invalid ${key}`);
+    }
+}
+
+function requireText(args, key, maximum) {
+    if (typeof args[key] !== "string" ||
+        !args[key].trim() || args[key].length > maximum) {
+        throw new Error(`Invalid ${key}`);
+    }
+}
+
+function pageValue(value, fallback, maximum, name) {
+    const result = value === undefined ? fallback : value;
+
+    if (!Number.isSafeInteger(result) || result < 0 || result > maximum) {
+        throw new Error(`Invalid ${name}`);
+    }
+
+    return result;
+}
+
 function validateArguments(name, args) {
     if (!args || typeof args !== "object" || Array.isArray(args)) {
         throw new Error("Tool arguments must be an object");
     }
 
-    const allowed = {
-        get_forum_info: [],
-        get_post: ["pid"],
-        get_topic: ["tid"],
-        get_user: ["uid"],
-        search_knowledge: ["query", "limit"]
-    }[name];
+    const allowed = allowedArguments[name];
 
-    if (!allowed) {
-        throw new Error(`Unknown MCP tool: ${name}`);
-    }
+    if (!allowed) throw new Error(`Unknown MCP tool: ${name}`);
 
-    if (Object.keys(args).some((key) => !allowed.includes(key))) {
+    if (Object.keys(args).some(key => !allowed.includes(key))) {
         throw new Error("Unexpected tool argument");
     }
 
-    if (name === "get_forum_info") {
-        return {};
+    if (name === "get_forum_info") return {};
+
+    if (["get_post", "get_topic", "get_user",
+        "delete_topic", "restore_topic",
+        "delete_post", "restore_post"].includes(name)) {
+        const key = name.endsWith("_post") || name === "get_post"
+            ? "pid" : name.endsWith("_topic") || name === "get_topic"
+                ? "tid" : "uid";
+
+        requireId(args, key);
+        return { [key]: args[key] };
     }
 
-    if (name === "get_post" || name === "get_topic" || name === "get_user") {
-        const key = name === "get_post"
-            ? "pid"
-            : name === "get_topic"
-                ? "tid"
-                : "uid";
+    if (name === "search_knowledge") {
+        requireText(args, "query", 2000);
+        const limit = args.limit === undefined ? 5 : args.limit;
 
-        if (!Number.isSafeInteger(args[key]) || args[key] < 1) {
-            throw new Error(`Invalid ${key}`);
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 20) {
+            throw new Error("Search limit must be from 1 to 20");
         }
 
-        return { [key]: args[key] };
+        return { query: args.query.trim(), limit };
+    }
+
+    if (name === "create_topic") {
+        requireId(args, "cid");
+        requireText(args, "title", 255);
+        requireText(args, "content", 20000);
+
+        const tags = args.tags === undefined ? [] : args.tags;
+
+        if (!Array.isArray(tags) || tags.length > 10 ||
+            tags.some(tag => typeof tag !== "string" ||
+                !tag.trim() || tag.length > 32)) {
+            throw new Error("Invalid tags");
+        }
+
+        return {
+            cid: args.cid,
+            title: args.title.trim(),
+            content: args.content,
+            tags
+        };
     }
 
-    if (
-        typeof args.query !== "string" ||
-        !args.query.trim() ||
-        args.query.length > 2000
-    ) {
-        throw new Error("Search query must contain 1 to 2000 characters");
+    if (name === "create_post" || name === "edit_post") {
+        const key = name === "create_post" ? "tid" : "pid";
+        requireId(args, key);
+        requireText(args, "content", 20000);
+        return { [key]: args[key], content: args.content };
     }
 
-    const limit = args.limit === undefined ? 5 : args.limit;
+    if (name === "list_topics") {
+        const result = {
+            start: pageValue(args.start, 0, 10000000, "start"),
+            limit: pageValue(args.limit, 20, 100, "limit"),
+            sort: args.sort === undefined ? "recent" : args.sort
+        };
+
+        if (!["recent", "old", "create", "posts", "votes", "views"]
+            .includes(result.sort)) {
+            throw new Error("Invalid sort");
+        }
 
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 20) {
-        throw new Error("Search limit must be an integer from 1 to 20");
+        if (args.cid !== undefined) {
+            requireId(args, "cid");
+            result.cid = args.cid;
+        }
+
+        return result;
     }
 
-    return {
-        query: args.query.trim(),
-        limit
-    };
+    if (name === "delete_user_posts") {
+        requireId(args, "uid");
+
+        return {
+            uid: args.uid,
+            start: pageValue(args.start, 0, 10000000, "start"),
+            limit: pageValue(args.limit, 100, 100, "limit")
+        };
+    }
+
+    if (name === "list_posts") {
+        requireId(args, "tid");
+
+        if (args.reverse !== undefined && typeof args.reverse !== "boolean") {
+            throw new Error("Invalid reverse");
+        }
+
+        return {
+            tid: args.tid,
+            start: pageValue(args.start, 0, 10000000, "start"),
+            limit: pageValue(args.limit, 20, 100, "limit"),
+            reverse: args.reverse ?? false
+        };
+    }
+
+    throw new Error(`Unknown MCP tool: ${name}`);
 }
 
 async function execute(name, args = {}, api) {
@@ -127,25 +347,27 @@ async function execute(name, args = {}, api) {
 
     const validated = validateArguments(name, args);
 
-    switch (name) {
-        case "get_forum_info":
-            return api.request("GET", "/api/v3/integration/internal/info");
-
-        case "get_post":
-            return api.request("POST", "/api/v3/integration/internal/post", validated);
-
-        case "get_topic":
-            return api.request("POST", "/api/v3/integration/internal/topic", validated);
-
-        case "get_user":
-            return api.request("POST", "/api/v3/integration/internal/user", validated);
+    const routes = {
+        get_forum_info: ["GET", "/api/v3/integration/internal/info"],
+        get_post: ["POST", "/api/v3/integration/internal/post"],
+        get_topic: ["POST", "/api/v3/integration/internal/topic"],
+        get_user: ["POST", "/api/v3/integration/internal/user"],
+        search_knowledge: ["POST", "/api/v3/integration/internal/search"],
+        create_topic: ["POST", "/api/v3/integration/internal/topic/create"],
+        delete_topic: ["POST", "/api/v3/integration/internal/topic/delete"],
+        restore_topic: ["POST", "/api/v3/integration/internal/topic/restore"],
+        list_topics: ["POST", "/api/v3/integration/internal/topics"],
+        create_post: ["POST", "/api/v3/integration/internal/post/create"],
+        edit_post: ["POST", "/api/v3/integration/internal/post/edit"],
+        delete_post: ["POST", "/api/v3/integration/internal/post/delete"],
+        restore_post: ["POST", "/api/v3/integration/internal/post/restore"],
+        delete_user_posts: ["POST", "/api/v3/integration/internal/user/delete-posts"],
+        list_posts: ["POST", "/api/v3/integration/internal/posts"]
+    };
 
-        case "search_knowledge":
-            return api.request("POST", "/api/v3/integration/internal/search", validated);
+    const [method, path] = routes[name];
 
-        default:
-            throw new Error(`Unknown MCP tool: ${name}`);
-    }
+    return api.request(method, path, validated);
 }
 
 function register(server, api) {
@@ -158,7 +380,7 @@ function register(server, api) {
         tools: definitions
     }));
 
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler(CallToolRequestSchema, async request => {
         const name = request.params.name;
         const args = request.params.arguments || {};
 
@@ -166,22 +388,18 @@ function register(server, api) {
             const result = await execute(name, args, api);
 
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2)
-                    }
-                ]
+                content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
             };
         } catch (error) {
             return {
                 isError: true,
-                content: [
-                    {
-                        type: "text",
-                        text: error.message || "Tool execution failed"
-                    }
-                ]
+                content: [{
+                    type: "text",
+                    text: error.message || "Tool execution failed"
+                }]
             };
         }
     });

package/src/nodebb/posts.js

@@ -3,18 +3,10 @@
 const NodeBB = require("./index");
 
 const META_FIELDS = [
-    "pid",
-    "tid",
-    "uid",
-    "timestamp",
-    "deleted",
-    "cid"
+    "pid", "tid", "uid", "timestamp", "deleted", "cid"
 ];
 
-const CONTENT_FIELDS = [
-    "pid",
-    "content"
-];
+const CONTENT_FIELDS = ["pid", "content"];
 
 function validatePid(pid) {
     pid = Number(pid);
@@ -26,9 +18,18 @@ function validatePid(pid) {
     return pid;
 }
 
+function validateUid(uid) {
+    uid = Number(uid);
+
+    if (!Number.isSafeInteger(uid) || uid <= 0) {
+        throw new TypeError("Invalid user ID");
+    }
+
+    return uid;
+}
+
 async function getPostMeta(pid) {
     pid = validatePid(pid);
-
     const posts = NodeBB.get("posts");
 
     if (typeof posts.getPostFields !== "function") {
@@ -40,7 +41,6 @@ async function getPostMeta(pid) {
 
 async function getPostContent(pid) {
     pid = validatePid(pid);
-
     const posts = NodeBB.get("posts");
 
     if (typeof posts.getPostFields !== "function") {
@@ -61,17 +61,13 @@ async function getPosts(pids = [], uid) {
         throw new TypeError("Invalid user ID");
     }
 
-    const unique = [
-        ...new Set(
-            pids
-                .map(Number)
-                .filter(pid => Number.isSafeInteger(pid) && pid > 0)
+    const unique = [...new Set(
+        pids.map(Number).filter(
+            pid => Number.isSafeInteger(pid) && pid > 0
         )
-    ];
+    )];
 
-    if (!unique.length) {
-        return [];
-    }
+    if (!unique.length) return [];
 
     const posts = NodeBB.get("posts");
 
@@ -84,10 +80,65 @@ async function getPosts(pids = [], uid) {
     return result.posts || result;
 }
 
+async function editPost(pid, uid, content) {
+    pid = validatePid(pid);
+    uid = validateUid(uid);
+
+    const posts = NodeBB.get("posts");
+
+    if (typeof posts.edit !== "function") {
+        throw new Error("NodeBB posts.edit is unavailable");
+    }
+
+    return posts.edit({ pid, uid, content });
+}
+
+async function deletePost(pid, uid) {
+    pid = validatePid(pid);
+    uid = validateUid(uid);
+
+    const posts = NodeBB.get("posts");
+
+    if (!posts.tools || typeof posts.tools.delete !== "function") {
+        throw new Error("NodeBB posts.tools.delete is unavailable");
+    }
+
+    return posts.tools.delete(uid, pid);
+}
+
+async function restorePost(pid, uid) {
+    pid = validatePid(pid);
+    uid = validateUid(uid);
+
+    const posts = NodeBB.get("posts");
+
+    if (!posts.tools || typeof posts.tools.restore !== "function") {
+        throw new Error("NodeBB posts.tools.restore is unavailable");
+    }
+
+    return posts.tools.restore(uid, pid);
+}
+
+async function getUserPostIds(uid, start, stop) {
+    uid = validateUid(uid);
+
+    const users = NodeBB.get("users");
+
+    if (typeof users.getPostIds !== "function") {
+        throw new Error("NodeBB users.getPostIds is unavailable");
+    }
+
+    return users.getPostIds(uid, start, stop);
+}
+
 module.exports = {
     getPostMeta,
     getPostContent,
     getPosts,
+    editPost,
+    deletePost,
+    restorePost,
+    getUserPostIds,
     META_FIELDS,
     CONTENT_FIELDS
 };