From e7ec9b365a0b6b5227160b678c4e9b12a2a30509 Mon Sep 17 00:00:00 2001 From: davideast <4570265+davideast@users.noreply.github.com> Date: Tue, 10 Mar 2026 03:58:40 +0000 Subject: [PATCH] feat: add MCP plan generation example Adds a new example under `packages/core/examples/mcp-plan-generation` demonstrating how to build a custom MCP server using the Jules SDK that generates highly detailed coding plans. Includes `index.ts` MCP tool definition, `package.json`, `README.md`, and updates to the core `README.md`. Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> --- packages/core/README.md | 1 + .../core/examples/custom-mcp-server/index.ts | 0 .../examples/mcp-plan-generation/README.md | 44 +++++++++ .../examples/mcp-plan-generation/index.ts | 91 +++++++++++++++++++ .../examples/mcp-plan-generation/package.json | 20 ++++ 5 files changed, 156 insertions(+) mode change 100644 => 100755 packages/core/examples/custom-mcp-server/index.ts create mode 100644 packages/core/examples/mcp-plan-generation/README.md create mode 100755 packages/core/examples/mcp-plan-generation/index.ts create mode 100644 packages/core/examples/mcp-plan-generation/package.json diff --git a/packages/core/README.md b/packages/core/README.md index b8c5da7..5a3653f 100644 --- a/packages/core/README.md +++ b/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) diff --git a/packages/core/examples/custom-mcp-server/index.ts b/packages/core/examples/custom-mcp-server/index.ts old mode 100644 new mode 100755 diff --git a/packages/core/examples/mcp-plan-generation/README.md b/packages/core/examples/mcp-plan-generation/README.md new file mode 100644 index 0000000..de598b5 --- /dev/null +++ b/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. diff --git a/packages/core/examples/mcp-plan-generation/index.ts b/packages/core/examples/mcp-plan-generation/index.ts new file mode 100755 index 0000000..79ac2b5 --- /dev/null +++ b/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); +}); diff --git a/packages/core/examples/mcp-plan-generation/package.json b/packages/core/examples/mcp-plan-generation/package.json new file mode 100644 index 0000000..cd3ab36 --- /dev/null +++ b/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" + } +}