rootr-cli 0.1.0

package/lib/mcp-tools/webhooks.js

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+
+import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+
+const VALID_EVENTS = [
+  'document.created',
+  'document.updated',
+  'document.moved',
+  'document.deleted',
+  'comment.created',
+  'extraction.completed',
+  'extraction.failed',
+  'log.anomaly.rca',
+  'scaffold.applied',
+];
+
+/** Webhook management tools: list/create/delete. Requires webhooks:manage scope. */
+export function registerWebhookTools(server) {
+  server.registerTool(
+    'rootr_list_webhooks',
+    {
+      title: 'List webhooks configured on a workspace',
+      description:
+        'List webhooks configured on a Rootr (루터) workspace. Secrets are not re-shown here (they only appear ' +
+        'once, at creation time).',
+      inputSchema: {
+        workspace: z
+          .string()
+          .optional()
+          .describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const result = await client.listWebhooks(ws);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_create_webhook',
+    {
+      title: 'Create a webhook',
+      description:
+        `Create a webhook on a Rootr (루터) workspace. Valid events: ${VALID_EVENTS.join(', ')}. ` +
+        'Optionally scope it to a subtree (scopeNodeId, inherited by descendants) and/or a tag filter (filterTags). ' +
+        'debounceSeconds coalesces bursts of events (server enforces a fixed trailing debounce with a cap). ' +
+        'IMPORTANT: the response secret is shown ONLY ONCE, in this call\'s result — copy it now, it will not be ' +
+        'shown again. LOOP GUARD: deliveries carry the actor as data.actorId ("apikey:<key-id>" for API writes) — ' +
+        'a consumer MUST skip deliveries caused by its own key before reacting, or an agent that writes on ' +
+        'notification will trigger itself forever.',
+      inputSchema: {
+        url: z.string().describe('HTTPS endpoint to receive webhook POSTs'),
+        events: z.array(z.string()).describe(`Event names to subscribe to, from: ${VALID_EVENTS.join(', ')}`),
+        name: z.string().optional().describe('Human-readable name for the webhook'),
+        scopeNodeId: z.string().optional().describe('Restrict to this node and its descendants'),
+        filterTags: z.array(z.string()).optional().describe('Only fire for nodes carrying one of these tags'),
+        debounceSeconds: z.number().optional().describe('Trailing debounce window in seconds (server-capped)'),
+        workspace: z
+          .string()
+          .optional()
+          .describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ url, events, name, scopeNodeId, filterTags, debounceSeconds, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const result = await client.createWebhook(ws, {
+          name,
+          url,
+          events,
+          scopeNodeId,
+          filterTags,
+          debounceSeconds,
+        });
+        const note =
+          '\n\n(This secret will not be shown again — store it now if you need to verify signatures.)';
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) + note }] };
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_delete_webhook',
+    {
+      title: 'Delete a webhook',
+      description: 'Delete a webhook from a Rootr (루터) workspace. This cannot be undone.',
+      inputSchema: {
+        webhookId: z.string().describe('Webhook id to delete'),
+        workspace: z
+          .string()
+          .optional()
+          .describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ webhookId, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        await client.deleteWebhook(ws, webhookId);
+        return jsonResult({ deleted: webhookId });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/workspaces.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+
+import { textResult, jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+
+/** Workspace listing and scaffolding tools: rootr_workspaces, rootr_scaffold_plan, rootr_create_workspace, rootr_scaffold_apply. */
+export function registerWorkspaceTools(server) {
+  server.registerTool(
+    'rootr_workspaces',
+    {
+      title: 'List my Rootr workspaces',
+      description:
+        'List the Rootr (루터) workspaces the current API key can see. Works with either key type: with an ' +
+        'account key (PAT) this lists all workspaces you belong to; a workspace key only sees the workspace ' +
+        "it's scoped to. Use this to find a workspace id before calling other workspace-scoped tools.",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        const client = makeClient();
+        const workspaces = await client.listWorkspaces();
+        const rows = workspaces.map((w) => `${w.id}\t${w.name || w.slug || ''}`);
+        return textResult(rows.length ? rows.join('\n') : '(no workspaces visible to this key)');
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_scaffold_plan',
+    {
+      title: 'Plan a workspace scaffold from an intent — then ASK THE USER before building',
+      description:
+        'Step 1 of scaffolding, ALWAYS call this first. Given a natural-language intent (e.g. "SRE 온콜 위키" or ' +
+        '"sales CRM for a 5-person team"), Rootr\'s consultant returns a questionPolicy (ask the user MIN 3, up ' +
+        'to 10 clarifying questions — this is not optional), the dimensions to cover, domain frameworks, and the ' +
+        'buildingBlocks menu (DATABASE/DOCUMENT/SPREADSHEET/WHITEBOARD/FORM/ISSUE_TRACKER/FOLDER). You must then ' +
+        'GENERATE your own questions from those frameworks, ask the user, and only design the tree AFTER their ' +
+        'answers — every answer must visibly shape the result. Never build straight from a one-line intent. ' +
+        'No workspace needed; create with rootr_create_workspace or rootr_scaffold_apply afterwards.',
+      inputSchema: {
+        intent: z.string().describe('Natural-language description of what the workspace/tree should be for'),
+      },
+    },
+    async ({ intent }) => {
+      try {
+        const client = makeClient();
+        const plan = await client.scaffoldPlan(intent);
+        return jsonResult(plan);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_create_workspace',
+    {
+      title: 'Create a brand-new Rootr workspace from a scaffold tree',
+      description:
+        'Create an entirely new Rootr (루터) workspace pre-populated with the given document tree. ' +
+        'REQUIRES an account key (PAT) with the workspaces:create scope — a workspace-scoped key cannot do this. ' +
+        'PRECONDITION: call rootr_scaffold_plan first and ask the user its 3-10 clarifying questions; design the ' +
+        'tree from their answers. Build a real tool, not a pile of thin markdown files: mix DATABASE (board/' +
+        'timeline views, seed rows), SPREADSHEET (formulas), FORM, ISSUE_TRACKER and rich multi-section DOCUMENTs ' +
+        'where they fit, and set an emoji `icon` on folders/databases/key documents. The `tree` shape follows ' +
+        'the scaffold schema in llms.txt (max 200 nodes). AFTER creating: if your runtime can receive HTTP ' +
+        'callbacks, offer the user to register a webhook on the new tree (rootr_create_webhook with scopeNodeId) ' +
+        'so changes flow back to you — skip your own actorId to avoid self-triggering.',
+      inputSchema: {
+        name: z.string().describe('Name for the new workspace'),
+        intent: z.string().optional().describe('Original natural-language intent, for reference/regeneration'),
+        tree: z.any().describe('Scaffold tree to populate the new workspace with (see llms.txt tree schema)'),
+      },
+    },
+    async ({ name, intent, tree }) => {
+      try {
+        const client = makeClient();
+        const result = await client.createWorkspaceScaffold({ name, intent, tree });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_scaffold_apply',
+    {
+      title: 'Apply a scaffold tree to an existing workspace',
+      description:
+        'Create the given document tree inside an existing Rootr (루터) workspace, optionally rooted under an ' +
+        'existing path. Works with a workspace key (docs:write scope). PRECONDITION: call rootr_scaffold_plan ' +
+        'first and ask the user its 3-10 clarifying questions; design the tree from their answers (same quality ' +
+        'bar as rootr_create_workspace — real building blocks with icons/views/seed content, not thin markdown). ' +
+        'AFTER creating: if your runtime can receive HTTP callbacks, offer a webhook on the new subtree ' +
+        '(rootr_create_webhook with scopeNodeId) so changes flow back to you — skip your own actorId.',
+      inputSchema: {
+        tree: z.any().describe('Scaffold tree to create (see llms.txt tree schema)'),
+        rootPath: z.string().optional().describe('Existing path to root the new tree under, e.g. "/projects"'),
+        workspace: z
+          .string()
+          .optional()
+          .describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ tree, rootPath, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const result = await client.scaffoldApply(ws, { rootPath, tree });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp.js

@@ -0,0 +1,50 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { registerDocumentTools } from './mcp-tools/documents.js';
+import { registerWorkspaceTools } from './mcp-tools/workspaces.js';
+import { registerLogTools } from './mcp-tools/logs.js';
+import { registerAskTools } from './mcp-tools/ask.js';
+import { registerIssueTools } from './mcp-tools/issues.js';
+import { registerWebhookTools } from './mcp-tools/webhooks.js';
+import { registerMiscTools } from './mcp-tools/misc.js';
+
+export async function startMcpServer({ name, version }) {
+  const server = new McpServer(
+    { name, version },
+    {
+      instructions:
+        'Rootr (pronounced "루터" in Korean — when the user says 루터, they mean Rootr) is the team\'s ' +
+        'cloud document workspace. Use these tools whenever the user asks to read, write, append to, ' +
+        'edit, or search their Rootr/루터 documents. Prefer rootr_append for adding content and ' +
+        'rootr_edit for targeted changes; use rootr_write only for full rewrites. Beyond documents, this ' +
+        'server also covers workspace scaffolding (planning/creating/applying document trees), typed LOG ' +
+        'datastores (structured entries + stats), GraphRAG root-cause Q&A (rootr_ask), GitHub-style issue ' +
+        'trackers, and webhooks.\n\n' +
+        'Node types — pick the block that fits, never fake everything with markdown files: ' +
+        'DOCUMENT = free-form markdown narrative (overviews, specs, decision logs); ' +
+        'DATABASE = typed columns + views (table/board/calendar/timeline) for anything trackable — tasks, requirements, risks, milestones; ' +
+        'SPREADSHEET = grid with formulas when content needs calculation (budgets, models, estimates); ' +
+        'WHITEBOARD = freeform visual canvas (flow diagrams, brainstorming, journey maps); ' +
+        'FORM = fillable intake from people outside the tree, optionally feeding a DATABASE (surveys, request queues); ' +
+        'ISSUE_TRACKER = GitHub-style issues with #numbers, states, labels, comments (bug/work tracking with a lifecycle); ' +
+        'FOLDER = grouping; LOG store = typed event table whose relation fields auto-build a lineage graph (metrics, incidents, pipeline events — use the rootr_*_log_* tools).\n\n' +
+        'Scaffolding discipline: ALWAYS rootr_scaffold_plan first, ask the user the 3-10 clarifying questions it ' +
+        'prescribes, and only then design and create the tree — every answer must visibly shape the structure. ' +
+        'If your runtime can receive HTTP callbacks, offer to close the loop after scaffolding: register a webhook ' +
+        'scoped to the new tree (rootr_create_webhook) so changes flow back to you — and ALWAYS skip deliveries ' +
+        'whose actorId is your own key, or you will trigger yourself in an infinite loop.',
+    },
+  );
+
+  registerDocumentTools(server);
+  registerWorkspaceTools(server);
+  registerLogTools(server);
+  registerAskTools(server);
+  registerIssueTools(server);
+  registerWebhookTools(server);
+  registerMiscTools(server);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/lib/resolve.js

@@ -0,0 +1,30 @@
+import { RootrApiError } from './client.js';
+
+/**
+ * Resolve a CLI/MCP "target" argument to a node id.
+ * If it starts with '/', treat it as a path and look it up via by-path
+ * (requires a workspace to be configured). Otherwise treat it as an id already.
+ *
+ * Returns { id, existed, path } where existed indicates whether the path
+ * resolved to an existing node (always true for id-form targets, since we
+ * don't verify those against the API).
+ */
+export async function resolveTarget(client, target) {
+  if (!target.startsWith('/')) {
+    return { id: target, existed: true, path: undefined };
+  }
+
+  const node = await client.getNodeByPath(target);
+  if (!node) {
+    return { id: undefined, existed: false, path: target };
+  }
+  const id = node.id || (node.node && node.node.id);
+  return { id, existed: true, path: target, node: node.node || node };
+}
+
+export function requireResolved(resolved) {
+  if (!resolved.existed || !resolved.id) {
+    throw new RootrApiError(`경로를 찾을 수 없습니다: ${resolved.path}`);
+  }
+  return resolved.id;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "rootr-cli",
+  "version": "0.1.0",
+  "description": "Official Rootr CLI + MCP server — read, write, edit and search Rootr documents from the shell or from an AI agent.",
+  "type": "module",
+  "bin": {
+    "rootr": "bin/rootr.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "keywords": [
+    "rootr",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "knowledge-base",
+    "markdown",
+    "cli"
+  ],
+  "homepage": "https://rootr.io",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  }
+}