fix: mcp fs copy, move, rename

src/backend/controllers/apps/AppController.js

@@ -100,7 +100,9 @@ export class AppController extends PuterController {
         return d;
     }
 
-    registerRoutes(router) {
+    registerRoutes(
+        /** @type {import('../../core/http/PuterRouter').PuterRouter} */ router,
+    ) {
         // GET /apps — list apps owned by the current user
         router.get(
             '/apps',
@@ -122,8 +124,7 @@ export class AppController extends PuterController {
             '/apps/nameAvailable',
             {
                 subdomain: 'api',
-                requireUserActor: true,
-                allowFullAccessToken: true,
+                requireAuth: true,
             },
             async (req, res) => {
                 const name = req.query?.name;

src/docs/src/mcp.md

@@ -98,11 +98,14 @@ The Puter MCP server exposes the following tools, grouped by category. Each one
 ### Filesystem
 
 - `fs_write_file`: Create or overwrite a file in your Puter filesystem.
-- `fs_read_file`: Read a file's contents (UTF-8 text, or base64 for binary).
+- `fs_read_file`: Read a file's contents (UTF-8 text, or base64 for binary), optionally just a byte window of it.
 - `fs_readdir`: List the files and subdirectories in a directory.
 - `fs_mkdir`: Create a directory, optionally creating missing parents.
 - `fs_stat`: Get metadata (name, size, type, timestamps) for a file or directory.
 - `fs_delete`: Delete a file or directory.
+- `fs_copy`: Copy a file or directory to another location.
+- `fs_move`: Move a file or directory to another location (also renames).
+- `fs_rename`: Rename a file or directory in place.
 
 ### Hosting
 
@@ -120,6 +123,21 @@ The Puter MCP server exposes the following tools, grouped by category. Each one
 - `workers_get`: Get a single worker's public URL and source file.
 - `workers_delete`: Undeploy a worker.
 
+### Key-value store
+
+Each app has its own KV namespace inside your account. These tools use your own
+user-level store by default; pass `app_uuid` to work in a specific app's store instead.
+
+- `kv_get`: Read a key (a missing key reads as `null`).
+- `kv_set`: Create or overwrite a key, optionally with an expiry timestamp.
+- `kv_del`: Delete a key.
+- `kv_list`: List keys, or key/value pairs, by pattern with pagination.
+- `kv_incr` / `kv_decr`: Change a number, or numbers at given dot paths.
+- `kv_add`: Add to the stored value — sums numbers, appends to arrays.
+- `kv_update`: Set specific dot paths inside a stored object.
+- `kv_remove`: Remove dot paths from a stored object.
+- `kv_expire` / `kv_expire_at`: Expire a key after N seconds, or at a timestamp.
+
 ### Apps
 
 - `apps_create`: Register a launchable Puter app pointing at a URL.

src/mcp-connector/README.md

@@ -19,12 +19,15 @@ OAuth "Sign in with Puter" flow the Worker hosts itself (see
 ### Filesystem
 | Tool | Description |
 | --- | --- |
-| `fs_read_file` | Read a file (UTF-8 or base64; optional offset/length). |
+| `fs_read_file` | Read a file (UTF-8 or base64; optional byte offset/length window). |
 | `fs_stat` | Stat a file or directory (size, type, timestamps, uid). |
 | `fs_write_file` | Create/overwrite a file (UTF-8 or base64 content). |
 | `fs_mkdir` | Create a directory (optionally creating missing parents). |
 | `fs_delete` | Delete a file or directory (recursive by default). |
 | `fs_readdir` | List the entries of a directory. |
+| `fs_copy` | Copy a file or directory to another location. |
+| `fs_move` | Move a file or directory to another location (also renames). |
+| `fs_rename` | Rename a file or directory in place. |
 
 ### Hosting (static websites)
 Publishing a website in Puter means creating a hosting subdomain served at
@@ -53,6 +56,29 @@ its associated file (there is no separate update call).
 | `workers_exec` | Call a worker over HTTP as the authenticated user. |
 | `workers_delete` | Undeploy a worker (leaves its source file in place). |
 
+### Key-value store
+Puter's KV store is namespaced per app inside each user's account. This connector
+authenticates with a **user token**, so these tools read and write the user's own
+namespace by default; every one takes an optional `app_uuid` to target a single
+app's store instead (e.g. the `sandbox-<worker>` app a deployed worker runs as).
+Values are stored as JSON. Tools that take a "dot path" (`profile.bio`) address
+into a stored object; the empty path is the value itself.
+
+| Tool | Description |
+| --- | --- |
+| `kv_get` | Read a key (missing keys read as `null`). |
+| `kv_set` | Create/overwrite a key, optionally with an expiry timestamp. |
+| `kv_del` | Delete a key. |
+| `kv_list` | List keys (or key/value pairs) by pattern, with pagination. |
+| `kv_incr` / `kv_decr` | Change a number, or numbers at given dot paths. |
+| `kv_add` | Add to the stored value (sums numbers, appends to arrays). |
+| `kv_update` | Set specific dot paths inside a stored object. |
+| `kv_remove` | Remove dot paths from a stored object. |
+| `kv_expire` / `kv_expire_at` | Expire a key after N seconds / at a timestamp. |
+
+`flush` is deliberately not exposed — wiping a whole store is not something an
+agent should be able to do in one call.
+
 ### Apps
 A Puter **app** is a registered application in your account: it shows up in your
 Puter app list, can be launched in the Puter desktop UI, and (once approved) be

src/mcp-connector/mcpb/manifest.json

@@ -12,7 +12,7 @@
   "homepage": "https://puter.com",
   "documentation": "https://github.com/HeyPuter/puter/tree/main/src/mcp-connector",
   "license": "AGPL-3.0-only",
-  "keywords": ["puter", "filesystem", "hosting", "subdomains", "workers", "serverless", "puter.js", "fs"],
+  "keywords": ["puter", "filesystem", "hosting", "subdomains", "workers", "serverless", "puter.js", "fs", "kv", "key-value"],
   "server": {
     "type": "node",
     "entry_point": "server/index.cjs",
@@ -28,12 +28,15 @@
   "tools_generated": false,
   "tools": [
     { "name": "whoami", "description": "Get the authenticated user's info (username, uuid, home directory). Use it to build valid paths." },
-    { "name": "fs_read_file", "description": "Read a file (UTF-8 or base64; optional offset/length)." },
+    { "name": "fs_read_file", "description": "Read a file (UTF-8 or base64; optional byte offset/length window)." },
     { "name": "fs_stat", "description": "Stat a file or directory (size, type, timestamps, uid)." },
     { "name": "fs_write_file", "description": "Create or overwrite a file (UTF-8 or base64 content)." },
     { "name": "fs_mkdir", "description": "Create a directory (optionally creating missing parents)." },
     { "name": "fs_delete", "description": "Delete a file or directory (recursive by default)." },
     { "name": "fs_readdir", "description": "List the entries of a directory." },
+    { "name": "fs_copy", "description": "Copy a file or directory to another location." },
+    { "name": "fs_move", "description": "Move a file or directory to another location (also renames)." },
+    { "name": "fs_rename", "description": "Rename a file or directory in place." },
     { "name": "hosting_list", "description": "List the caller's published websites (hosting subdomains, served at <subdomain>.puter.site)." },
     { "name": "hosting_get", "description": "Get a published website by its subdomain." },
     { "name": "hosting_create", "description": "Publish a static website on a subdomain (optionally pointing at a root_dir)." },
@@ -44,6 +47,17 @@
     { "name": "workers_get", "description": "Get a deployed worker (name, URL, source file) by name." },
     { "name": "workers_exec", "description": "Call a deployed worker over HTTP as the authenticated user." },
     { "name": "workers_delete", "description": "Undeploy a worker (leaves its source file in place)." },
+    { "name": "kv_get", "description": "Read a key from the key-value store (missing keys read as null)." },
+    { "name": "kv_set", "description": "Create or overwrite a key, optionally with an expiry timestamp." },
+    { "name": "kv_del", "description": "Delete a key from the key-value store." },
+    { "name": "kv_list", "description": "List keys (or key/value pairs) by pattern, with pagination." },
+    { "name": "kv_incr", "description": "Increment a number, or numbers at given dot paths." },
+    { "name": "kv_decr", "description": "Decrement a number, or numbers at given dot paths." },
+    { "name": "kv_add", "description": "Add to a stored value (sums numbers, appends to arrays)." },
+    { "name": "kv_update", "description": "Set specific dot paths inside a stored object." },
+    { "name": "kv_remove", "description": "Remove dot paths from a stored object." },
+    { "name": "kv_expire", "description": "Expire a key after a number of seconds." },
+    { "name": "kv_expire_at", "description": "Expire a key at a Unix timestamp." },
     { "name": "apps_list", "description": "List the Puter apps the caller owns / can edit (name, URL, icon, aggregate usage stats)." },
     { "name": "apps_get", "description": "Get a Puter app by name; pass stats_period for detailed open/user counts over a window." },
     { "name": "apps_create", "description": "Register a new Puter app (requires name and index_url, the URL the app loads)." },