MCP Tools Module

The MCP tools module provides integration between MCP clustering tools and the RAG chat system. It converts MCP tool definitions to OpenAI function calling format and handles tool execution.

Overview

This module enables the LLM to automatically decide when to use clustering analysis tools to answer questions about conference topics, trends, and developments during RAG chat sessions. It also exposes summarize_interesting_papers and recommend_related_papers, which use the paper ratings forwarded from the web UI.

Quick Start

from abstracts_explorer.mcp_tools import (
    get_mcp_tools_schema,
    execute_mcp_tool,
    format_tool_result_for_llm,
)

# Get tool schemas for OpenAI function calling
schemas = get_mcp_tools_schema()

# Execute a tool
result = execute_mcp_tool(
    "get_conference_topics",
    {"n_clusters": 8}
)

# Format the result for LLM consumption
formatted = format_tool_result_for_llm("get_conference_topics", result)

API Reference

MCP Tools Integration for RAG Chat

This module provides integration between MCP clustering tools and the RAG chat system. It converts MCP tool definitions to OpenAI function calling format and handles tool execution.

The integration allows the LLM to automatically decide when to use clustering tools to answer questions about conference topics, trends, and developments.

exception abstracts_explorer.mcp_tools.MCPToolsError[source]

Bases: Exception

Exception raised for MCP tools-related errors.

class abstracts_explorer.mcp_tools.NormRule(target, aliases=(), convert=<function _identity>, convert_existing=True, drop_on_error=False)[source]

Bases: object

One normalization rule for LLM-generated tool arguments.

Parameters:

  • target (str) – Canonical argument name.

  • aliases (Tuple[str, ...]) – Alternate names produced by the LLM. Aliases are dropped when the canonical name is already present.

  • convert (Callable[[Any], Any]) – Conversion applied to the selected value.

  • convert_existing (bool) – Whether to convert the value when the canonical name is already present. Defaults to True.

  • drop_on_error (bool) – Remove the canonical argument when conversion raises. Otherwise the argument is set to None.

target: str
aliases: Tuple[str, ...] = ()
convert()

Return value unchanged.

Return type:

Any

convert_existing: bool = True
drop_on_error: bool = False
__init__(target, aliases=(), convert=<function _identity>, convert_existing=True, drop_on_error=False)
abstracts_explorer.mcp_tools.execute_mcp_tool(tool_name, arguments)[source]

Execute an MCP tool with the given arguments.

Arguments are normalized before dispatch to handle common LLM output quirks (e.g. "year" instead of "years", list values for scalar string fields). After normalization, any keyword arguments that are not accepted by the target function are silently dropped with a WARNING log entry so that tools never raise TypeError for unexpected keys.

Parameters:

  • tool_name (str) – Name of the tool to execute

  • arguments (Dict[str, Any]) – Arguments to pass to the tool

Returns:

Tool execution result (JSON string)

Return type:

str

Raises:

MCPToolsError – If tool execution fails or tool is unknown

abstracts_explorer.mcp_tools.get_mcp_tools_schema(conferences=None, years=None)[source]

Get the MCP tools schema for OpenAI function calling.

When conferences or years are provided (typically queried from the database), they are injected as enum constraints into every tool property that accepts conference or year values. This lets the LLM pick from the exact values stored in the database instead of guessing.

Parameters:

  • conferences (Optional[List[str]]) – Available conference names (e.g. ["NeurIPS", "ICLR"]). Injected as enum into conference-related properties.

  • years (Optional[List[int]]) – Available years (e.g. [2024, 2025]). Injected as enum into year-related properties.

Returns:

List of tool definitions in OpenAI format

Return type:

List[Dict[str, Any]]

abstracts_explorer.mcp_tools.format_tool_result_for_llm(tool_name, result)[source]

Format tool execution result for LLM consumption.

This function extracts the most relevant information from tool results and formats it in a way that’s easy for the LLM to process.

Parameters:

  • tool_name (str) – Name of the tool that was executed

  • result (str) – Raw tool result (JSON string)

Returns:

Formatted result suitable for LLM processing

Return type:

str