Polybrain MCP Server

Instructions

Implementation Reference

• src/mcp-tools.ts:43-154 (handler)

  The core handler logic for the 'chat' tool: determines or creates conversation, selects model/client, adds user message, calls OpenAI chat, stores assistant response, returns JSON with conversationId, response, reasoning, modelId.

  async ({ message, conversationId, modelId, reasoning }) => {
    try {
      logger.debug("Chat tool called", {
        hasConversationId: !!conversationId,
        modelId,
      });
  
      let actualConversationId: string;
      let actualModelId: string;
  
      // Determine conversation ID and model ID
      if (conversationId) {
        const existing = conversationManager.getConversation(conversationId);
        if (!existing) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error: Conversation not found: ${conversationId}`,
              },
            ],
          };
        }
  
        if (modelId && modelId !== existing.modelId) {
          // Clone conversation with new model
          actualConversationId = conversationManager.cloneConversation(conversationId, modelId);
          actualModelId = modelId;
        } else {
          // Continue existing conversation
          actualConversationId = conversationId;
          actualModelId = existing.modelId;
        }
      } else {
        // Create new conversation
        actualModelId = modelId || config.models[0].id;
        actualConversationId = conversationManager.createConversation(actualModelId);
      }
  
      // Validate model exists and get its full model name
      const client = openaiClients.get(actualModelId);
      if (!client) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: Model not configured: ${actualModelId}`,
            },
          ],
        };
      }
  
      // Get the full model name from config for API calls
      const modelConfig = config.models.find((m) => m.id === actualModelId);
      if (!modelConfig) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: Model configuration not found: ${actualModelId}`,
            },
          ],
        };
      }
  
      // Add user message to conversation
      conversationManager.addMessage(actualConversationId, "user", message);
  
      // Get conversation history
      const history = conversationManager.getHistory(actualConversationId);
  
      // Send to OpenAI - use the full modelName for the API call
      const response = await client.chat(modelConfig.modelName, history, {
        reasoning,
        provider: modelConfig.provider,
      });
  
      // Add assistant response to conversation
      conversationManager.addMessage(actualConversationId, "assistant", response.content);
  
      logger.info("Chat completed", {
        conversationId: actualConversationId,
        modelId: actualModelId,
      });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              conversationId: actualConversationId,
              response: response.content,
              reasoning: response.reasoning,
              modelId: actualModelId,
            }),
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      logger.error("Chat tool error", error instanceof Error ? error : new Error(errorMessage));
  
      return {
        content: [
          {
            type: "text" as const,
            text: `Error: ${errorMessage}`,
          },
        ],
      };
    }
  }

• src/mcp-tools.ts:17-42 (schema)

  Tool schema definition including title, detailed description with usage examples, and Zod-validated input schema for 'chat' tool parameters.

  {
    title: "Chat with Another LLM Model",
    description:
      'Send a message to an available LLM for help, second opinions, or brainstorming; start new conversations, continue existing ones, or switch models mid-chat. In the first message you shall provide as much context as possible, since the model has no idea of the problem.\n\nExample workflow:\n1. chat(message: "hello", modelId: "gpt-5-mini") → conversationId: "abc1"\n2. chat(message: "follow-up", conversationId: "abc1") → conversationId: "abc1" (continues)\n3. chat(message: "same question", conversationId: "abc1", modelId: "deepseek-r1") → conversationId: "xyz9" (cloned with new model)',
    inputSchema: z.object({
      message: z.string().describe("The question or request to send—be clear and specific."),
      conversationId: z
        .string()
        .optional()
        .describe(
          "ID of the conversation to continue; omit to start a new one. Use the conversationId from prior responses to keep discussing the same topic."
        ),
      modelId: z
        .string()
        .optional()
        .describe(
          "ID of model to use (call list_models); omitted = default model. To switch models, pass a different modelId with your conversationId — you'll get a new conversationId with the conversation cloned to the new model."
        ),
      reasoning: z
        .boolean()
        .optional()
        .describe(
          "Set true to have the model show its reasoning steps, useful for complex problems."
        ),
    }),
  },

• src/mcp-tools.ts:15-155 (registration)

  Registers the 'chat' tool on the MCP server using server.registerTool with name, schema, and handler function.

  server.registerTool(
    "chat",
    {
      title: "Chat with Another LLM Model",
      description:
        'Send a message to an available LLM for help, second opinions, or brainstorming; start new conversations, continue existing ones, or switch models mid-chat. In the first message you shall provide as much context as possible, since the model has no idea of the problem.\n\nExample workflow:\n1. chat(message: "hello", modelId: "gpt-5-mini") → conversationId: "abc1"\n2. chat(message: "follow-up", conversationId: "abc1") → conversationId: "abc1" (continues)\n3. chat(message: "same question", conversationId: "abc1", modelId: "deepseek-r1") → conversationId: "xyz9" (cloned with new model)',
      inputSchema: z.object({
        message: z.string().describe("The question or request to send—be clear and specific."),
        conversationId: z
          .string()
          .optional()
          .describe(
            "ID of the conversation to continue; omit to start a new one. Use the conversationId from prior responses to keep discussing the same topic."
          ),
        modelId: z
          .string()
          .optional()
          .describe(
            "ID of model to use (call list_models); omitted = default model. To switch models, pass a different modelId with your conversationId — you'll get a new conversationId with the conversation cloned to the new model."
          ),
        reasoning: z
          .boolean()
          .optional()
          .describe(
            "Set true to have the model show its reasoning steps, useful for complex problems."
          ),
      }),
    },
    async ({ message, conversationId, modelId, reasoning }) => {
      try {
        logger.debug("Chat tool called", {
          hasConversationId: !!conversationId,
          modelId,
        });
  
        let actualConversationId: string;
        let actualModelId: string;
  
        // Determine conversation ID and model ID
        if (conversationId) {
          const existing = conversationManager.getConversation(conversationId);
          if (!existing) {
            return {
              content: [
                {
                  type: "text" as const,
                  text: `Error: Conversation not found: ${conversationId}`,
                },
              ],
            };
          }
  
          if (modelId && modelId !== existing.modelId) {
            // Clone conversation with new model
            actualConversationId = conversationManager.cloneConversation(conversationId, modelId);
            actualModelId = modelId;
          } else {
            // Continue existing conversation
            actualConversationId = conversationId;
            actualModelId = existing.modelId;
          }
        } else {
          // Create new conversation
          actualModelId = modelId || config.models[0].id;
          actualConversationId = conversationManager.createConversation(actualModelId);
        }
  
        // Validate model exists and get its full model name
        const client = openaiClients.get(actualModelId);
        if (!client) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error: Model not configured: ${actualModelId}`,
              },
            ],
          };
        }
  
        // Get the full model name from config for API calls
        const modelConfig = config.models.find((m) => m.id === actualModelId);
        if (!modelConfig) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error: Model configuration not found: ${actualModelId}`,
              },
            ],
          };
        }
  
        // Add user message to conversation
        conversationManager.addMessage(actualConversationId, "user", message);
  
        // Get conversation history
        const history = conversationManager.getHistory(actualConversationId);
  
        // Send to OpenAI - use the full modelName for the API call
        const response = await client.chat(modelConfig.modelName, history, {
          reasoning,
          provider: modelConfig.provider,
        });
  
        // Add assistant response to conversation
        conversationManager.addMessage(actualConversationId, "assistant", response.content);
  
        logger.info("Chat completed", {
          conversationId: actualConversationId,
          modelId: actualModelId,
        });
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                conversationId: actualConversationId,
                response: response.content,
                reasoning: response.reasoning,
                modelId: actualModelId,
              }),
            },
          ],
        };
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        logger.error("Chat tool error", error instanceof Error ? error : new Error(errorMessage));
  
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: ${errorMessage}`,
            },
          ],
        };
      }
    }
  );

• src/types.ts:33-38 (schema)

  TypeScript interface defining the ChatRequest type, matching the Zod schema for chat tool inputs.

  export interface ChatRequest {
    message: string;
    conversationId?: string;
    modelId?: string;
    reasoning?: boolean;
  }

• src/openai-client.ts:80-142 (helper)

  OpenAIClient.chat method called by the chat tool handler to perform the actual LLM chat completion request.

  async chat(
    modelId: string,
    messages: ChatMessage[],
    options?: ChatOptions
  ): Promise<{ content: string; reasoning?: string }> {
    try {
      logger.debug("Sending chat request to OpenAI", {
        model: modelId,
        messageCount: messages.length,
        reasoning: options?.reasoning,
      });
  
      const openaiMessages = messages.map((msg) => ({
        role: msg.role as "user" | "assistant",
        content: msg.content,
      }));
  
      const client = this.getClient();
  
      // Build provider-specific reasoning params
      const reasoningParams = this.buildReasoningParams(
        options?.provider,
        options?.reasoning ?? false
      );
  
      const response = await client.chat.completions.create({
        model: modelId,
        messages: openaiMessages,
        ...reasoningParams,
      });
  
      const textContent = response.choices[0]?.message?.content;
      if (!textContent) {
        throw new Error("No content in response from OpenAI");
      }
  
      logger.debug("Received response from OpenAI", {
        model: modelId,
        tokens: response.usage?.total_tokens,
      });
  
      // Extract reasoning if present and requested
      let reasoning: string | undefined;
      if (options?.reasoning) {
        reasoning = this.extractReasoning(
          response.choices[0].message as unknown as Record<string, unknown>
        );
      }
  
      return {
        content: textContent,
        reasoning,
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      logger.error("OpenAI API error", {
        model: modelId,
        error: errorMessage,
      });
  
      throw new Error(`Failed to get response from OpenAI: ${errorMessage}`);
    }
  }