kontexted 0.1.5 → 0.1.6

package/dist/commands/skill.js

@@ -45,6 +45,54 @@ async function executeNoteById(client, workspaceSlug, notePublicId) {
     }
     return response.json();
 }
+/**
+ * Execute create-folder skill via the API
+ */
+async function executeCreateFolder(client, workspaceSlug, name, displayName, parentPublicId) {
+    const body = { workspaceSlug, name, displayName };
+    if (parentPublicId) {
+        body.parentPublicId = parentPublicId;
+    }
+    const response = await client.post("/api/skill/create-folder", body);
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Create folder skill failed: ${response.status} ${errorText}`);
+    }
+    return response.json();
+}
+/**
+ * Execute create-note skill via the API
+ */
+async function executeCreateNote(client, workspaceSlug, name, title, folderPublicId, content) {
+    const body = { workspaceSlug, name, title };
+    if (folderPublicId) {
+        body.folderPublicId = folderPublicId;
+    }
+    if (content !== undefined) {
+        body.content = content;
+    }
+    const response = await client.post("/api/skill/create-note", body);
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Create note skill failed: ${response.status} ${errorText}`);
+    }
+    return response.json();
+}
+/**
+ * Execute update-note-content skill via the API
+ */
+async function executeUpdateNoteContent(client, workspaceSlug, notePublicId, content) {
+    const response = await client.post("/api/skill/update-note-content", {
+        workspaceSlug,
+        notePublicId,
+        content,
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Update note content skill failed: ${response.status} ${errorText}`);
+    }
+    return response.json();
+}
 /**
  * Helper function to create an API client from a profile alias
  */
@@ -142,6 +190,90 @@ export function registerSkillCommand(program) {
             process.exit(1);
         }
     });
+    skillCommand
+        .command("create-folder")
+        .description("Create a new folder in the workspace")
+        .requiredOption("--alias <name>", "Profile alias to use")
+        .requiredOption("--name <name>", "URL-safe folder name")
+        .requiredOption("--display-name <displayName>", "Human-readable display name")
+        .option("--parent-id <parentPublicId>", "Public ID of parent folder (for nested folders)")
+        .action(async (options) => {
+        try {
+            const client = await createApiClient(options.alias);
+            const config = await readConfig();
+            const profile = getProfile(config, options.alias);
+            if (!profile) {
+                console.error(`Profile not found: ${options.alias}. Run 'kontexted login' first.`);
+                process.exit(1);
+            }
+            if (!profile.write) {
+                console.error("Error: Write operations not enabled for this profile. Re-login with 'kontexted login --alias <alias> --write' to enable write access.");
+                process.exit(1);
+            }
+            const result = await executeCreateFolder(client, profile.workspace, options.name, options.displayName, options.parentId);
+            displayResult(result);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    skillCommand
+        .command("create-note")
+        .description("Create a new note in the workspace")
+        .requiredOption("--alias <name>", "Profile alias to use")
+        .requiredOption("--name <name>", "URL-safe note name")
+        .requiredOption("--title <title>", "Human-readable note title")
+        .option("--folder-id <folderPublicId>", "Public ID of folder (for notes in folders)")
+        .option("--content <content>", "Initial content for the note")
+        .action(async (options) => {
+        try {
+            const client = await createApiClient(options.alias);
+            const config = await readConfig();
+            const profile = getProfile(config, options.alias);
+            if (!profile) {
+                console.error(`Profile not found: ${options.alias}. Run 'kontexted login' first.`);
+                process.exit(1);
+            }
+            if (!profile.write) {
+                console.error("Error: Write operations not enabled for this profile. Re-login with 'kontexted login --alias <alias> --write' to enable write access.");
+                process.exit(1);
+            }
+            const result = await executeCreateNote(client, profile.workspace, options.name, options.title, options.folderId, options.content);
+            displayResult(result);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    skillCommand
+        .command("update-note-content")
+        .description("Update the content of an existing note")
+        .requiredOption("--alias <name>", "Profile alias to use")
+        .requiredOption("--note-id <notePublicId>", "Public ID of the note to update")
+        .requiredOption("--content <content>", "New content for the note")
+        .action(async (options) => {
+        try {
+            const client = await createApiClient(options.alias);
+            const config = await readConfig();
+            const profile = getProfile(config, options.alias);
+            if (!profile) {
+                console.error(`Profile not found: ${options.alias}. Run 'kontexted login' first.`);
+                process.exit(1);
+            }
+            if (!profile.write) {
+                console.error("Error: Write operations not enabled for this profile. Re-login with 'kontexted login --alias <alias> --write' to enable write access.");
+                process.exit(1);
+            }
+            const result = await executeUpdateNoteContent(client, profile.workspace, options.noteId, options.content);
+            displayResult(result);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
     skillCommand
         .command("init")
         .description("Initialize AI agent skills for the current project")

package/dist/lib/proxy-server.js

@@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { logError } from "../lib/logger.js";
 // Tools that modify data
-const WRITE_TOOLS = new Set(["createFolder", "createNote", "updateNote", "deleteNote", "deleteFolder"]);
+const WRITE_TOOLS = new Set(["createFolder", "createNote", "updateNoteContent", "deleteNote", "deleteFolder"]);
 /**
  * Convert JSON schema to Zod schema, removing workspaceSlug
  */

package/dist/skill-init/templates/kontexted-cli.js

@@ -1,14 +1,24 @@
 export const kontextedCliSkill = {
     name: 'kontexted-cli',
-    description: 'Access and manage Kontexted workspaces, search notes, and retrieve content through the kontexted CLI. Use when the user needs to explore workspace structure, find specific notes, or read note content using profile aliases.',
+    description: 'Access and manage Kontexted workspaces, search notes, retrieve content, and create/update notes and folders through the kontexted CLI. Use when the user needs to explore workspace structure, find specific notes, read note content, or modify workspace content using profile aliases.',
     content: String.raw `# Kontexted CLI Skill Commands
 
+## Read Commands (No --write flag needed)
+
 \`\`\`
 kontexted skill workspace-tree --alias <profile>                    # Get workspace folder/note structure
 kontexted skill search-notes --alias <profile> --query "<text>"    # Search notes
 kontexted skill note-by-id --alias <profile> --note-id <id>        # Get specific note
 \`\`\`
 
+## Write Commands (Require write-enabled profile)
+
+\`\`\`
+kontexted skill create-folder --alias <profile> --name <name> --display-name "<displayName>" [--parent-id <id>]
+kontexted skill create-note --alias <profile> --name <name> --title "<title>" [--folder-id <id>] [--content "<content>"]
+kontexted skill update-note-content --alias <profile> --note-id <id> --content "<content>"
+\`\`\`
+
 ## Prerequisites
 
 Before using the kontexted CLI skill commands, ensure:
@@ -16,12 +26,15 @@ Before using the kontexted CLI skill commands, ensure:
 1. **kontexted CLI is installed** - Install via npm or your preferred package manager
 2. **User has authenticated** - User must have run \`kontexted login\` with a profile alias
 3. **Profile has a workspace configured** - The profile alias must be associated with an active workspace
+4. **Write operations require write-enabled profile** - To use write commands, the profile must have been created with \`kontexted login --write\`
 
 All commands require the \`--alias\` parameter to specify which profile to use. The profile must already be set up and authenticated.
 
 ## Available Tools
 
-### workspace-tree
+### Read Tools
+
+#### workspace-tree
 
 Get the complete folder and note structure of a workspace.
 
@@ -39,7 +52,7 @@ kontexted skill workspace-tree --alias <profile>
 - When exploring available notes before reading specific content
 - When building navigation paths to locate notes
 
-### search-notes
+#### search-notes
 
 Search for notes containing specific text content.
 
@@ -50,16 +63,16 @@ kontexted skill search-notes --alias <profile> --query "<text>" [--limit <n>]
 **Options:**
 - \`--alias\` (required): The profile alias to use for authentication
 - \`--query\` (required): The search text to find in notes
-- \`--limit\` (optional): Maximum number of results to return (default: 10)
+- \`--limit\` (optional): Maximum number of results to return (default: 20, max: 50)
 
-**Returns:** JSON array of matching notes with metadata including note ID, title, and snippets
+**Returns:** JSON array of matching notes with metadata including note ID, title, and relevant snippets
 
 **When to use:**
 - When you need to find notes containing specific keywords
 - When searching for content across multiple notes
 - When the user asks to find notes about a particular topic
 
-### note-by-id
+#### note-by-id
 
 Retrieve the complete content of a specific note by its ID.
 
@@ -78,24 +91,114 @@ kontexted skill note-by-id --alias <profile> --note-id <id>
 - After finding a note via search or workspace tree exploration
 - When the user asks to read a specific note
 
+### Write Tools
+
+#### create-folder
+
+Create a new folder in the workspace. Optionally nest under a parent folder.
+
+\`\`\`bash
+kontexted skill create-folder --alias <profile> --name <name> --display-name "<displayName>" [--parent-id <parentPublicId>]
+\`\`\`
+
+**Options:**
+- \`--alias\` (required): The profile alias to use for authentication
+- \`--name\` (required): URL-safe folder name (kebab-case, camelCase, snake_case, or PascalCase)
+- \`--display-name\` (required): Human-readable display name for the folder
+- \`--parent-id\` (optional): Public ID of parent folder (omit for root level)
+
+**Returns:** JSON object containing the created folder's public ID and metadata
+
+**When to use:**
+- When creating a new folder to organize notes
+- When setting up a hierarchical folder structure
+
+**Error cases:**
+- **"Folder with this name already exists"** - Choose a different name
+- **"Parent folder not found"** - Verify the parent folder ID
+- **"Invalid folder name"** - Use kebab-case, camelCase, snake_case, or PascalCase
+
+#### create-note
+
+Create a new note in the workspace. Optionally place in a folder.
+
+\`\`\`bash
+kontexted skill create-note --alias <profile> --name <name> --title "<title>" [--folder-id <folderPublicId>] [--content "<content>"]
+\`\`\`
+
+**Options:**
+- \`--alias\` (required): The profile alias to use for authentication
+- \`--name\` (required): URL-safe note name (kebab-case, camelCase, snake_case, or PascalCase)
+- \`--title\` (required): Human-readable title for the note
+- \`--folder-id\` (optional): Public ID of folder (omit for root level)
+- \`--content\` (optional): Initial content for the note (defaults to empty)
+
+**Returns:** JSON object containing the created note's public ID and metadata
+
+**When to use:**
+- When creating a new note in the workspace
+- When the user asks to write or create a document/note
+
+**Error cases:**
+- **"Note with this name already exists"** - Choose a different name
+- **"Folder not found"** - Verify the folder ID
+- **"Invalid note name"** - Use kebab-case, camelCase, snake_case, or PascalCase
+
+#### update-note-content
+
+Update the content of an existing note. This creates a revision for history.
+
+\`\`\`bash
+kontexted skill update-note-content --alias <profile> --note-id <notePublicId> --content "<content>"
+\`\`\`
+
+**Options:**
+- \`--alias\` (required): The profile alias to use for authentication
+- \`--note-id\` (required): Public ID of the note to update
+- \`--content\` (required): New content for the note
+
+**Returns:** JSON object containing the note's public ID, revision ID, and updated timestamp
+
+**When to use:**
+- When updating the content of an existing note
+- When the user asks to edit or modify a note's content
+- When appending or replacing note content
+
+**Important notes:**
+- This operation replaces the entire note content
+- A revision is created for history tracking
+- Connected clients are notified in real-time
+
+**Error cases:**
+- **"Note not found"** - Verify the note ID
+- **"Invalid note public ID"** - Check the ID format
+
 ## Typical Workflow
 
 The skill commands work best when combined in a logical sequence:
 
+### Read-Only Workflow
+
 1. **Explore** - Use \`workspace-tree\` to understand workspace structure
 2. **Search** - Use \`search-notes\` to find relevant notes by content
 3. **Read** - Use \`note-by-id\` to retrieve full content of specific notes
 
-**Example workflow:**
+### Write Workflow
+
+1. **Create structure** - Use \`create-folder\` to organize content
+2. **Create notes** - Use \`create-note\` to create new notes
+3. **Update content** - Use \`update-note-content\` to modify existing notes
+
+**Example write workflow:**
 \`\`\`bash
-# First, explore the workspace structure
-kontexted skill workspace-tree --alias work
+# Create a folder for project documentation
+kontexted skill create-folder --alias work --name "project-docs" --display-name "Project Documentation"
 
-# Then, search for notes containing specific content
-kontexted skill search-notes --alias work --query "project planning" --limit 5
+# Create a note in that folder (use the returned publicId)
+kontexted skill create-note --alias work --name "requirements" --title "Requirements" --folder-id "FOLDER_PUBLIC_ID"
 
-# Finally, read the content of notes of interest
-kontexted skill note-by-id --alias work --note-id "abc123"
+# Update the note content
+kontexted skill update-note-content --alias work --note-id "NOTE_PUBLIC_ID" --content "# Requirements\n\n- Feature A\n- Feature B"
 \`\`\`
 
 ## Example Usage
@@ -124,16 +227,35 @@ kontexted skill search-notes --alias work --query "todo" --limit 3
 kontexted skill note-by-id --alias work --note-id "note-uuid-123"
 \`\`\`
 
-### Combining commands in a single task
+### Creating a folder structure
+
+\`\`\`bash
+# Create a root-level folder
+kontexted skill create-folder --alias work --name "meetings" --display-name "Meeting Notes"
+
+# Create a nested folder (use the returned publicId as parent-id)
+kontexted skill create-folder --alias work --name "2024" --display-name "2024 Meetings" --parent-id "PARENT_FOLDER_ID"
+\`\`\`
+
+### Creating and populating a note
 
 \`\`\`bash
-# Task: Find and read notes about project requirements
-# Step 1: Search for relevant notes
-kontexted skill search-notes --alias work --query "requirements" --limit 5
+# Create a note with initial content
+kontexted skill create-note --alias work --name "todo" --title "Todo List" --content "# Todo\n\n- [ ] Task 1\n- [ ] Task 2"
 
-# Step 2: Read each matching note
-kontexted skill note-by-id --alias work --note-id "req-001"
-kontexted skill note-by-id --alias work --note-id "req-002"
+# Later, update the note content
+kontexted skill update-note-content --alias work --note-id "NOTE_ID" --content "# Todo\n\n- [x] Task 1\n- [ ] Task 2\n- [ ] Task 3"
+\`\`\`
+
+### Combining read and write operations
+
+\`\`\`bash
+# Task: Find a note and update it
+# Step 1: Search for the note
+kontexted skill search-notes --alias work --query "meeting notes"
+
+# Step 2: Update the found note
+kontexted skill update-note-content --alias work --note-id "FOUND_NOTE_ID" --content "Updated content here"
 \`\`\`
 
 ## Error Handling
@@ -148,6 +270,14 @@ If you encounter authentication errors:
 
 3. **"No workspace configured"** - The profile is authenticated but has no workspace. Ask the user to set up a workspace with \`kontexted workspace set --alias <profile>\`.
 
+### Write operation errors
+
+1. **"Write operations not enabled for this profile"** - Re-login with \`kontexted login --alias <alias> --write\` to enable write access
+2. **"Folder with this name already exists"** - Use a unique name or check existing folders
+3. **"Note with this name already exists"** - Use a unique name or check existing notes
+4. **"Parent folder not found"** - Verify the parent folder ID exists
+5. **"Note not found"** - Verify the note ID is correct
+
 ### Other errors
 
 - **"Note not found"** - The specified note ID doesn't exist or belongs to a different workspace
@@ -160,10 +290,16 @@ When errors occur, report them clearly to the user so they can take appropriate
 
 All commands return JSON output that is easy to parse:
 
+### Read commands
 - \`workspace-tree\`: Returns nested object with folders and notes
 - \`search-notes\`: Returns array of matching notes with ID, title, and snippets
 - \`note-by-id\`: Returns complete note object with body and metadata
 
+### Write commands
+- \`create-folder\`: Returns \`{ folder: { publicId, name, displayName, parentPublicId } }\`
+- \`create-note\`: Returns \`{ note: { publicId, name, title, folderPublicId, content } }\`
+- \`update-note-content\`: Returns \`{ note: { publicId, revisionId, updatedAt } }\`
+
 Use this structured output to provide clear responses to users about workspace contents and note information.
 `
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kontexted",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "CLI tool for Kontexted - MCP proxy, workspaces management, and local server",
   "type": "module",
   "bin": {
@@ -43,8 +43,8 @@
     "typescript": "^5.6.0"
   },
   "optionalDependencies": {
-    "@kontexted/darwin-arm64": "0.1.5",
-    "@kontexted/linux-x64": "0.1.5",
-    "@kontexted/windows-x64": "0.1.5"
+    "@kontexted/darwin-arm64": "0.1.6",
+    "@kontexted/linux-x64": "0.1.6",
+    "@kontexted/windows-x64": "0.1.6"
   }
 }