MCP Server for Cluster Analysis

The Abstracts Explorer includes a Model Context Protocol (MCP) server that provides tools for analyzing clustered paper embeddings. This enables LLM-based assistants to answer sophisticated questions about research topics, trends, and developments.

NEW: MCP tools are automatically integrated into the RAG chat system, allowing the LLM to decide when to use clustering analysis versus paper retrieval.

What is MCP?

Model Context Protocol (MCP) is a protocol that allows tools and servers to provide context and capabilities to LLM-based applications. The MCP server exposes tools that can be called by LLM assistants to perform specific tasks.

Features

The MCP server provides tools for conference analysis plus two personalized tools that work with the papers a user marked as interesting.

1. get_conference_topics

Analyzes clustered embeddings to identify the most frequently mentioned topics in each cluster.

Parameters:

• conferences (list of str): Conference names to analyze (e.g., ["NeurIPS"]). Required.

• years (list of int, optional): Filter by specific years

• collection_name (str, optional): Name of ChromaDB collection

Returns: JSON with cluster statistics and topics for each cluster, including:

• Keywords and their frequencies

• Common sessions

• Year distribution

• Sample paper titles

Example use case: “What are the most frequently mentioned topics in the conference papers?”

2. get_topic_evolution

Analyzes how specific topics have evolved over the years.

Parameters:

• topic_keywords (str): Keywords describing the topic (e.g., “transformers attention”)

• conference (str, optional): Filter by conference name

• start_year (int, optional): Start year for analysis

• end_year (int, optional): End year for analysis

• embeddings_path (str, optional): Path to ChromaDB embeddings database

• collection_name (str, optional): Name of ChromaDB collection

• db_path (str, optional): Path to SQLite database

Returns: JSON with topic evolution data including:

• Year-by-year paper counts

• Sample papers from each year

• Relevance scores

Example use case: “How have topics related to ‘transformer architectures’ evolved over the years at NeurIPS?”

3. search_papers

Finds the most important recent developments in a specific topic.

Parameters:

• topic_keywords (str): Keywords describing the topic

• years (list): List of years to consider (default: None, which means all years)

• n_results (int): Number of papers to return (default: 10)

• conference (str, optional): Filter by conference name

• embeddings_path (str, optional): Path to ChromaDB embeddings database

• collection_name (str, optional): Name of ChromaDB collection

• db_path (str, optional): Path to SQLite database

Returns: JSON with recent papers including:

• Paper titles and abstracts

• Years and conferences

• Relevance scores

Example use case: “What are the most important recent developments in large language models?”

4. get_cluster_visualization

Generates visualization data for clustered embeddings.

Parameters:

• conferences (list of str): Conference names to retrieve visualization for (e.g., ["NeurIPS"]). Required.

• years (list of int, optional): Filter by specific years

• output_path (str, optional): Path to save visualization JSON

• collection_name (str, optional): Name of ChromaDB collection

Returns: JSON with visualization data including:

• Point coordinates (x, y, optionally z)

• Cluster assignments

• Paper metadata

• Statistics

Example use case: “Display a graphical representation of the paper clusters.”

5. summarize_interesting_papers

Summarizes the papers a user marked, starred, liked, or rated as interesting.

Ratings are stored in the browser (localStorage.paperPriorities) and are forwarded automatically by the web UI chat. The tool receives them as parameters; no ratings are persisted server-side.

Parameters:

• paper_ids (list of str, optional): Paper UIDs. When omitted, the keys of priorities are used.

• priorities (dict, optional): Mapping of paper UID to a dict with priority and optional searchTerm.

• conference (str, optional): Conference filter (e.g. "ICLR" or "ICLR 2026").

• years (list of int, optional): Year filter (e.g. [2026]).

Returns: JSON with:

• Total interesting papers and rating distribution/average

• Conferences, years, sessions, search terms, and top keywords

• Highest-rated papers and compact paper records

Example use case: “Give me a summary about the papers I marked as interesting for ICLR’26!”

6. recommend_related_papers

Recommends further papers based on a rating-weighted embedding centroid of the user’s interesting papers. Papers the user already rated are excluded.

Parameters:

• paper_ids (list of str, optional): Paper UIDs. When omitted, the keys of priorities are used.

• priorities (dict, optional): Mapping of paper UID to a dict with priority and optional searchTerm.

• conferences (list of str, optional): Restrict recommendations to these conferences. Defaults to the dominant conference of the interesting papers.

• years (list of int, optional): Restrict recommendations to these years. Defaults to the years of the interesting papers.

• n_results (int, optional): Number of recommendations (default: 10).

• exclude_ids (list of str, optional): Additional UIDs to exclude.

Returns: JSON with recommended papers, each including a relevance score and reasons (shared keywords, authors, session, or semantic closeness).

Example use case: “Based on my interesting papers, suggest other papers that may interest me.”

Starting the MCP Server

Basic Usage

Start the server with default settings:

abstracts-explorer mcp-server

This starts the server on http://127.0.0.1:8000/mcp with streamable HTTP transport.

Custom Host and Port

Start on a custom host and port:

abstracts-explorer mcp-server --host 0.0.0.0 --port 8080

STDIO Transport

For local CLI integration, use stdio transport:

abstracts-explorer mcp-server --transport stdio

Configuration

The MCP server uses the same configuration as the rest of Abstracts Explorer. Configure via .env file:

# Database Configuration
PAPER_DB=abstracts.db
EMBEDDING_DB_PATH=chroma_db
COLLECTION_NAME=papers

# LLM Backend (for embeddings in tools)
LLM_BACKEND_URL=http://localhost:1234
EMBEDDING_MODEL=text-embedding-qwen3-embedding-4b

Integration with LLM Assistants

The MCP server can be integrated with any MCP-compatible LLM assistant or client. It’s now automatically integrated into the RAG chat system.

RAG Chat Integration (Recommended)

The easiest way to use MCP tools is through the RAG chat system, which automatically calls the appropriate tools:

from abstracts_explorer.rag import RAGChat
from abstracts_explorer.embeddings import EmbeddingsManager
from abstracts_explorer.database import DatabaseManager

# Initialize components
em = EmbeddingsManager()
db = DatabaseManager()

# Create RAG chat (MCP tools enabled by default)
chat = RAGChat(em, db, enable_mcp_tools=True)

# The LLM automatically uses clustering tools when appropriate
response = chat.query("What are the main topics at NeurIPS?")
# Internally calls get_conference_topics() and uses results

response = chat.query("How have transformers evolved over time?")
# Internally calls get_topic_evolution(topic_keywords="transformers")

See the RAG API documentation for more details.

Claude Desktop Integration

Add to Claude Desktop MCP configuration:

{
  "mcpServers": {
    "abstracts-explorer": {
      "command": "abstracts-explorer",
      "args": ["mcp-server", "--transport", "stdio"]
    }
  }
}

Example Tool Call

When an LLM assistant needs to analyze topics, it can call:

{
  "tool": "get_conference_topics",
  "arguments": {
    "conferences": ["NeurIPS"],
    "years": [2024, 2025]
  }
}

The server will:

1. Load pre-computed clustering results from the database cache

2. Analyze topics in each cluster

3. Return structured JSON results

API Reference

Tool Response Format

All tools return JSON strings with the following general structure:

{
  "statistics": {
    "n_clusters": 8,
    "total_papers": 1000
  },
  "clusters": [
    {
      "cluster_id": 0,
      "paper_count": 150,
      "keywords": [
        {"keyword": "transformer", "count": 45},
        {"keyword": "attention", "count": 38}
      ],
      "sessions": [
        {"session": "Deep Learning", "count": 100}
      ],
      "years": {"2023": 80, "2024": 70},
      "sample_titles": ["Paper 1", "Paper 2", "Paper 3"]
    }
  ]
}

Error Handling

If an error occurs, tools return JSON with an error field:

{
  "error": "Failed to load clustering data: Database not found"
}

Requirements

Before using the MCP server, ensure:

1. Embeddings are created: Run abstracts-explorer create-embeddings first

2. Database exists: Download papers with abstracts-explorer download

3. MCP package installed: uv sync or pip install "mcp>=2.0.0,<3"

Troubleshooting

“No embeddings found”

Make sure to create embeddings first:

abstracts-explorer create-embeddings

“Failed to connect to database”

Check that the database paths in .env are correct:

# .env
PAPER_DB=data/abstracts.db
EMBEDDING_DB_PATH=chroma_db

Port already in use

Change the port:

abstracts-explorer mcp-server --port 8001

Advanced Usage

Clustering Configuration

The MCP tools read pre-computed clustering results from the database cache. The pipeline is fixed to Agglomerative clustering (ward linkage, distance threshold 150) with t-SNE dimensionality reduction. Generate the cache with:

abstracts-explorer clustering pre-generate --conference NeurIPS

Filtering by Conference

Analyze specific conferences:

# get_topic_evolution arguments
{
  "topic_keywords": "neural networks",
  "conferences": ["NeurIPS"],
  "start_year": 2020,
  "end_year": 2024
}

See Also

• CLI Reference - Command-line interface documentation

• Clustering Guide - Clustering and visualization guide

• RAG Chat - Using RAG chat with MCP tools

• Configuration - Environment configuration options