Gemini MCP Server

Instructions

Implementation Reference

• src/tools/chat.ts:31-62 (handler)

  The main handler function that implements the chat tool logic, including session creation/retrieval, message sending to AI, and response formatting.

  async ({ message, sessionId, model, systemInstruction }) => {
    try {
      let session = sessionId ? getSession(sessionId) : undefined;
      const id = session ? sessionId! : generateSessionId();
  
      if (!session) {
        const chat = ai.chats.create({
          model,
          config: systemInstruction ? { systemInstruction } : undefined,
        });
        session = { chat, turnCount: 0, lastActivity: Date.now() };
        storeSession(id, session);
      }
  
      const response = await session.chat.sendMessage({ message });
      session.turnCount++;
      session.lastActivity = Date.now();
  
      const result = {
        sessionId: id,
        response: response.text ?? '',
        turnCount: session.turnCount,
      };
  
      return {
        structuredContent: result,
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
      };
    } catch (error) {
      return formatToolError(error);
    }
  },

• src/tools/chat.ts:14-25 (schema)

  Input/output schema definitions for the chat tool, including validation for message, sessionId, model, and systemInstruction inputs, and sessionId, response, and turnCount outputs.

  inputSchema: {
    message: z.string().min(1).describe('The message to send'),
    sessionId: z.string().optional().describe('Session ID from a previous response to continue that conversation'),
    model: TextModel.default('gemini-2.5-flash').describe('Gemini model to use'),
    systemInstruction: z.string().optional().describe('System instruction (only applied when starting a new session)'),
  },
  outputSchema: {
    sessionId: z.string().describe('Session ID for continuing this conversation'),
    response: z.string().describe('The model response text'),
    turnCount: z.number().describe('Number of turns in this session'),
  },
  annotations: {

• src/tools/chat.ts:8-64 (registration)

  Tool registration function that registers the 'chat' tool with the MCP server, defining its metadata, schema, and handler.

  export function register(server: McpServer, ai: GoogleGenAI): void {
    server.registerTool(
      'chat',
      {
        title: 'Chat',
        description: 'Multi-turn conversation with session management. Omit sessionId to start a new session; include it to continue an existing one.',
        inputSchema: {
          message: z.string().min(1).describe('The message to send'),
          sessionId: z.string().optional().describe('Session ID from a previous response to continue that conversation'),
          model: TextModel.default('gemini-2.5-flash').describe('Gemini model to use'),
          systemInstruction: z.string().optional().describe('System instruction (only applied when starting a new session)'),
        },
        outputSchema: {
          sessionId: z.string().describe('Session ID for continuing this conversation'),
          response: z.string().describe('The model response text'),
          turnCount: z.number().describe('Number of turns in this session'),
        },
        annotations: {
          readOnlyHint: false,
          destructiveHint: false,
          openWorldHint: true,
        },
      },
      async ({ message, sessionId, model, systemInstruction }) => {
        try {
          let session = sessionId ? getSession(sessionId) : undefined;
          const id = session ? sessionId! : generateSessionId();
  
          if (!session) {
            const chat = ai.chats.create({
              model,
              config: systemInstruction ? { systemInstruction } : undefined,
            });
            session = { chat, turnCount: 0, lastActivity: Date.now() };
            storeSession(id, session);
          }
  
          const response = await session.chat.sendMessage({ message });
          session.turnCount++;
          session.lastActivity = Date.now();
  
          const result = {
            sessionId: id,
            response: response.text ?? '',
            turnCount: session.turnCount,
          };
  
          return {
            structuredContent: result,
            content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
          };
        } catch (error) {
          return formatToolError(error);
        }
      },
    );
  }

• src/gemini-client.ts:3-34 (helper)

  Helper utilities for chat session management: ChatSession interface, session storage Map, and functions for generating/retrieving/storing sessions.

  export interface ChatSession {
    chat: any;
    turnCount: number;
    lastActivity: number;
  }
  
  const sessions = new Map<string, ChatSession>();
  const SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
  
  export function createClient(apiKey: string): GoogleGenAI {
    return new GoogleGenAI({ apiKey });
  }
  
  export function generateSessionId(): string {
    return crypto.randomUUID();
  }
  
  export function getSession(id: string): ChatSession | undefined {
    const session = sessions.get(id);
    if (session) {
      session.lastActivity = Date.now();
    }
    return session;
  }
  
  export function storeSession(id: string, session: ChatSession): void {
    sessions.set(id, session);
  }
  
  export function deleteSession(id: string): boolean {
    return sessions.delete(id);
  }

• src/index.ts:26-26 (registration)

  Main server registration point where the chat tool is registered with the MCP server instance.

  registerChat(server, ai);