MCP-DBLP

Instructions

Implementation Reference

• src/mcp_dblp/server.py:280-309 (handler)

  Handler logic for the 'search' MCP tool within the call_tool method. Validates input, calls dblp_client.search, formats results with optional BibTeX, and returns text content.

  case "search":
      if "query" not in arguments:
          return [
              types.TextContent(
                  type="text", text="Error: Missing required parameter 'query'"
              )
          ]
      include_bibtex = arguments.get("include_bibtex", False)
      result = search(
          query=arguments.get("query"),
          max_results=arguments.get("max_results", 10),
          year_from=arguments.get("year_from"),
          year_to=arguments.get("year_to"),
          venue_filter=arguments.get("venue_filter"),
          include_bibtex=include_bibtex,
      )
      if include_bibtex:
          return [
              types.TextContent(
                  type="text",
                  text=f"Found {len(result)} publications matching your query:\n\n{format_results_with_bibtex(result)}",
              )
          ]
      else:
          return [
              types.TextContent(
                  type="text",
                  text=f"Found {len(result)} publications matching your query:\n\n{format_results(result)}",
              )
          ]

• src/mcp_dblp/server.py:101-126 (schema)

  Schema definition for the 'search' tool, including detailed description and input schema, returned by list_tools().

      name="search",
      description=(
          "Search DBLP for publications using a boolean query string.\n"
          "Arguments:\n"
          "  - query (string, required): A query string that may include boolean operators 'and' and 'or' (case-insensitive).\n"
          "    For example, 'Swin and Transformer'. Parentheses are not supported.\n"
          "  - max_results (number, optional): Maximum number of publications to return. Default is 10.\n"
          "  - year_from (number, optional): Lower bound for publication year.\n"
          "  - year_to (number, optional): Upper bound for publication year.\n"
          "  - venue_filter (string, optional): Case-insensitive substring filter for publication venues (e.g., 'iclr').\n"
          "  - include_bibtex (boolean, optional): Whether to include BibTeX entries in the results. Default is false.\n"
          "Returns a list of publication objects including title, authors, venue, year, type, doi, ee, and url."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "query": {"type": "string"},
              "max_results": {"type": "number"},
              "year_from": {"type": "number"},
              "year_to": {"type": "number"},
              "venue_filter": {"type": "string"},
              "include_bibtex": {"type": "boolean"},
          },
          "required": ["query"],
      },
  ),

• src/mcp_dblp/server.py:83-258 (registration)

  Registration of the 'search' tool via the list_tools() handler, which returns all available tools including 'search'.

  @server.list_tools()
  async def list_tools() -> list[types.Tool]:
      """List all available DBLP tools with detailed descriptions."""
      return [
          types.Tool(
              name="get_instructions",
              description=(
                  "Get detailed DBLP usage instructions. Key points:\n"
                  "- Batch searches in parallel (5-10 at a time) for efficiency\n"
                  "- Add entries immediately after each search result (don't batch add_bibtex_entry calls)\n"
                  "- Use author+year for best results: search('Vaswani 2017') not just title\n"
                  "- Copy dblp_key EXACTLY from search results to add_bibtex_entry\n"
                  "- Export once at the end with export_bibtex\n"
                  "Call this tool for complete workflow details, search strategies, and examples."
              ),
              inputSchema={"type": "object", "properties": {}},
          ),
          types.Tool(
              name="search",
              description=(
                  "Search DBLP for publications using a boolean query string.\n"
                  "Arguments:\n"
                  "  - query (string, required): A query string that may include boolean operators 'and' and 'or' (case-insensitive).\n"
                  "    For example, 'Swin and Transformer'. Parentheses are not supported.\n"
                  "  - max_results (number, optional): Maximum number of publications to return. Default is 10.\n"
                  "  - year_from (number, optional): Lower bound for publication year.\n"
                  "  - year_to (number, optional): Upper bound for publication year.\n"
                  "  - venue_filter (string, optional): Case-insensitive substring filter for publication venues (e.g., 'iclr').\n"
                  "  - include_bibtex (boolean, optional): Whether to include BibTeX entries in the results. Default is false.\n"
                  "Returns a list of publication objects including title, authors, venue, year, type, doi, ee, and url."
              ),
              inputSchema={
                  "type": "object",
                  "properties": {
                      "query": {"type": "string"},
                      "max_results": {"type": "number"},
                      "year_from": {"type": "number"},
                      "year_to": {"type": "number"},
                      "venue_filter": {"type": "string"},
                      "include_bibtex": {"type": "boolean"},
                  },
                  "required": ["query"],
              },
          ),
          types.Tool(
              name="fuzzy_title_search",
              description=(
                  "Search DBLP for publications with fuzzy title matching.\n"
                  "Arguments:\n"
                  "  - title (string, required): Full or partial title of the publication (case-insensitive).\n"
                  "  - similarity_threshold (number, required): A float between 0 and 1 where 1.0 means an exact match.\n"
                  "  - max_results (number, optional): Maximum number of publications to return. Default is 10.\n"
                  "  - year_from (number, optional): Lower bound for publication year.\n"
                  "  - year_to (number, optional): Upper bound for publication year.\n"
                  "  - venue_filter (string, optional): Case-insensitive substring filter for publication venues.\n"
                  "  - include_bibtex (boolean, optional): Whether to include BibTeX entries in the results. Default is false.\n"
                  "Returns a list of publication objects sorted by title similarity score."
              ),
              inputSchema={
                  "type": "object",
                  "properties": {
                      "title": {"type": "string"},
                      "similarity_threshold": {"type": "number"},
                      "max_results": {"type": "number"},
                      "year_from": {"type": "number"},
                      "year_to": {"type": "number"},
                      "venue_filter": {"type": "string"},
                      "include_bibtex": {"type": "boolean"},
                  },
                  "required": ["title", "similarity_threshold"],
              },
          ),
          types.Tool(
              name="get_author_publications",
              description=(
                  "Retrieve publication details for a specific author with fuzzy matching.\n"
                  "Arguments:\n"
                  "  - author_name (string, required): Full or partial author name (case-insensitive).\n"
                  "  - similarity_threshold (number, required): A float between 0 and 1 where 1.0 means an exact match.\n"
                  "  - max_results (number, optional): Maximum number of publications to return. Default is 20.\n"
                  "  - include_bibtex (boolean, optional): Whether to include BibTeX entries in the results. Default is false.\n"
                  "Returns a dictionary with keys: name, publication_count, publications, and stats (which includes top venues, years, and types)."
              ),
              inputSchema={
                  "type": "object",
                  "properties": {
                      "author_name": {"type": "string"},
                      "similarity_threshold": {"type": "number"},
                      "max_results": {"type": "number"},
                      "include_bibtex": {"type": "boolean"},
                  },
                  "required": ["author_name", "similarity_threshold"],
              },
          ),
          types.Tool(
              name="get_venue_info",
              description=(
                  "Retrieve information about a publication venue from DBLP.\n"
                  "Arguments:\n"
                  "  - venue_name (string, required): Venue name or abbreviation (e.g., 'ICLR', 'NeurIPS', or full name).\n"
                  "Returns a dictionary with fields:\n"
                  "  - venue: Full venue title\n"
                  "  - acronym: Venue acronym/abbreviation (if available)\n"
                  "  - type: Venue type (e.g., 'Conference or Workshop', 'Journal', 'Repository')\n"
                  "  - url: Canonical DBLP URL for the venue\n"
                  "Note: Publisher, ISSN, and other metadata are not available through this endpoint."
              ),
              inputSchema={
                  "type": "object",
                  "properties": {"venue_name": {"type": "string"}},
                  "required": ["venue_name"],
              },
          ),
          types.Tool(
              name="calculate_statistics",
              description=(
                  "Calculate statistics from a list of publication results.\n"
                  "Arguments:\n"
                  "  - results (array, required): An array of publication objects, each with at least 'title', 'authors', 'venue', and 'year'.\n"
                  "Returns a dictionary with:\n"
                  "  - total_publications: Total count.\n"
                  "  - time_range: Dictionary with 'min' and 'max' publication years.\n"
                  "  - top_authors: List of tuples (author, count) sorted by count.\n"
                  "  - top_venues: List of tuples (venue, count) sorted by count (empty venue is treated as '(empty)')."
              ),
              inputSchema={
                  "type": "object",
                  "properties": {"results": {"type": "array"}},
                  "required": ["results"],
              },
          ),
          types.Tool(
              name="add_bibtex_entry",
              description=(
                  "Add a BibTeX entry to the collection for later export. Call this once for each paper you want to export.\n"
                  "Arguments:\n"
                  "  - dblp_key (string, required): The DBLP key from search results (e.g., 'conf/nips/VaswaniSPUJGKP17').\n"
                  "  - citation_key (string, required): The citation key to use in the .bib file (e.g., 'Vaswani2017').\n"
                  "Workflow:\n"
                  "  1. Fetches BibTeX directly from DBLP using the provided key\n"
                  "  2. Replaces the citation key with your custom key\n"
                  "  3. Adds to collection (duplicate citation_key will be overwritten)\n"
                  "  4. Returns count of entries currently in collection\n"
                  "After adding all entries, call export_bibtex to save them to a .bib file."
              ),
              inputSchema={
                  "type": "object",
                  "properties": {
                      "dblp_key": {"type": "string"},
                      "citation_key": {"type": "string"},
                  },
                  "required": ["dblp_key", "citation_key"],
              },
          ),
          types.Tool(
              name="export_bibtex",
              description=(
                  "Export all collected BibTeX entries to a .bib file. Call this after adding all entries with add_bibtex_entry.\n"
                  "Workflow:\n"
                  "  1. Saves all collected entries to a .bib file at the specified path\n"
                  "  2. Clears the collection for next export\n"
                  "  3. Returns the full path to the exported file\n"
                  "Returns error if no entries have been added yet."
              ),
              inputSchema={
                  "type": "object",
                  "properties": {
                      "path": {
                          "type": "string",
                          "description": "Absolute path for the .bib file (e.g., '/path/to/refs.bib'). The .bib extension is added automatically if missing. Parent directories are created if needed.",
                      },
                  },
                  "required": ["path"],
              },
          ),
      ]

• src/mcp_dblp/dblp_client.py:105-176 (helper)

  Core helper function implementing the DBLP search logic: API calls, query parsing, filtering, and optional BibTeX fetching. Called by the MCP tool handler.

  def search(
      query: str,
      max_results: int = 10,
      year_from: int | None = None,
      year_to: int | None = None,
      venue_filter: str | None = None,
      include_bibtex: bool = False,
  ) -> list[dict[str, Any]]:
      """
      Search DBLP using their public API.
  
      Parameters:
          query (str): The search query string.
          max_results (int, optional): Maximum number of results to return. Default is 10.
          year_from (int, optional): Lower bound for publication year.
          year_to (int, optional): Upper bound for publication year.
          venue_filter (str, optional): Case-insensitive substring filter
              for publication venues.
          include_bibtex (bool, optional): Whether to include BibTeX entries
              in the results. Default is False.
  
      Returns:
          List[Dict[str, Any]]: A list of publication dictionaries.
      """
      query_lower = query.lower()
      if "(" in query or ")" in query:
          logger.warning(
              "Parentheses are not supported in boolean queries. "
              "They will be treated as literal characters."
          )
      results = []
      if " or " in query_lower:
          subqueries = [q.strip() for q in query_lower.split(" or ") if q.strip()]
          seen = set()
          for q in subqueries:
              for pub in _fetch_publications(q, max_results):
                  identifier = (pub.get("title"), pub.get("year"))
                  if identifier not in seen:
                      results.append(pub)
                      seen.add(identifier)
      else:
          results = _fetch_publications(query, max_results)
  
      filtered_results = []
      for result in results:
          if year_from or year_to:
              year = result.get("year")
              if year:
                  try:
                      year = int(year)
                      if (year_from and year < year_from) or (year_to and year > year_to):
                          continue
                  except (ValueError, TypeError):
                      pass
          if venue_filter:
              venue = result.get("venue", "")
              if venue_filter.lower() not in venue.lower():
                  continue
          filtered_results.append(result)
  
      if not filtered_results:
          logger.info("No results found. Consider revising your query syntax.")
  
      filtered_results = filtered_results[:max_results]
  
      # Fetch BibTeX entries if requested
      if include_bibtex:
          for result in filtered_results:
              if "dblp_key" in result and result["dblp_key"]:
                  result["bibtex"] = fetch_bibtex_entry(result["dblp_key"])
  
      return filtered_results