Clarify base_url docs and add server instructions

Update: clarify the Annotated base_url parameter docstrings across mcp modules (collection, dataset, dataverse, file, search) to state that the MCP server's connected dataverse is used by default. Add DataverseMCP.base_url and base_url_instructions properties and include the base_url_instructions text in multiple tool descriptions so tools explicitly inform users which dataverse the MCP is connected to and how to override it. Also tighten dependency version bounds in pyproject.toml for several optional mcp-related packages.

Author: JR-1991

pyDataverse/mcp/collection.py

@@ -17,8 +17,8 @@ def get_collection_metadata(
     ],
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
-    ],
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
+    ] = None,
     ctx: Context = CurrentContext(),
 ) -> str:
     """
@@ -39,8 +39,8 @@ def list_content(
     ],
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
-    ],
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
+    ] = None,
     ctx: Context = CurrentContext(),
 ) -> str:
     """
@@ -80,7 +80,7 @@ def get_graph_summary(
     depth: int = 3,
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
     ] = None,
     ctx: Context = CurrentContext(),
 ) -> str:
@@ -130,7 +130,7 @@ def query_sparql(
     ] = 3,
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
     ] = None,
     ctx: Context = CurrentContext(),
 ) -> str:

pyDataverse/mcp/dataset.py

@@ -43,8 +43,8 @@ def get_dataset(
     ],
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
-    ],
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
+    ] = None,
     ctx: Context = CurrentContext(),
 ):
     """
@@ -119,8 +119,8 @@ def list_files(
     ],
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
-    ],
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
+    ] = None,
     ctx: Context = CurrentContext(),
 ):
     """

pyDataverse/mcp/dataverse.py

@@ -10,7 +10,7 @@
 def get_metrics(
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
     ] = None,
     ctx: Context = CurrentContext(),
 ):

pyDataverse/mcp/file.py

@@ -90,8 +90,8 @@ def read_file(
     ],
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
-    ],
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
+    ] = None,
     ctx: Context = CurrentContext(),
 ) -> Union[ImageContent, List[TextContent], EmbeddedResource, TextContent]:
     """
@@ -209,7 +209,7 @@ def read_tabular(
     ] = None,
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
     ] = None,
     ctx: Context = CurrentContext(),
 ) -> str:
@@ -280,7 +280,7 @@ def tabular_schema(
     ],
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
     ] = None,
     ctx: Context = CurrentContext(),
 ) -> str:

pyDataverse/mcp/search.py

@@ -117,7 +117,7 @@ def search(
     per_page: Annotated[int, "Maximum number of results to return per page"] = 10,
     base_url: Annotated[
         Optional[str],
-        "The base URL of the dataverse to use. If not specified, the function will use the dataverse from the context.",
+        "The base URL of the dataverse to use. If not specified, the function will use the dataverse this MCP server is connected to by default.",
     ] = None,
     ctx: Context = CurrentContext(),
 ):

pyDataverse/mcp/server.py

@@ -85,6 +85,20 @@ def __init__(
 
         self.config = config or MCPConfiguration()
 
+    @property
+    def base_url(self) -> str:
+        """
+        Get the base URL of the dataverse.
+        """
+        return self.dataverse.base_url
+
+    @property
+    def base_url_instructions(self) -> str:
+        """
+        Get the base URL instructions for the dataverse.
+        """
+        return f"This MCP server is connected to the dataverse at {self.base_url}. Provide the `base_url` parameter if you want to use a different dataverse."
+
     def to_mcp(self, mcp: FastMCP):
         """
         Configure the provided FastMCP instance with Dataverse tools and middleware.
@@ -116,7 +130,7 @@ def _add_dataverse_tools(self, mcp: FastMCP):
             mcp.tool(
                 get_metrics,
                 name="Dataverse_Metrics",
-                description="Get metrics from the dataverse in total and for the past 7 days. This tool returns the metrics of the dataverse in a TOON format.",
+                description=f"Get metrics from the dataverse in total and for the past 7 days. This tool returns the metrics of the dataverse in a TOON format. {self.base_url_instructions}",
             )
 
     def _add_dataset_tools(self, mcp: FastMCP):
@@ -142,14 +156,16 @@ def _add_dataset_tools(self, mcp: FastMCP):
             The available metadata blocks are: {", ".join(available_metadatablocks)}. 
             If you do not specify the metadata blocks, the function will return all metadata blocks.
             To save tokens and compute resources, you should first request the dataset without the `full` flag to get the available metadata blocks and then request the dataset with the `full` flag and the metadata blocks you want to see.
+            
+            {self.base_url_instructions}
             """.strip(),
         )
 
         mcp.tool(
             list_files,
             name="List_Files_in_Dataset",
             enabled="read" in self.config.dataset,
-            description="List the files in a dataset. This tool returns the files in a TOON format.",
+            description=f"List the files in a dataset. This tool returns the files in a TOON format. {self.base_url_instructions}",
         )
 
     def _add_file_tools(self, mcp: FastMCP):
@@ -168,28 +184,32 @@ def _add_file_tools(self, mcp: FastMCP):
             read_tabular,
             name="Read_Tabular_File",
             enabled="read" in self.config.file,
-            description="""
+            description=f"""
             Read a tabular file from a dataset. This tool returns the file in a TOON format.
             When `summarize` is True, the function will return the description of the file using the `describe` method of the pandas DataFrame.
             When `n_rows` is specified, the function will return the first `n_rows` rows of the file.
             When `n_rows` is not specified, the function will return the entire file. Please note that this is capped to 1000 rows.
+            
+            {self.base_url_instructions}
             """.strip(),
         )
 
         mcp.tool(
             read_file,
             name="Read_File_Content",
             enabled="read" in self.config.file,
-            description="""
+            description=f"""
             Read then content of a file from a dataset. This tool returns the raw content of the file.
+            
+            {self.base_url_instructions}
             """.strip(),
         )
 
         mcp.tool(
             tabular_schema,
             name="Get_Tabular_File_Schema",
             enabled="read" in self.config.file,
-            description="Get the schema of a tabular file. This tool returns the schema of the file in a TOON format.",
+            description=f"Get the schema of a tabular file. This tool returns the schema of the file in a TOON format. {self.base_url_instructions}",
         )
 
     def _add_collection_tools(self, mcp: FastMCP):
@@ -206,42 +226,48 @@ def _add_collection_tools(self, mcp: FastMCP):
             get_collection_metadata,
             name="Get_Collection_Metadata",
             enabled="read" in self.config.collection,
-            description="Get the metadata of a collection. This tool returns the metadata of the collection in a TOON format.",
+            description=f"Get the metadata of a collection. This tool returns the metadata of the collection in a TOON format. {self.base_url_instructions}",
         )
 
         mcp.tool(
             list_content,
             name="List_Content_of_Collection",
             enabled="read" in self.config.collection,
-            description="""
+            description=f"""
             List the content of a collection. This tool returns the content in a TOON format.
             You can filter the content by type. The available types are: dataset, collection.
+            
+            {self.base_url_instructions}
             """.strip(),
         )
 
         mcp.tool(
             get_graph_summary,
             name="Knowledge_Graph_Summary",
             enabled="graph" in self.config.collection,
-            description="""
+            description=f"""
             Get the summary of the RDF graph of a collection. This tool returns all classes and predicates 
             found in the collection's knowledge graph, including their full URIs and short names. 
             Useful for exploring the semantic structure of a collection before writing SPARQL queries.
             The graph can be generated in different formats: "croissant" or "OAI_ORE".
             Returns the summary in a TOON format.
+            
+            {self.base_url_instructions}
             """.strip(),
         )
 
         mcp.tool(
             query_sparql,
             name="Query_Knowledge_Graph",
             enabled="graph" in self.config.collection,
-            description="""
+            description=f"""
             Execute a SPARQL query against a collection's RDF graph. This tool allows you to query the 
             semantic metadata of a collection using SPARQL syntax. The graph can be generated in different 
             formats: "croissant" or "OAI_ORE". Query results are returned as a list of dictionaries where 
             each dictionary represents a result row with variable names as keys. Use get_graph_summary first 
             to explore available classes and predicates before writing queries. Returns results in a TOON format.
+            
+            {self.base_url_instructions}
             """.strip(),
         )
 

pyproject.toml

@@ -21,7 +21,7 @@ dependencies = [
     "asyncer>=0.0.10,<0.0.11",
     "bigtree>=1.0.0,<2.0.0",
     "rdflib>=7.5.0,<8.0.0",
-    "sniffio>=1.3.1",
+    "sniffio>=1.3.1<2.0.0",
 ]
 
 [project.optional-dependencies]
@@ -35,13 +35,13 @@ tests = [
     "ruff>=0.4.4,<0.5.0",
 ]
 mcp = [
-    "fastmcp>=2.14.5",
-    "mcp>=1.26.0",
-    "nbconvert>=7.17.0",
-    "nbformat>=5.10.4",
-    "pillow>=12.1.1",
-    "pymupdf>=1.27.1",
-    "toon-format==0.9.0b1",
+    "fastmcp>=2.14.5<3.0.0",
+    "mcp>=1.26.0<2.0.0",
+    "nbconvert>=7.17.0<8.0.0",
+    "nbformat>=5.10.4<6.0.0",
+    "pillow>=12.1.1<13.0.0",
+    "pymupdf>=1.27.1<2.0.0",
+    "toon-format==0.9.0b1<0.10.0",
 ]
 
 [project.urls]