docs: add mcp and skill session config (#106)

examples/mcp-custom-tool/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@sandbox-agent/example-mcp-custom-tool",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build:mcp": "esbuild src/mcp-server.ts --bundle --format=cjs --platform=node --target=node18 --minify --outfile=dist/mcp-server.cjs",
+    "start": "pnpm build:mcp && tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "@sandbox-agent/example-shared": "workspace:*",
+    "sandbox-agent": "workspace:*",
+    "zod": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "esbuild": "latest",
+    "tsx": "latest",
+    "typescript": "latest"
+  }
+}

examples/mcp-custom-tool/src/index.ts

@@ -0,0 +1,49 @@
+import { SandboxAgent } from "sandbox-agent";
+import { detectAgent, buildInspectorUrl, generateSessionId } from "@sandbox-agent/example-shared";
+import { startDockerSandbox } from "@sandbox-agent/example-shared/docker";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Verify the bundled MCP server exists (built by `pnpm build:mcp`).
+const serverFile = path.resolve(__dirname, "../dist/mcp-server.cjs");
+if (!fs.existsSync(serverFile)) {
+  console.error("Error: dist/mcp-server.cjs not found. Run `pnpm build:mcp` first.");
+  process.exit(1);
+}
+
+// Start a Docker container running sandbox-agent.
+console.log("Starting sandbox...");
+const { baseUrl, cleanup } = await startDockerSandbox({ port: 3004 });
+
+// Upload the bundled MCP server into the sandbox filesystem.
+console.log("Uploading MCP server bundle...");
+const client = await SandboxAgent.connect({ baseUrl });
+
+const bundle = await fs.promises.readFile(serverFile);
+const written = await client.writeFsFile(
+  { path: "/opt/mcp/custom-tools/mcp-server.cjs" },
+  bundle,
+);
+console.log(`  Written: ${written.path} (${written.bytesWritten} bytes)`);
+
+// Create a session with the uploaded MCP server as a local command.
+console.log("Creating session with custom MCP tool...");
+const sessionId = generateSessionId();
+await client.createSession(sessionId, {
+  agent: detectAgent(),
+  mcp: {
+    customTools: {
+      type: "local",
+      command: ["node", "/opt/mcp/custom-tools/mcp-server.cjs"],
+    },
+  },
+});
+console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
+console.log('  Try: "generate a random number between 1 and 100"');
+console.log("  Press Ctrl+C to stop.");
+
+const keepAlive = setInterval(() => {}, 60_000);
+process.on("SIGINT", () => { clearInterval(keepAlive); cleanup().then(() => process.exit(0)); });

examples/mcp-custom-tool/src/mcp-server.ts

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+async function main() {
+  const server = new McpServer({ name: "rand", version: "1.0.0" });
+
+  server.tool(
+    "random_number",
+    "Generate a random integer between min and max (inclusive)",
+    {
+      min: z.number().describe("Minimum value"),
+      max: z.number().describe("Maximum value"),
+    },
+    async ({ min, max }) => ({
+      content: [{ type: "text", text: String(Math.floor(Math.random() * (max - min + 1)) + min) }],
+    }),
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main();

examples/mcp-custom-tool/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}