@adrive/mcp-server 0.3.0 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @adrive/mcp-server
 
-MCP server for **AgentDrive** — the persistent workspace your agents share across Claude Code, Codex, Cursor, and LangGraph. Files, semantic search, run logging, and cross-platform memory.
+MCP server for **AgentDrive** — the cross-agent artifact workspace with provenance and portable storage across Claude Code, Codex, Cursor, and LangGraph. Files, semantic recall, run logging, and cross-platform attribution.
 
 Drop this server into any MCP-compatible client and your agents get a shared filesystem with provenance, semantic search across artifacts written by other agents, and per-run audit. Memory is a feature of the workspace, not the headline.
 
@@ -66,7 +66,7 @@ env = { AGENTDRIVE_API_KEY = "agentdrive_live_...", AGENTDRIVE_AGENT_PLATFORM =
 }
 ```
 
-## Tools (16)
+## Tools (20)
 
 **Files**
 - `drive_write` — create or update a file with versioning

package/dist/api-client.d.ts

@@ -38,7 +38,6 @@ export interface ContextRequestBody {
     task: string;
     workspace_id?: string;
     limit?: number;
-    include_facts?: boolean;
 }
 export interface ContextArtifact extends SearchHit {
 }
@@ -233,5 +232,44 @@ export declare class ApiClient {
         run_id: string;
         created_at: number;
     }>;
+    sandboxClone(workspaceId: string, body: {
+        url: string;
+        branch?: string;
+        depth?: number;
+    }): Promise<{
+        workspace_id: string;
+        repo_url?: string;
+        branch?: string;
+        head_sha?: string;
+        last_active_at?: number;
+    }>;
+    sandboxExec(workspaceId: string, body: {
+        cmd: string;
+        cwd?: string;
+        timeout_ms?: number;
+    }): Promise<{
+        exit_code: number;
+        stdout: string;
+        stderr: string;
+        duration_ms: number;
+        truncated: boolean;
+    }>;
+    sandboxRead(workspaceId: string, path: string): Promise<{
+        content: string;
+        size: number;
+        truncated: boolean;
+    }>;
+    sandboxCommit(workspaceId: string, body: {
+        message: string;
+        author?: {
+            name: string;
+            email: string;
+        };
+    }): Promise<{
+        commit_sha: string;
+        branch: string;
+        files_changed: number;
+        artifact_path: string;
+    }>;
 }
 export {};

package/dist/api-client.js

@@ -195,4 +195,18 @@ export class ApiClient {
     async logRun(body) {
         return this.request('POST', '/runs', body);
     }
+    // --- Sandbox (Wave 5 Stream D) ---
+    async sandboxClone(workspaceId, body) {
+        return this.request('POST', `/workspaces/${workspaceId}/sandbox/clone`, body);
+    }
+    async sandboxExec(workspaceId, body) {
+        return this.request('POST', `/workspaces/${workspaceId}/sandbox/exec`, body);
+    }
+    async sandboxRead(workspaceId, path) {
+        const cleaned = path.startsWith('/') ? path : `/${path}`;
+        return this.request('GET', `/workspaces/${workspaceId}/sandbox/files${cleaned}`);
+    }
+    async sandboxCommit(workspaceId, body) {
+        return this.request('POST', `/workspaces/${workspaceId}/sandbox/commit`, body);
+    }
 }

package/dist/index.js

@@ -18,10 +18,40 @@ import { driveSearchSchema, driveSearch } from './tools/drive-search.js';
 import { driveRecallSchema, driveRecall } from './tools/drive-recall.js';
 import { driveLogRunSchema, driveLogRun } from './tools/drive-log-run.js';
 import { driveContextSchema, driveContext } from './tools/drive-context.js';
+import { driveSandboxCloneSchema, driveSandboxClone } from './tools/drive-sandbox-clone.js';
+import { driveSandboxExecSchema, driveSandboxExec } from './tools/drive-sandbox-exec.js';
+import { driveSandboxReadSchema, driveSandboxRead } from './tools/drive-sandbox-read.js';
+import { driveSandboxCommitSchema, driveSandboxCommit } from './tools/drive-sandbox-commit.js';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
 const BASE_URL = process.env.AGENTDRIVE_API_URL || 'https://app.agentdrive.sh';
 const API_KEY = process.env.AGENTDRIVE_API_KEY;
 const AGENT_PLATFORM = process.env.AGENTDRIVE_AGENT_PLATFORM || 'claude-code';
 const AGENT_ROLE = process.env.AGENTDRIVE_AGENT_ROLE || '';
+// Cross-host preamble shipped via MCP `instructions` so every MCP-aware
+// client (Claude Code, Codex, Cursor, Zed, Cline, Continue, OpenClaw) gets
+// the same usage guidance at session start without needing a per-host
+// markdown file. Hosts that ALSO read a markdown rules file
+// (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.cursor/rules/agentdrive.mdc)
+// continue to get the more verbose adrive init preamble via auto-context.ts.
+const SERVER_INSTRUCTIONS = `AgentDrive — cross-agent artifact workspace with provenance for multi-agent workflows.
+
+Reach for these tools without waiting to be asked:
+
+- **Session start:** call \`drive_context\` with a short summary of the
+  current task. Returns the most relevant artifacts and last_run
+  summaries from prior agents' work in the same workspace, each with
+  an \`attribution\` block explaining *why* it was surfaced.
+- **Cross-agent recall:** call \`drive_search\` (semantic) when the
+  user asks "what did Codex / Cursor / the last session do?"
+- **Saving work:** call \`drive_write\` for any artifact worth keeping
+  so the next agent in the chain can read it back.
+- **Provenance:** call \`drive_log_run\` at the end of meaningful
+  work so the cross-agent timeline stays accurate.
+
+Privacy: if the user has Private Workspace on, written content is
+encrypted client-side; the AgentDrive server only stores ciphertext.`;
 if (!API_KEY) {
     console.error('AGENTDRIVE_API_KEY environment variable is required');
     process.exit(1);
@@ -34,8 +64,10 @@ const client = new ApiClient({
 });
 const server = new McpServer({
     name: 'agentdrive',
-    version: '0.3.0',
-    description: 'AgentDrive — the persistent workspace your agents share across Claude Code, Codex, Cursor, and LangGraph. Files, semantic search, run logging, and cross-platform memory.',
+    version: pkg.version,
+    description: 'AgentDrive — the persistent workspace your agents share across Claude Code, Codex, Cursor, and LangGraph. Files, semantic search, run logging, cross-platform memory, and per-workspace Linux sandbox with git worktree.',
+}, {
+    instructions: SERVER_INSTRUCTIONS,
 });
 server.tool('drive_write', 'Write a markdown file to a workspace. Creates or updates the file with automatic versioning.', driveWriteSchema, (args) => driveWrite(client, args));
 server.tool('drive_read', 'Read a file\'s content from a workspace.', driveReadSchema, (args) => driveRead(client, args));
@@ -53,6 +85,16 @@ server.tool('drive_search', "Semantic search across your org's artifacts in Agen
 server.tool('drive_recall', 'Recall persistent facts and preferences your agents have written. In v1 this returns semantic search results across artifacts; v1.5 will narrow to auto-extracted facts (preferences, decisions, key entities).', driveRecallSchema, (args) => driveRecall(client, args));
 server.tool('drive_log_run', "Log an agent run to AgentDrive's provenance store. Captures task, status, referenced/produced artifacts, and cross-platform identity (which agent on which tool). Used for retrospective context retrieval and team-wide audit.", driveLogRunSchema, (args) => driveLogRun(client, args));
 server.tool('drive_context', 'Auto-pull the most relevant artifacts from prior agent sessions for the task you are about to do. Combines semantic relevance with recency. Call this at the START of any non-trivial task to ground the agent in prior context — replaces manual copy-paste of artifacts between sessions.', driveContextSchema, (args) => driveContext(client, args));
+// The four drive_sandbox_* tools are EXPERIMENTAL. They require the
+// Cloudflare Containers plan on the AgentDrive worker; without that
+// binding the API returns 503 and these tools surface a clean
+// "not configured" message. Marked experimental in the description
+// so MCP-aware hosts that surface tool metadata can communicate the
+// status; not part of the v1 cross-agent value prop.
+server.tool('drive_sandbox_clone', '[EXPERIMENTAL] Clone a git repo into a per-workspace Linux sandbox. Requires Cloudflare Containers on the AgentDrive worker; gracefully degrades to a 503 with "sandbox not configured" otherwise.', driveSandboxCloneSchema, (args) => driveSandboxClone(client, args));
+server.tool('drive_sandbox_exec', '[EXPERIMENTAL] Run a shell command inside the per-workspace Linux sandbox. Captures stdout/stderr (64 KB cap), exit code, duration. Requires Cloudflare Containers; degrades to 503 otherwise.', driveSandboxExecSchema, (args) => driveSandboxExec(client, args));
+server.tool('drive_sandbox_read', '[EXPERIMENTAL] Read a file from the per-workspace sandbox filesystem (build artifacts, test output, logs). Requires Cloudflare Containers; degrades to 503 otherwise.', driveSandboxReadSchema, (args) => driveSandboxRead(client, args));
+server.tool('drive_sandbox_commit', '[EXPERIMENTAL] Stage + commit the current sandbox worktree. Surfaces as an AgentDrive artifact at commits/<sha>.json. Requires Cloudflare Containers; degrades to 503 otherwise.', driveSandboxCommitSchema, (args) => driveSandboxCommit(client, args));
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/tools/drive-context.d.ts

@@ -4,13 +4,11 @@ export declare const driveContextSchema: {
     task: z.ZodString;
     workspace_id: z.ZodOptional<z.ZodString>;
     limit: z.ZodOptional<z.ZodNumber>;
-    include_facts: z.ZodOptional<z.ZodBoolean>;
 };
 export declare function driveContext(client: ApiClient, args: {
     task: string;
     workspace_id?: string;
     limit?: number;
-    include_facts?: boolean;
 }): Promise<{
     content: {
         type: "text";

package/dist/tools/drive-context.js

@@ -3,14 +3,12 @@ export const driveContextSchema = {
     task: z.string().min(1).max(2000).describe('What you are about to do — used to rank prior artifacts by relevance'),
     workspace_id: z.string().optional().describe('Scope to a single workspace; omit for org-wide context'),
     limit: z.number().int().positive().max(20).optional().describe('Max artifacts to return (default 5, max 20)'),
-    include_facts: z.boolean().optional().describe('Include extracted facts alongside artifacts (v1.5+)'),
 };
 export async function driveContext(client, args) {
     const { artifacts } = await client.context({
         task: args.task,
         workspace_id: args.workspace_id,
         limit: args.limit ?? 5,
-        include_facts: args.include_facts ?? false,
     });
     if (artifacts.length === 0) {
         return { content: [{ type: 'text', text: 'No prior context found.' }] };

package/dist/tools/drive-sandbox-clone.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { ApiClient } from '../api-client.js';
+export declare const driveSandboxCloneSchema: {
+    workspace_id: z.ZodString;
+    url: z.ZodString;
+    branch: z.ZodOptional<z.ZodString>;
+    depth: z.ZodOptional<z.ZodNumber>;
+};
+export declare function driveSandboxClone(client: ApiClient, args: {
+    workspace_id: string;
+    url: string;
+    branch?: string;
+    depth?: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/drive-sandbox-clone.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export const driveSandboxCloneSchema = {
+    workspace_id: z.string().describe('Workspace to clone into. The sandbox persists across MCP sessions per workspace.'),
+    url: z.string().url().describe('Git repository URL to clone'),
+    branch: z.string().optional().describe('Branch to check out (default: repo default)'),
+    depth: z.number().int().positive().max(50).optional().describe('Shallow clone depth (default: full clone)'),
+};
+export async function driveSandboxClone(client, args) {
+    const state = await client.sandboxClone(args.workspace_id, {
+        url: args.url,
+        branch: args.branch,
+        depth: args.depth,
+    });
+    return {
+        content: [{
+                type: 'text',
+                text: `Cloned ${state.repo_url}${state.branch ? '@' + state.branch : ''} into workspace ${state.workspace_id}.`,
+            }],
+    };
+}

package/dist/tools/drive-sandbox-commit.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { ApiClient } from '../api-client.js';
+export declare const driveSandboxCommitSchema: {
+    workspace_id: z.ZodString;
+    message: z.ZodString;
+    author_name: z.ZodOptional<z.ZodString>;
+    author_email: z.ZodOptional<z.ZodString>;
+};
+export declare function driveSandboxCommit(client: ApiClient, args: {
+    workspace_id: string;
+    message: string;
+    author_name?: string;
+    author_email?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/drive-sandbox-commit.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export const driveSandboxCommitSchema = {
+    workspace_id: z.string().describe('Workspace whose sandbox to commit'),
+    message: z.string().min(1).max(500).describe('Commit message'),
+    author_name: z.string().optional().describe('Override git author name (default: agent identity)'),
+    author_email: z.string().email().optional().describe('Override git author email (default: agent identity)'),
+};
+export async function driveSandboxCommit(client, args) {
+    const author = args.author_name && args.author_email
+        ? { name: args.author_name, email: args.author_email }
+        : undefined;
+    const result = await client.sandboxCommit(args.workspace_id, {
+        message: args.message,
+        author,
+    });
+    return {
+        content: [{
+                type: 'text',
+                text: `Committed ${result.commit_sha.slice(0, 8)} on ${result.branch} ` +
+                    `(${result.files_changed} file${result.files_changed === 1 ? '' : 's'} changed). ` +
+                    `Surfaced as AgentDrive artifact at ${result.artifact_path}.`,
+            }],
+    };
+}

package/dist/tools/drive-sandbox-exec.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { ApiClient } from '../api-client.js';
+export declare const driveSandboxExecSchema: {
+    workspace_id: z.ZodString;
+    cmd: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+};
+export declare function driveSandboxExec(client: ApiClient, args: {
+    workspace_id: string;
+    cmd: string;
+    cwd?: string;
+    timeout_ms?: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/drive-sandbox-exec.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export const driveSandboxExecSchema = {
+    workspace_id: z.string().describe('Workspace whose sandbox to run in'),
+    cmd: z.string().min(1).max(2048).describe('Shell command to run inside the per-workspace Linux sandbox'),
+    cwd: z.string().optional().describe('Working directory (default: workspace root)'),
+    timeout_ms: z.number().int().positive().max(60_000).optional().describe('Max runtime in ms (default 30000, hard cap 60000)'),
+};
+export async function driveSandboxExec(client, args) {
+    const result = await client.sandboxExec(args.workspace_id, {
+        cmd: args.cmd,
+        cwd: args.cwd,
+        timeout_ms: args.timeout_ms,
+    });
+    const header = `exit=${result.exit_code} duration=${result.duration_ms}ms${result.truncated ? ' [output truncated to 64KB]' : ''}`;
+    const stdoutBlock = result.stdout ? `\n--- stdout ---\n${result.stdout}` : '';
+    const stderrBlock = result.stderr ? `\n--- stderr ---\n${result.stderr}` : '';
+    return {
+        content: [{
+                type: 'text',
+                text: `${header}${stdoutBlock}${stderrBlock}`,
+            }],
+    };
+}

package/dist/tools/drive-sandbox-read.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import type { ApiClient } from '../api-client.js';
+export declare const driveSandboxReadSchema: {
+    workspace_id: z.ZodString;
+    path: z.ZodString;
+};
+export declare function driveSandboxRead(client: ApiClient, args: {
+    workspace_id: string;
+    path: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/drive-sandbox-read.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export const driveSandboxReadSchema = {
+    workspace_id: z.string().describe('Workspace whose sandbox to read from'),
+    path: z.string().describe('Path inside the sandbox (e.g., src/index.ts or /tmp/build.log)'),
+};
+export async function driveSandboxRead(client, args) {
+    const file = await client.sandboxRead(args.workspace_id, args.path);
+    const note = file.truncated ? `\n\n[content truncated; total ${file.size} bytes]` : '';
+    return {
+        content: [{
+                type: 'text',
+                text: `${args.path} (${file.size} bytes)\n\n${file.content}${note}`,
+            }],
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adrive/mcp-server",
-  "version": "0.3.0",
-  "description": "MCP server for AgentDrive — the persistent workspace your agents share across Claude Code, Codex, Cursor, and LangGraph. Files, semantic search, run logging, and cross-platform memory.",
+  "version": "1.0.0",
+  "description": "MCP server for AgentDrive — cross-agent artifact workspace with provenance and portable storage across Claude Code, Codex, Cursor, and LangGraph.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {