Fixes #244: Add MCP Plan Generation Example

packages/core/README.md

@@ -7,6 +7,7 @@ Orchestrate complex, long-running coding tasks to an ephemeral cloud environment
 ## Examples
 
 - [Basic Session](./examples/basic-session/README.md)
+- [MCP Plan Generation](./examples/mcp-plan-generation/README.md)
 - [Advanced Session](./examples/advanced-session/README.md)
 - [Agent Workflow](./examples/agent/README.md)
 - [Webhook Integration](./examples/webhook/README.md)

packages/core/examples/mcp-plan-generation/README.md

@@ -0,0 +1,44 @@
+# Jules MCP Plan Generation Server
+
+This example demonstrates how to build a custom [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server using the Jules SDK. This server acts as a tool provider that coding agents can use to generate highly detailed implementation plans. The generated plans contain reference implementations, build/test commands, and verification checks which can then be used as a prompt to create a new Jules session.
+
+## Prerequisites
+
+- Bun installed globally (`npm install -g bun` or via `curl -fsSL https://bun.sh/install | bash`)
+- A Jules API Key (`export JULES_API_KEY=your-api-key`)
+
+## Setup
+
+Navigate to this directory and install dependencies:
+
+```bash
+cd packages/core/examples/mcp-plan-generation
+bun install
+```
+
+## Running the Server
+
+Start the MCP Server locally using standard input/output (stdio):
+
+```bash
+bun run start
+```
+
+*Note: The server uses stdio for communication, which is the standard transport mechanism for MCP servers interacting with an agent's runtime environment.*
+
+## Building
+
+To build the executable for node, run:
+
+```bash
+bun run build
+```
+
+## Usage
+
+Once running, the server exposes the `generate_plan` tool. Any MCP client (or agent using the MCP protocol) can call this tool with the following inputs:
+
+- `taskDescription`: The specific goal or bug fix requested by the user.
+- `sourceContext` (optional): Any contextual source code details (such as a GitHub repository name, file paths, or snippets).
+
+The server will internally create a repoless Jules session to generate a comprehensive markdown plan. This output plan can then be supplied directly into a subsequent Jules session as the execution prompt.

packages/core/examples/mcp-plan-generation/index.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { defineCommand, runMain } from 'citty';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { jules } from '@google/jules-sdk';
+
+async function runMcpServer() {
+  if (!process.env.JULES_API_KEY) {
+    console.error('Warning: JULES_API_KEY environment variable is missing.');
+  }
+
+  const server = new McpServer({
+    name: 'jules-mcp-plan-generation',
+    version: '1.0.0',
+  });
+
+  server.tool(
+    'generate_plan',
+    'Generates a highly detailed coding plan including reference implementations, build/test commands, and verification checks. This output can be used as a prompt to create a new Jules session.',
+    {
+      taskDescription: z.string().describe('The user\'s requested task or bug to solve.'),
+      sourceContext: z.string().optional().describe('Optional context about the source code, e.g., a GitHub repo name or file paths.'),
+    },
+    async ({ taskDescription, sourceContext }) => {
+      try {
+        const prompt = `You are an expert coding agent. Create a highly detailed plan to accomplish the following task:
+${taskDescription}
+
+${sourceContext ? `Source Context:\n${sourceContext}\n` : ''}
+The plan MUST include:
+1. Reference implementation details.
+2. Build commands to verify compilation.
+3. Test commands to verify correctness.
+4. Additional verification checks (e.g., linting, manual testing steps).
+
+Format the output cleanly in Markdown so it can be used directly as a prompt for another Jules session.`;
+
+        const session = await jules.session({
+          prompt,
+        });
+
+        const outcome = await session.result();
+        const files = outcome.generatedFiles();
+
+        // Find the main markdown output, or fallback to the last agent message
+        let planContent = 'Plan generation failed to produce an output.';
+
+        for (const [filename, file] of files) {
+          if (filename.endsWith('.md')) {
+            planContent = file.content;
+            break;
+          }
+        }
+
+        if (planContent === 'Plan generation failed to produce an output.' && outcome.lastAgentMessage) {
+           planContent = outcome.lastAgentMessage;
+        }
+
+        return {
+          content: [{ type: 'text', text: planContent }],
+        };
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Failed to generate plan: ${error.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Jules MCP Plan Generation Server is running on stdio');
+}
+
+const main = defineCommand({
+  meta: {
+    name: 'jules-mcp-plan-generation',
+    version: '1.0.0',
+    description: 'A Custom Jules MCP Server to generate highly detailed plans for coding agents.',
+  },
+  async run() {
+    await runMcpServer();
+  },
+});
+
+runMain(main).catch((error) => {
+  console.error('Fatal CLI Error:', error);
+  process.exit(1);
+});

packages/core/examples/mcp-plan-generation/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "mcp-plan-generation-example",
+  "version": "1.0.0",
+  "description": "Example demonstrating how to create an MCP server for generating highly detailed plans using the Jules SDK",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "mcp-plan-generation": "./index.ts"
+  },
+  "scripts": {
+    "start": "bun run index.ts",
+    "build": "bun build index.ts --target=node"
+  },
+  "dependencies": {
+    "@google/jules-sdk": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.2.0",
+    "citty": "^0.2.1",
+    "zod": "^3.23.0"
+  }
+}