@kosuke-ai/cli 1.0.1-next.5 → 1.0.1-next.6

package/README.md

@@ -62,3 +62,107 @@ into `src/generated/`: request types (openapi-typescript) and one descriptor per
 operation, which the hand-written runtime turns into commands. `npm run check`
 regenerates and fails on any difference, so the tree is only ever what the
 document says.
+
+## MCP server
+
+The same package serves the platform to an MCP client: `kosuke mcp serve` runs on
+your machine as a child process of Claude, Cursor or Codex, speaks MCP over
+stdio, and talks to app.kosuke.ai with the token above. There is nothing to
+deploy. One block in the client's config is the whole install:
+
+```json
+{
+  "mcpServers": {
+    "kosuke": {
+      "command": "npx",
+      "args": ["-y", "@kosuke-ai/cli", "mcp", "serve"],
+      "env": { "KOSUKE_API_KEY": "kosuke_..." }
+    }
+  }
+}
+```
+
+`KOSUKE_API_URL` in the same `env` points it at another deployment. `kosuke mcp
+tools` prints the tool list as JSON without starting a server.
+
+Attachments are read from disk, and the model picks the path, so the server
+only reads under one directory: the working directory it was started in, or
+`KOSUKE_MCP_ATTACHMENT_ROOT` / `--attachment-root`. Set it to the project you
+are working on. A path outside the root, a symlink that leads out of it, and
+any hidden path under it (`.ssh`, `.aws`, `.config`, `.env`) are refused
+before anything is read.
+
+### Tools
+
+Every operation of the API is a tool, generated from the same descriptors as
+the commands: `kosuke sessions send` is the tool `sessions_send`, path params
+and request fields are its arguments, and the API's own description is the
+tool's. A body that is not a flat object (`projects_env_vars_add`,
+`workspaces_ai_provider_set`) is one `body` argument with the real schema. The
+four operations that take files accept `attachments: [{ "path": "..." }]`, paths
+on the machine the server runs on, like `--attach`, confined to the attachment
+root above.
+
+On top, three hand-written tools for the arcs that otherwise make an agent
+plumb ids by hand. They only ever call the generated tools:
+
+| Tool     | What it does                                                                                                        |
+| -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `ship`   | Create a chat session from a prompt and start its first turn, or start a backlog session. Returns the job to watch. |
+| `watch`  | Poll a chat job, or the deploy, until it settles, with progress on the way. Returns the last assistant message.     |
+| `submit` | Send the `open-pr` skill to a session so it opens, or updates, its pull request. Returns the job to watch.          |
+
+### Toolsets
+
+Seventy-odd tools on every turn is more than a model chooses between well, so
+they are grouped by the spec's own tags. All are on by default; load a subset
+with `--toolsets` (or `KOSUKE_MCP_TOOLSETS`) in the `args`/`env` above.
+`kosuke mcp tools` prints the current list; the counts here are as of this
+version of the document:
+
+| Toolset      | Tools | Covers                                                                                         |
+| ------------ | ----: | ---------------------------------------------------------------------------------------------- |
+| `sessions`   |    29 | Chat sessions: create, send, jobs, messages, files, diff, comments, git, checklist, artifacts. |
+| `projects`   |    15 | Projects and their settings: services, environment variables, import, skills.                  |
+| `workspaces` |    13 | Workspaces: members, usage, credits, AI provider, sandboxes.                                   |
+| `preview`    |     8 | Preview URLs, health, reset, share links and shared artifacts.                                 |
+| `deploy`     |     3 | Run, cancel and read the agentic deploy.                                                       |
+| `composite`  |     3 | `ship`, `watch`, `submit`.                                                                     |
+
+```json
+"args": ["-y", "@kosuke-ai/cli", "mcp", "serve", "--toolsets", "sessions,composite"]
+```
+
+`--read-only` keeps only the tools that read: the GET operations and `watch`,
+minus the three reads that wake a paused sandbox and so start billing
+(`preview_get`, `preview_shared`, `sessions_files_get`). The same rule sets
+each tool's `readOnlyHint`, the signal a client uses to run a call without
+asking.
+
+### Safeguards
+
+Tool arguments and results end up in the agent's transcript, so the server
+enforces these rather than asking:
+
+- A provider key (`anthropicApiKey`, `bedrockApiKey`, `openaiApiKey`) or an
+  environment variable marked `isSecret` in an argument is refused before any
+  request is made, so the server never knowingly forwards a declared secret.
+  It cannot stop a value the caller does not declare: whatever a model puts
+  in an argument is in the transcript already. Set secrets in Settings or with
+  the CLI.
+- Free text is never refused, but an argument that looks like it quotes a
+  credential comes back with a `warnings` entry on the result.
+- Attachments come only from the attachment root, never from a hidden path.
+- Environment values marked secret (`envVars[].value` where `isSecret`) and the
+  `sentryDsn` field of a project are redacted from every result. Prose that
+  quotes such a value, in a chat message for instance, is returned as the
+  platform sent it.
+- A preview share link is a credential. Only `preview_share_get` and
+  `preview_share_create` return one, and their descriptions say so.
+- Admin, webhook, billing, browser-auth, key-management and preview auth-token
+  routes are not in the document, so no tool, composite or generated, can reach
+  them.
+
+A remote HTTP transport (a one-click connector rather than a local process) is
+a separate piece of work; this server is shaped so it can be added without
+changing the tools.

package/dist/commands/mcp.js

@@ -0,0 +1,85 @@
+import { resolve } from 'node:path';
+import { UsageError } from '../runtime/invoke.js';
+import { defaultAttachmentPolicy } from '../runtime/mcp-attachments.js';
+import { ALL_TOOLSETS, availableToolsets, selectTools, serveStdio, toolListing, } from '../runtime/mcp-server.js';
+export function attachMcpCommands(root, runtime, deps = {}) {
+    const { env = process.env, fetch, stdout = (line) => process.stdout.write(line + '\n'), stderr = (line) => process.stderr.write(line + '\n'), exit = (code) => {
+        process.exitCode = code;
+    }, serve = serveStdio, } = deps;
+    const mcp = root
+        .command('mcp')
+        .description('Serve the platform to an MCP client such as Claude, Cursor or Codex.');
+    const toolsetHelp = `Comma-separated toolsets to expose: ${[ALL_TOOLSETS, ...availableToolsets()].join(', ')}. ` +
+        `Default all, or KOSUKE_MCP_TOOLSETS.`;
+    const selection = (flags) => ({
+        toolsets: parseToolsets(flags.toolsets ?? env.KOSUKE_MCP_TOOLSETS),
+        readOnly: flags.readOnly === true,
+    });
+    const attachmentRootHelp = 'Directory attachments may come from; nothing outside it is read. ' +
+        'Default: the working directory, or KOSUKE_MCP_ATTACHMENT_ROOT.';
+    mcp
+        .command('serve')
+        .description('Start the MCP server on stdio. Uses the same auth token as every other command.')
+        .option('--toolsets <names>', toolsetHelp)
+        .option('--read-only', 'Expose only the tools that read.')
+        .option('--attachment-root <path>', attachmentRootHelp)
+        .action(async (flags) => {
+        const { apiKey, apiUrl } = runtime.credentials();
+        if (!apiKey) {
+            stderr('No auth token. Set KOSUKE_API_KEY in the MCP client config, pass --api-key, or run ' +
+                '`kosuke auth login`. Create one in Settings on the platform.');
+            exit(1);
+            return;
+        }
+        try {
+            await serve({
+                apiUrl,
+                apiKey,
+                ...selection(flags),
+                attachments: flags.attachmentRoot
+                    ? { root: resolve(flags.attachmentRoot) }
+                    : defaultAttachmentPolicy(env),
+                ...(fetch ? { fetch } : {}),
+                log: stderr,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof UsageError))
+                throw error;
+            stderr(error.message);
+            exit(1);
+        }
+    });
+    mcp
+        .command('tools')
+        .description('Print the tools the server would expose, as JSON, without starting it.')
+        .option('--toolsets <names>', toolsetHelp)
+        .option('--read-only', 'Only the tools that read.')
+        .action((flags) => {
+        try {
+            stdout(JSON.stringify(selectTools(selection(flags)).map(toolListing), null, 2));
+        }
+        catch (error) {
+            if (!(error instanceof UsageError))
+                throw error;
+            stderr(error.message);
+            exit(1);
+        }
+    });
+}
+/**
+ * Absent means every toolset; given but naming none is refused, since a typo
+ * in KOSUKE_MCP_TOOLSETS must not quietly serve everything.
+ */
+function parseToolsets(value) {
+    if (value === undefined)
+        return [];
+    const names = value
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+    if (!names.length) {
+        throw new UsageError(`--toolsets (or KOSUKE_MCP_TOOLSETS) names no toolset; use all, or a comma-separated list.`);
+    }
+    return names;
+}

package/dist/generated/tools/deploy/cancel.js

@@ -0,0 +1,20 @@
+import { operation } from '../../commands/deploy/cancel.js';
+export const tool = {
+    "name": "deploy_cancel",
+    "toolset": "deploy",
+    "description": "Stop the running deploy. Steers queued behind it are discarded and listed.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            }
+        },
+        "required": [
+            "projectId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/deploy/messages.js

@@ -0,0 +1,20 @@
+import { operation } from '../../commands/deploy/messages.js';
+export const tool = {
+    "name": "deploy_messages",
+    "toolset": "deploy",
+    "description": "Read the deploy conversation and the current deploy status.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            }
+        },
+        "required": [
+            "projectId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/deploy/run.js

@@ -0,0 +1,52 @@
+import { operation } from '../../commands/deploy/run.js';
+export const tool = {
+    "name": "deploy_run",
+    "toolset": "deploy",
+    "description": "Start a deploy (empty JSON body), continue the current one with userResponse, or steer a running one with steerTargetDeployJobId. Attachments ride along as multipart, where the message is called content.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            },
+            "userResponse": {
+                "type": "string"
+            },
+            "steerTargetDeployJobId": {
+                "type": "string"
+            },
+            "freshDeploy": {
+                "type": "boolean"
+            },
+            "content": {
+                "type": "string",
+                "description": "The message for the deploy agent."
+            },
+            "attachments": {
+                "type": "array",
+                "maxItems": 10,
+                "description": "Files to attach, at most 10 of 10 MiB each. Each is a path on this machine; the request is sent as multipart when any are given.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "Path of a file to attach."
+                        }
+                    },
+                    "required": [
+                        "path"
+                    ],
+                    "additionalProperties": false
+                }
+            }
+        },
+        "required": [
+            "projectId",
+            "content"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/index.js

@@ -0,0 +1,138 @@
+import { tool as t0 } from './deploy/cancel.js';
+import { tool as t1 } from './deploy/messages.js';
+import { tool as t2 } from './deploy/run.js';
+import { tool as t3 } from './preview/get.js';
+import { tool as t4 } from './preview/health.js';
+import { tool as t5 } from './preview/reset.js';
+import { tool as t6 } from './preview/share-create.js';
+import { tool as t7 } from './preview/share-delete.js';
+import { tool as t8 } from './preview/share-get.js';
+import { tool as t9 } from './preview/shared.js';
+import { tool as t10 } from './preview/shared-artifact.js';
+import { tool as t11 } from './projects/create.js';
+import { tool as t12 } from './projects/delete.js';
+import { tool as t13 } from './projects/env-vars-add.js';
+import { tool as t14 } from './projects/env-vars-remove.js';
+import { tool as t15 } from './projects/get.js';
+import { tool as t16 } from './projects/list.js';
+import { tool as t17 } from './projects/services-add.js';
+import { tool as t18 } from './projects/services-list.js';
+import { tool as t19 } from './projects/services-remove.js';
+import { tool as t20 } from './projects/services-update.js';
+import { tool as t21 } from './projects/settings-get.js';
+import { tool as t22 } from './projects/settings-import.js';
+import { tool as t23 } from './projects/settings-update.js';
+import { tool as t24 } from './projects/skills.js';
+import { tool as t25 } from './projects/update.js';
+import { tool as t26 } from './sessions/activate.js';
+import { tool as t27 } from './sessions/artifacts-get.js';
+import { tool as t28 } from './sessions/artifacts-list.js';
+import { tool as t29 } from './sessions/checklist-generate.js';
+import { tool as t30 } from './sessions/checklist-get.js';
+import { tool as t31 } from './sessions/comments-add.js';
+import { tool as t32 } from './sessions/comments-delete.js';
+import { tool as t33 } from './sessions/comments-list.js';
+import { tool as t34 } from './sessions/comments-update.js';
+import { tool as t35 } from './sessions/create.js';
+import { tool as t36 } from './sessions/delete.js';
+import { tool as t37 } from './sessions/diff-files.js';
+import { tool as t38 } from './sessions/diff-patch.js';
+import { tool as t39 } from './sessions/edit-prompt.js';
+import { tool as t40 } from './sessions/files-get.js';
+import { tool as t41 } from './sessions/files-list.js';
+import { tool as t42 } from './sessions/files-write.js';
+import { tool as t43 } from './sessions/get.js';
+import { tool as t44 } from './sessions/git-commit.js';
+import { tool as t45 } from './sessions/git-commit-message.js';
+import { tool as t46 } from './sessions/git-push.js';
+import { tool as t47 } from './sessions/git-state.js';
+import { tool as t48 } from './sessions/jobs-cancel.js';
+import { tool as t49 } from './sessions/jobs-get.js';
+import { tool as t50 } from './sessions/list.js';
+import { tool as t51 } from './sessions/messages.js';
+import { tool as t52 } from './sessions/search.js';
+import { tool as t53 } from './sessions/send.js';
+import { tool as t54 } from './sessions/update.js';
+import { tool as t55 } from './workspaces/access-status.js';
+import { tool as t56 } from './workspaces/ai-provider-get.js';
+import { tool as t57 } from './workspaces/ai-provider-remove.js';
+import { tool as t58 } from './workspaces/ai-provider-set.js';
+import { tool as t59 } from './workspaces/credits.js';
+import { tool as t60 } from './workspaces/get.js';
+import { tool as t61 } from './workspaces/getting-started-get.js';
+import { tool as t62 } from './workspaces/getting-started-update.js';
+import { tool as t63 } from './workspaces/list.js';
+import { tool as t64 } from './workspaces/members.js';
+import { tool as t65 } from './workspaces/sandbox-limit.js';
+import { tool as t66 } from './workspaces/stop-sandboxes.js';
+import { tool as t67 } from './workspaces/usage.js';
+export const tools = [
+    t0,
+    t1,
+    t2,
+    t3,
+    t4,
+    t5,
+    t6,
+    t7,
+    t8,
+    t9,
+    t10,
+    t11,
+    t12,
+    t13,
+    t14,
+    t15,
+    t16,
+    t17,
+    t18,
+    t19,
+    t20,
+    t21,
+    t22,
+    t23,
+    t24,
+    t25,
+    t26,
+    t27,
+    t28,
+    t29,
+    t30,
+    t31,
+    t32,
+    t33,
+    t34,
+    t35,
+    t36,
+    t37,
+    t38,
+    t39,
+    t40,
+    t41,
+    t42,
+    t43,
+    t44,
+    t45,
+    t46,
+    t47,
+    t48,
+    t49,
+    t50,
+    t51,
+    t52,
+    t53,
+    t54,
+    t55,
+    t56,
+    t57,
+    t58,
+    t59,
+    t60,
+    t61,
+    t62,
+    t63,
+    t64,
+    t65,
+    t66,
+    t67,
+];

package/dist/generated/tools/preview/get.js

@@ -0,0 +1,24 @@
+import { operation } from '../../commands/preview/get.js';
+export const tool = {
+    "name": "preview_get",
+    "toolset": "preview",
+    "description": "Read the preview URLs of the project's main sandbox, or of one chat session's.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            },
+            "sessionId": {
+                "type": "string",
+                "description": "A chat session's preview instead of the project's main one."
+            }
+        },
+        "required": [
+            "projectId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/preview/health.js

@@ -0,0 +1,24 @@
+import { operation } from '../../commands/preview/health.js';
+export const tool = {
+    "name": "preview_health",
+    "toolset": "preview",
+    "description": "Read the health of every service behind a preview.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            },
+            "sessionId": {
+                "type": "string",
+                "description": "A chat session's preview instead of the project's main one."
+            }
+        },
+        "required": [
+            "projectId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/preview/reset.js

@@ -0,0 +1,23 @@
+import { operation } from '../../commands/preview/reset.js';
+export const tool = {
+    "name": "preview_reset",
+    "toolset": "preview",
+    "description": "Queue a rebuild of a preview sandbox from scratch.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            },
+            "sessionId": {
+                "type": "string"
+            }
+        },
+        "required": [
+            "projectId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/preview/share-create.js

@@ -0,0 +1,24 @@
+import { operation } from '../../commands/preview/share-create.js';
+export const tool = {
+    "name": "preview_share_create",
+    "toolset": "preview",
+    "description": "Create the public share link of a preview. The body sessionId wins over the query one. Returns the share link itself, which is a credential: anyone holding it can open the preview.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            },
+            "sessionId": {
+                "type": "string",
+                "description": "A chat session's preview instead of the project's main one."
+            }
+        },
+        "required": [
+            "projectId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/preview/share-delete.js

@@ -0,0 +1,24 @@
+import { operation } from '../../commands/preview/share-delete.js';
+export const tool = {
+    "name": "preview_share_delete",
+    "toolset": "preview",
+    "description": "Revoke the public share link of a preview.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            },
+            "sessionId": {
+                "type": "string",
+                "description": "A chat session's preview instead of the project's main one."
+            }
+        },
+        "required": [
+            "projectId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/preview/share-get.js

@@ -0,0 +1,24 @@
+import { operation } from '../../commands/preview/share-get.js';
+export const tool = {
+    "name": "preview_share_get",
+    "toolset": "preview",
+    "description": "Read the public share link of a preview, if one exists. Returns the share link itself, which is a credential: anyone holding it can open the preview.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            },
+            "sessionId": {
+                "type": "string",
+                "description": "A chat session's preview instead of the project's main one."
+            }
+        },
+        "required": [
+            "projectId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/preview/shared-artifact.js

@@ -0,0 +1,25 @@
+import { operation } from '../../commands/preview/shared-artifact.js';
+export const tool = {
+    "name": "preview_shared_artifact",
+    "toolset": "preview",
+    "description": "Read one artifact behind a public share link. No credential needed.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "slug": {
+                "type": "string",
+                "description": "Slug."
+            },
+            "artifactId": {
+                "type": "string",
+                "description": "Artifact id."
+            }
+        },
+        "required": [
+            "slug",
+            "artifactId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/preview/shared.js

@@ -0,0 +1,20 @@
+import { operation } from '../../commands/preview/shared.js';
+export const tool = {
+    "name": "preview_shared",
+    "toolset": "preview",
+    "description": "Resolve a public share link. No credential needed; rate limited per caller.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "slug": {
+                "type": "string",
+                "description": "Slug."
+            }
+        },
+        "required": [
+            "slug"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/projects/create.js

@@ -0,0 +1,26 @@
+import { operation } from '../../commands/projects/create.js';
+export const tool = {
+    "name": "projects_create",
+    "toolset": "projects",
+    "description": "Connect a GitHub repository as a project in a workspace.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string"
+            },
+            "repositoryUrl": {
+                "type": "string"
+            },
+            "orgId": {
+                "type": "string"
+            }
+        },
+        "required": [
+            "name",
+            "repositoryUrl"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};

package/dist/generated/tools/projects/delete.js

@@ -0,0 +1,20 @@
+import { operation } from '../../commands/projects/delete.js';
+export const tool = {
+    "name": "projects_delete",
+    "toolset": "projects",
+    "description": "Delete a project and everything it owns. Workspace admins only.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "projectId": {
+                "type": "string",
+                "description": "Project id."
+            }
+        },
+        "required": [
+            "projectId"
+        ],
+        "additionalProperties": false
+    },
+    operation,
+};