Merge branch 'main' into navigator

Author: 4tikhonov

README.md

@@ -1,45 +1,60 @@
 # MCP (Model Context Protocol) server for Dataverse
 
-Credits: this work is funded by [SSHOC-NL](https://sshoc.nl) project developing [Semantic Croissant](https://docs.google.com/document/d/1fi9Lb6x5Wm0L9CZftqjSGElV_ifcSW_IT-H8ZlpbrtQ/edit?tab=t.0). First version of [Croissant ML](https://docs.mlcommons.org/croissant/docs/croissant-spec.html) export for Dataverse was implemented by Phil Durbin (Harvard IQSS) and Slava Tykhonov (DANS-KNAW).
+Credits: this work is funded by the [SSHOC-NL](https://sshoc.nl) project developing [Semantic Croissant](https://docs.google.com/document/d/1fi9Lb6x5Wm0L9CZftqjSGElV_ifcSW_IT-H8ZlpbrtQ/edit?tab=t.0). The first version of [Croissant](https://docs.mlcommons.org/croissant/docs/croissant-spec.html) export for Dataverse was implemented by Philip Durbin (Harvard IQSS) and Slava Tykhonov (DANS-KNAW).
 
-If you don't know what Croissant ML is — it's a special language for machines, built on top of Schema.org. With Croissant, we aim to solve multilingual challenges and finally speak the same language across the planet.
+Croissant is a special language for machines, built on top of Schema.org. With Croissant, we aim to solve multilingual challenges and finally speak the same language across the planet.
 Even if it's artificial.
 
-Installation:
+## Getting started with mcp.dataverse.org
+
+When getting started, we recommend the public MCP server for Dataverse at <https://mcp.dataverse.org>. (Below you'll also find instructions on how to run the MCP server locally.) You can visit https://mcp.dataverse.org/tools for an inventory of available tools.
+
+You will need an MCP client with AI agent support such as [Cursor](https://www.cursor.com), [Visual Studio Code](https://code.visualstudio.com), [Windsurf Editor](https://windsurf.com), or [Zed](https://zed.dev).
+
+### (Optional) Command line test
+
+Before you get too far into configuring your MCP client, you could try this quick test to get information about a dataset by passing its DOI.
+
 ```
-cp .env-sample .env
-docker-compose build
-docker-compose up -d
+curl -X POST "https://mcp.dataverse.org/tools/get_croissant_record" -H "Content-Type: application/json" -d '{"doi":"doi:10.7910/DVN/WGCRY7"}'
 ```
 
-Go to http://127.0.0.1:8000/tools to get an overview of available tools. We have also deployed official Dataverse MCP server on https://mcp.dataverse.org
+### Configuring your MCP Client
+
+You'll be using https://mcp.dataverse.org/sse as the URL and SSE (Server-Sent Events) as the type of MCP server.
+
+Click the arrow to expand instructions for your MCP client.
+
+<details><summary>Cursor</summary>
+
+Create a configuration file for Cursor at [~/.cursor/mcp.json](https://docs.cursor.com/context/model-context-protocol):
 
-You can register MCP in Cursor, Visual Studio or Windsurf Editor, or other IDE with AI Agents support. For example, create configuration file for Cursor [~/.cursor/mcp.json](https://docs.cursor.com/context/model-context-protocol):
 ```
 {
   "mcpServers": {
     "Croissant": {
-      "url": "http://127.0.0.1:8000/sse",
+      "url": "https://mcp.dataverse.org/sse",
       "headers": {
         "Content-Type": "application/json"
       }
     }
-}
+  }
 }
 ```
 
-To register this MCP server in Visual Studio Code ([official docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)), open settings and search for "mcp". Click the link "edit in settings.json" under "Model Context Protocol server configurations" and paste the "mcp-dataverse" objects below, which are shown in a simplified version of that configuration file.
+Ensure that "auto" is selected as the agent.
+</details>
+
+<details><summary>Visual Studio Code</summary>
+
+To register the MCP server in Visual Studio Code ([official docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)), open settings and search for "mcp". Click the link "edit in settings.json" under "Model Context Protocol server configurations" and paste the "mcp-dataverse" object below, which is shown in a simplified version of that configuration file.
 
 ```
 {
 ...
   "mcp": {
     "servers": {
-      "mcp-dataverse-local": {
-        "type": "sse",
-        "url": "http://127.0.0.1:8000/sse"
-      },
-      "mcp-dataverse-remote": {
+      "mcp-dataverse": {
         "type": "sse",
         "url": "https://mcp.dataverse.org/sse"
       }
@@ -51,20 +66,57 @@ To register this MCP server in Visual Studio Code ([official docs](https://code.
 
 Next, click "view", then "open chat". Choose "Agent" in the dropdown that offers "Ask", "Edit", and "Agent".
 
-Your new MCP servers should be configured for use but you can check if they are enabled or disable one of them by clicking the "select tools" icon (just below the chat input area) and scrolling down to them (here you can also try the "add more tools" button).
+Your new MCP server should be configured for use but you can check if it are enabled by clicking the "select tools" icon (just below the chat input area) and scrolling down (here you can also try the "add more tools" button).
+</details>
+
+<details><summary>Windsurf</summary>
 
-Continue with the instructions below about what to try typing to the agent.
+As explained in the [Windsurf docs](https://docs.windsurf.com/windsurf/cascade/mcp), configure
+`~/.codeium/windsurf/mcp_config.json` with the following.
 
-## Test Croissant ML support for Dataverse
 ```
-curl -X POST "http://localhost:8000/tools/get_croissant_record" -H "Content-Type: application/json" -d '{"doi":"doi:10.7910/DVN/WGCRY7"}'
+{
+  "mcpServers": {
+    "mcp-dataverse": {
+      "serverUrl": "https://mcp.dataverse.org/sse"
+    }
+  }
+}
+```
+</details>
+
+<details><summary>Zed</summary>
+
+As explained in the [Zed docs](https://zed.dev/docs/ai/mcp), add the following to `settings.json` (the `...` indicates there are probably additional lines in your file):
+
 ```
+{
+  "context_servers": {
+    "mcp-dataverse": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "mcp-remote", "https://mcp.dataverse.org/sse"],
+        "env": null
+      },
+      "settings": {}
+    }
+  }
+...
+}
+
+```
+
+</details>
+
+### Chat examples
 
-## Connect MCP to your favourite IDE
+Here are some suggested examples to use when chatting with the MCP server.
+
+#### Explore a dataset
 
 Type in the chat of Agent:
 ```
-Connect to MCP server running on http://127.0.0.1:8000 and explore all tools with curl command.
+Connect to the MCP server running at https://mcp.dataverse.org and explore all tools using the curl command.
 
 Explore dataset doi:10.7910/DVN/6TFFPG
 ```
@@ -77,11 +129,12 @@ This dataset contains experimental data from research on Nitrogen-Vacancy (NV) c
 It includes data shown in both the main text and supplemental material of the associated scientific paper
 The research focuses on photoluminescence spectra at low magnetic fields
 ```
-## Multilingual support
+
+#### Multilingual support
 
 Let's connect to a dataset in Dutch and ask questions in English. Example dataset is taken from [DANS Archaelogy Data Station](https://archaeology.datastations.nl/dataset.xhtml?persistentId=doi:10.17026/AR/IQZTRX):
 ```
-give me overview of doi:10.17026/dans-xv2-dsx6
+give me an overview of doi:10.17026/dans-xv2-dsx6
 ```
 The response in English:
 ```
@@ -130,3 +183,18 @@ Historical geography
 Environmental studies
 Cultural heritage management
 ```
+
+## Local installation
+
+```
+cp .env-sample .env
+docker-compose build
+docker-compose up -d
+```
+
+Go to http://127.0.0.1:8000/tools to get an overview of available tools.
+
+### Test Croissant support for Dataverse
+```
+curl -X POST "http://localhost:8000/tools/get_croissant_record" -H "Content-Type: application/json" -d '{"doi":"doi:10.7910/DVN/WGCRY7"}'
+```