Gemini Tool

Relevant source files

The following files were used as context for generating this wiki page:

• src/geminiAgent.ts
• README.md
• src/server.ts
• src/types.ts
• src/runner.ts
• src/agentLoader.ts

The Gemini Tool is a specialized component of the SuperAgent MCP server designed to interface with the Gemini CLI agent. It enables the execution of one or many generative AI tasks in parallel, specifically leveraging "YOLO mode" for automatic approval of all actions taken by the underlying CLI. Within the broader SuperAgent architecture, the Gemini Tool acts as a bridge between Model Context Protocol (MCP) clients and the Google Gemini-powered command-line interface.

Sources: README.md:3-10, src/server.ts:65-68, src/geminiAgent.ts:55-58

Architecture and Execution Flow

The Gemini Tool operates by spawning the gemini CLI as a child process. It handles input preparation, process management, and output parsing to return structured JSON responses to the MCP client.

Invocation Logic

The execution starts in server.ts where a CallToolRequest for "gemini" is received. The request is validated against the GeminiInvokeSchema and passed to the batch runner.

Process Management

The invokeGemini function manages the lifecycle of the child process, including setting timeouts and registering the process for cleanup during server shutdown.

• Timeout: Defaults to 30 minutes (1,800,000 ms).
• Environment: Inherits the current process.env.
• Concurrency: Supports 1 to 10 parallel tasks (default: 1).

Sources: src/geminiAgent.ts:37, src/geminiAgent.ts:133-150, src/types.ts:22-29

Configuration and Tool Definition

The tool is defined within the MCP server with a specific input schema that allows users to specify prompts, working directories, and specialized agent personas.

Input Schema (GeminiInvokeSchema)

Parameter	Type	Description
inputs[]	Array	A list of AgentPromptSchema objects to execute.
concurrency	Number	Number of tasks to run in parallel (1-10).
prompt	String	The actual instruction for the agent.
agent	String	(Optional) Name of a specialized agent (e.g., backend-architect).
workingDirectory	String	(Optional) Path to the directory where the agent should operate.
timeoutMs	Number	(Optional) Custom timeout in milliseconds.

Sources: src/types.ts:7-29, src/server.ts:65-68

Meta-Instruction and Prompting

The tool automatically wraps user requests in a META_INSTRUCTION that enforces conciseness and focus. It also supports specialized system prompts loaded from the ~/.superagent/agents directory.

const META_INSTRUCTION = `You are an MCP-invoked agent. Your responses should be:
- Concise but complete
- Focus on the requested task
- Do what has been asked, nothing more, nothing less...`;

Sources: src/geminiAgent.ts:39-49, src/runner.ts:113-118

Data Processing

The Gemini Tool performs sophisticated parsing of the CLI's output to extract the assistant's reply and performance statistics.

Output Parsing Logic

The parseGeminiResponse function attempts multiple strategies to extract data from stdout:

1. Full JSON: Tries to parse the entire output as a single JSON object.
2. JSON Search: Searches for the first { and last } to find a JSON block within noise.
3. Fallback: Returns the trimmed stdout as a plain string if no JSON is found.

Result Structure

Successful executions return an AgentInvocationSuccess object, while failures return an AgentInvocationErrorResult.

Field	Type	Description
status	"ok"	"error"
response	String	The parsed text from the Gemini agent.
durationMs	Number	Time taken for execution.
exitCode	Number	CLI process exit code.
error	String	Error message (if status is "error").

Sources: src/types.ts:49-74

Agent Integration

The Gemini Tool can be customized by passing an agent parameter. This parameter corresponds to Markdown files stored in the agent library.

• System Prompt Loading: If an agent is specified, runner.ts calls getAgent() to retrieve the system prompt from the local agent library.
• Library Location: Agents are stored in ~/.superagent/agents.
• Discovery: The list-agents tool can be used to query available personas before invoking the Gemini tool.

Sources: src/runner.ts:111-120, src/agentLoader.ts:13, src/server.ts:50-54

Summary

The Gemini Tool provides a robust, parallelized interface for the Gemini CLI agent within an MCP environment. It automates command approval via YOLO mode, ensures consistent agent behavior through standardized meta-instructions, and provides reliable data extraction from CLI outputs, making it suitable for complex multi-step research and code modification tasks.