remnote-mcp-server 0.14.2 → 0.16.0

package/mcpb/remnote-local/server/fallback-tools.generated.js

@@ -0,0 +1,477 @@
+// Generated by scripts/generate-mcpb-tools.mjs; do not edit by hand.
+export const FALLBACK_TOOLS = [
+  {
+    name: 'remnote_create_note',
+    description:
+      'Create a new note in RemNote with optional content, parent, and exact tag Rem IDs. Supports hierarchical markdown in content and flashcard syntax (e.g. "- Term :: Definition"). At least one of title or content must be provided. Recommended preflight once per session: remnote_status.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: {
+          type: 'string',
+          description: 'The title of the note (optional if content is provided)',
+        },
+        content: {
+          type: 'string',
+          description: 'Content as plain text, child bullets or hierarchical markdown',
+        },
+        parentId: {
+          type: 'string',
+          description: 'Parent Rem ID',
+        },
+        tagRemIds: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          description: 'Exact tag Rem IDs to apply',
+        },
+        asDocument: {
+          type: 'boolean',
+          description:
+            'Mark the created title/root Rem as a document while preserving any concept/card status',
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'remnote_search',
+    description:
+      'Search the RemNote knowledge base. Supports cursor paging through hasMore/nextCursor. For whole-KB orientation, prefer contentMode="structured" with view="compact", depth=1, and childLimit=500. Request ancestorDepth when hierarchy context matters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search query text',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum results (1-150, default: 50)',
+        },
+        cursor: {
+          type: 'string',
+          description: 'Opaque cursor returned by a previous remnote_search response',
+        },
+        contentMode: {
+          type: 'string',
+          enum: ['none', 'markdown', 'structured'],
+          description:
+            'Content rendering mode: "none" omits content (default), "markdown" renders child subtree as indented markdown, "structured" returns nested child objects with remIds',
+        },
+        view: {
+          type: 'string',
+          enum: ['compact', 'standard', 'full'],
+          description: 'Output detail level: compact, standard, or full',
+        },
+        ancestorDepth: {
+          type: 'number',
+          description: 'Number of parent Rems to include, direct parent first (0-20, default: 0)',
+        },
+        depth: {
+          type: 'number',
+          description:
+            'Depth of child hierarchy to render for markdown/structured content (0-10, default: 1)',
+        },
+        childLimit: {
+          type: 'number',
+          description: 'Maximum children per level (1-500, default: 20)',
+        },
+        maxContentLength: {
+          type: 'number',
+          description: 'Maximum character length for rendered content (default: 3000)',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'remnote_search_by_tag',
+    description:
+      'Find notes by exact tag Rem ID. Supports cursor paging through hasMore/nextCursor. Default resultMode="context" returns resolved ancestor context targets with matchedRems; resultMode="tagged" returns directly tagged Rems with context metadata. Request ancestorDepth to include parent-first ancestors on both context results and matchedRems.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tagRemId: {
+          type: 'string',
+          description: 'Exact tag Rem ID to search',
+        },
+        resultMode: {
+          type: 'string',
+          enum: ['context', 'tagged'],
+          description:
+            '"context" returns resolved ancestor context targets with matchedRems (default); "tagged" returns directly tagged Rems with context metadata',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum results (1-150, default: 50)',
+        },
+        contentMode: {
+          type: 'string',
+          enum: ['none', 'markdown', 'structured'],
+          description:
+            'Content rendering mode: "none" omits content (default), "markdown" renders child subtree as indented markdown, "structured" returns nested child objects with remIds',
+        },
+        view: {
+          type: 'string',
+          enum: ['compact', 'standard', 'full'],
+          description: 'Output detail level: compact, standard, or full',
+        },
+        ancestorDepth: {
+          type: 'number',
+          description: 'Number of parent Rems to include, direct parent first (0-20, default: 0)',
+        },
+        depth: {
+          type: 'number',
+          description:
+            'Depth of child hierarchy to render for markdown/structured content (0-10, default: 1)',
+        },
+        childLimit: {
+          type: 'number',
+          description: 'Maximum children per level (1-500, default: 20)',
+        },
+        maxContentLength: {
+          type: 'number',
+          description: 'Maximum character length for rendered content (default: 3000)',
+        },
+        cursor: {
+          type: 'string',
+          description: 'Opaque cursor returned by a previous remnote_search_by_tag response',
+        },
+        timeoutMs: {
+          type: 'number',
+          description:
+            'Per-call bridge wait timeout in milliseconds (1-60000, default: 15000). Does not cancel plugin-side work.',
+        },
+      },
+      required: ['tagRemId'],
+    },
+  },
+  {
+    name: 'remnote_read_note',
+    description:
+      'Read a specific note from RemNote by its Rem ID. For hierarchy traversal, prefer contentMode="structured" and start shallow (depth=1, childLimit=500), then deepen only selected branches. Request ancestorDepth when placement context matters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        remId: {
+          type: 'string',
+          description: 'The Rem ID to read',
+        },
+        depth: {
+          type: 'number',
+          description: 'Depth of child hierarchy to render (0-10, default: 5)',
+        },
+        contentMode: {
+          type: 'string',
+          enum: ['none', 'markdown', 'structured'],
+          description:
+            'Content rendering mode: "markdown" renders child subtree (default), "structured" returns nested child objects with remIds, "none" omits content',
+        },
+        view: {
+          type: 'string',
+          enum: ['compact', 'standard', 'full'],
+          description: 'Output detail level: compact, standard, or full',
+        },
+        ancestorDepth: {
+          type: 'number',
+          description: 'Number of parent Rems to include, direct parent first (0-20, default: 0)',
+        },
+        childLimit: {
+          type: 'number',
+          description: 'Maximum children per level (1-500, default: 100)',
+        },
+        maxContentLength: {
+          type: 'number',
+          description: 'Maximum character length for rendered content (default: 100000)',
+        },
+      },
+      required: ['remId'],
+    },
+  },
+  {
+    name: 'remnote_list_children',
+    description:
+      'List direct child Rems under a parent without rendering a subtree. Use for cheap hierarchy traversal; page with nextCursor when hasMore is true.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        parentRemId: {
+          type: 'string',
+          description: 'Parent Rem ID whose direct children to list',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum direct children (1-150, default: 50)',
+        },
+        cursor: {
+          type: 'string',
+          description: 'Opaque cursor returned by a previous remnote_list_children response',
+        },
+        view: {
+          type: 'string',
+          enum: ['compact', 'standard', 'full'],
+          description: 'Output detail level for child metadata: compact, standard, or full',
+        },
+        ancestorDepth: {
+          type: 'number',
+          description: 'Number of parent Rems to include for each child, direct parent first',
+        },
+      },
+      required: ['parentRemId'],
+    },
+  },
+  {
+    name: 'remnote_update_note',
+    description: 'Update note metadata in RemNote. Use this tool for title changes only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        remId: {
+          type: 'string',
+          description: 'The Rem ID to update',
+        },
+        title: {
+          type: 'string',
+          description: 'New title',
+        },
+      },
+      required: ['remId', 'title'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'remnote_set_document_status',
+    description:
+      'Preview or set whether an existing Rem is marked as a document. Uses dryRun=true by default, preserves Rem ID, children, parent, tags, and concept/card status, and requires write operations to be enabled.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        remId: {
+          type: 'string',
+          description: 'The Rem ID whose document status should change',
+        },
+        isDocument: {
+          type: 'boolean',
+          description: 'Whether the Rem should be marked as a document',
+        },
+        dryRun: {
+          type: 'boolean',
+          description:
+            'Preview the document-status change without mutating RemNote (default: true)',
+        },
+        expectedOldRemType: {
+          type: 'string',
+          enum: ['document', 'dailyDocument', 'concept', 'descriptor', 'portal', 'text'],
+          description:
+            'Optional stale-context guard; reject if current remType differs from this value',
+        },
+      },
+      required: ['remId', 'isDocument'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'remnote_move_note',
+    description:
+      'Safely move an existing Rem and its subtree under a new parent. Defaults to dryRun=true; pass dryRun=false only after user approval. expectedOldParentRemId rejects stale move proposals.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        remId: {
+          type: 'string',
+          description: 'Rem ID to move',
+        },
+        newParentRemId: {
+          type: 'string',
+          description: 'New parent Rem ID',
+        },
+        position: {
+          type: 'string',
+          enum: ['first', 'last', 'before', 'after'],
+          description: 'Where to place the moved Rem under the new parent (default: last)',
+        },
+        siblingRemId: {
+          type: 'string',
+          description: 'Sibling Rem ID required for before/after positioning',
+        },
+        dryRun: {
+          type: 'boolean',
+          description: 'Preview without mutating RemNote (default: true)',
+        },
+        expectedOldParentRemId: {
+          type: 'string',
+          description: 'Reject if the current direct parent differs from this Rem ID',
+        },
+        ancestorDepth: {
+          type: 'number',
+          description: 'Number of parent Rems to include before/after the move',
+        },
+      },
+      required: ['remId', 'newParentRemId'],
+    },
+  },
+  {
+    name: 'remnote_insert_children',
+    description:
+      'Insert new child Rems under a parent at a deterministic position without replacing existing children. Use this for tag description nodes and hierarchy maintenance.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        parentRemId: {
+          type: 'string',
+          description: 'Parent Rem ID that will receive the new children',
+        },
+        content: {
+          type: 'string',
+          description: 'Markdown content to insert as child Rems',
+        },
+        position: {
+          type: 'string',
+          enum: ['first', 'last', 'before', 'after'],
+          description: 'Where to insert the new child Rems',
+        },
+        siblingRemId: {
+          type: 'string',
+          description: 'Sibling Rem ID required when position is before or after',
+        },
+      },
+      required: ['parentRemId', 'content', 'position'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'remnote_replace_children',
+    description:
+      'Replace all direct children under a parent Rem. This is destructive because existing child Rem IDs are removed and may be blocked by bridge policy.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        parentRemId: {
+          type: 'string',
+          description: 'Parent Rem ID whose direct children will be replaced',
+        },
+        content: {
+          type: 'string',
+          description:
+            'Markdown content to use as replacement children; empty string clears all direct children',
+        },
+      },
+      required: ['parentRemId', 'content'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'remnote_update_tags',
+    description:
+      'Add or remove tags from a note by exact tag Rem IDs. Use this for production tagging workflows to avoid ambiguous name lookup.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        remId: {
+          type: 'string',
+          description: 'The Rem ID whose tags should change',
+        },
+        addTagRemIds: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          minItems: 1,
+          description: 'Exact tag Rem IDs to add',
+        },
+        removeTagRemIds: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          minItems: 1,
+          description: 'Exact tag Rem IDs to remove',
+        },
+      },
+      required: ['remId'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'remnote_append_journal',
+    description:
+      "Append content to today's daily document in RemNote with optional exact tag Rem IDs. Recommended preflight once per session: remnote_status.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: {
+          type: 'string',
+          description: "Content to append to today's daily document (markdown supported)",
+        },
+        timestamp: {
+          type: 'boolean',
+          description: 'Include timestamp (default: true)',
+        },
+        tagRemIds: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          description: 'Exact tag Rem IDs to apply',
+        },
+      },
+      required: ['content'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'remnote_get_playbook',
+    description:
+      'Get an operations playbook for MCP agents: status-first recommendation, navigation presets, content-mode guidance, and write-safety decision tree.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'remnote_status',
+    description:
+      'Check bridge connection health, compatibility warnings, and write-policy capabilities. Recommended once per session before write operations.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'remnote_read_table',
+    description:
+      'Read an Advanced Table from RemNote by exact title or Rem ID. Returns the table schema (columns with property types) and row data (cell values). Use this when you need structured tabular data. For simple tag-based queries without table structure, prefer remnote_search_by_tag.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tableRemId: {
+          type: 'string',
+          description: 'Table Rem ID',
+        },
+        tableTitle: {
+          type: 'string',
+          description: 'Exact Advanced Table title',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum rows to return (1-150, default: 50)',
+        },
+        offset: {
+          type: 'number',
+          description: '0-based row offset for pagination (default: 0)',
+        },
+        propertyFilter: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          description: 'Only return these property/column names (all if omitted)',
+        },
+      },
+      description: 'Provide exactly one of tableRemId or tableTitle.',
+    },
+  },
+];

package/mcpb/remnote-local/server/index.js

@@ -2,143 +2,30 @@
 
 import process from 'node:process';
 import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { fileURLToPath, URL, pathToFileURL } from 'node:url';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { FALLBACK_TOOLS } from './fallback-tools.generated.js';
 
-export const DEFAULT_MCP_URL = 'http://127.0.0.1:3001/mcp';
-export const SERVER_INFO = { name: 'remnote-mcp-stdio', version: '0.14.1' };
+export { FALLBACK_TOOLS } from './fallback-tools.generated.js';
 
-export const FALLBACK_TOOLS = [
-  {
-    name: 'remnote_create_note',
-    description:
-      'Create a new note in RemNote with optional content, parent, and tags. Supports hierarchical markdown in content and flashcard syntax.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        title: { type: 'string', description: 'The title of the note' },
-        content: { type: 'string', description: 'Content as plain text or hierarchical markdown' },
-        parentId: { type: 'string', description: 'Parent Rem ID' },
-        tags: { type: 'array', items: { type: 'string' }, description: 'Tags to apply' },
-      },
-    },
-  },
-  {
-    name: 'remnote_search',
-    description: 'Search the RemNote knowledge base.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        query: { type: 'string', description: 'Search query text' },
-        limit: { type: 'number', description: 'Maximum results' },
-        includeContent: { type: 'string', enum: ['none', 'markdown', 'structured'] },
-        depth: { type: 'number', description: 'Depth of child hierarchy to render' },
-        childLimit: { type: 'number', description: 'Maximum children per level' },
-        maxContentLength: { type: 'number', description: 'Maximum rendered content length' },
-      },
-      required: ['query'],
-    },
-  },
-  {
-    name: 'remnote_search_by_tag',
-    description: 'Find notes by tag.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        tag: { type: 'string', description: 'Tag name to search' },
-        limit: { type: 'number', description: 'Maximum results' },
-        includeContent: { type: 'string', enum: ['none', 'markdown', 'structured'] },
-        depth: { type: 'number', description: 'Depth of child hierarchy to render' },
-        childLimit: { type: 'number', description: 'Maximum children per level' },
-        maxContentLength: { type: 'number', description: 'Maximum rendered content length' },
-      },
-      required: ['tag'],
-    },
-  },
-  {
-    name: 'remnote_read_note',
-    description: 'Read a specific note from RemNote by its Rem ID.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        remId: { type: 'string', description: 'The Rem ID to read' },
-        depth: { type: 'number', description: 'Depth of child hierarchy to render' },
-        includeContent: { type: 'string', enum: ['none', 'markdown', 'structured'] },
-        childLimit: { type: 'number', description: 'Maximum children per level' },
-        maxContentLength: { type: 'number', description: 'Maximum rendered content length' },
-      },
-      required: ['remId'],
-    },
-  },
-  {
-    name: 'remnote_update_note',
-    description: 'Update an existing note in RemNote.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        remId: { type: 'string', description: 'The Rem ID to update' },
-        title: { type: 'string', description: 'New title' },
-        appendContent: { type: 'string', description: 'Content to append as children' },
-        replaceContent: { type: 'string', description: 'Content to replace direct children' },
-        addTags: { type: 'array', items: { type: 'string' }, description: 'Tags to add' },
-        removeTags: { type: 'array', items: { type: 'string' }, description: 'Tags to remove' },
-      },
-      required: ['remId'],
-    },
-  },
-  {
-    name: 'remnote_append_journal',
-    description: "Append content to today's daily document in RemNote.",
-    inputSchema: {
-      type: 'object',
-      properties: {
-        content: { type: 'string', description: "Content to append to today's daily document" },
-        timestamp: { type: 'boolean', description: 'Include timestamp' },
-      },
-      required: ['content'],
-    },
-  },
-  {
-    name: 'remnote_read_table',
-    description: 'Read an Advanced Table from RemNote by exact title or Rem ID.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        tableRemId: { type: 'string', description: 'Table Rem ID' },
-        tableTitle: { type: 'string', description: 'Exact Advanced Table title' },
-        limit: { type: 'number', description: 'Maximum rows to return' },
-        offset: { type: 'number', description: '0-based row offset for pagination' },
-        propertyFilter: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Only return these property/column names',
-        },
-      },
-    },
-  },
-  {
-    name: 'remnote_get_playbook',
-    description: 'Get an operations playbook for MCP agents.',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'remnote_status',
-    description:
-      'Check bridge connection health, compatibility warnings, and write-policy capabilities.',
-    inputSchema: { type: 'object', properties: {} },
-  },
-];
+export const DEFAULT_MCP_URL = 'http://127.0.0.1:3001/mcp';
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+export const SERVER_INFO = { name: 'remnote-mcp-stdio', version: packageJson.version };
 
 export function normalizeMcpUrl(value) {
-  const trimmed = String(value || DEFAULT_MCP_URL).trim();
+  const trimmed = String(value || DEFAULT_MCP_URL)
+    .trim()
+    .replace(/\/+$/, '');
   if (trimmed.endsWith('/mcp')) {
     return trimmed;
   }
-  return `${trimmed.replace(/\/+$/, '')}/mcp`;
+  return `${trimmed}/mcp`;
 }
 
 export function createSdkHttpClient(mcpUrl, clientInfo = SERVER_INFO) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remnote-mcp-server",
-  "version": "0.14.2",
+  "version": "0.16.0",
   "description": "MCP server bridge for RemNote knowledge base",
   "type": "module",
   "main": "dist/index.js",
@@ -10,8 +10,10 @@
     "remnote-mcp-stdio": "mcpb/remnote-local/server/index.js"
   },
   "scripts": {
-    "build": "tsc && node scripts/chmod-bins.mjs && node scripts/build-mcpb.mjs",
-    "build:mcpb": "node scripts/build-mcpb.mjs",
+    "build": "tsc && node scripts/chmod-bins.mjs && node scripts/generate-mcpb-tools.mjs && node scripts/build-mcpb.mjs",
+    "build:mcpb": "npm run generate:mcpb-tools && node scripts/build-mcpb.mjs",
+    "generate:mcpb-tools": "tsc && node scripts/generate-mcpb-tools.mjs",
+    "check:mcpb-tools": "tsc && node scripts/generate-mcpb-tools.mjs --check",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",