Merge branch 'main' into add-mcp-use-client

Author: pietrozullo

.github/workflows/main.yml

@@ -11,7 +11,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v2
+      - uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: npm

docs/clients.mdx

@@ -3,6 +3,13 @@ title: "What's New"
 description: 'The latest updates and improvements to MCP'
 ---
 
+<Update label="2025-04-10" description="Java SDK 0.9.0 released">
+- Version [0.9.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.9.0) of the MCP Java SDK has been released.
+- Refactored logging system to use exchange mechanism
+- Custom Context Paths
+- Server Instructions
+- CallToolResult Enhancement   
+</Update>
 <Update label="2025-03-26" description="Kotlin SDK 0.4.0 released">
 - Fix issues and cleanup API
 - Added binary compatibility tracking to avoid breaking changes

docs/development/updates.mdx

@@ -26,7 +26,8 @@
                 ]
               },
               "examples",
-              "clients"
+              "clients",
+              "faqs"
             ]
           },
           {
@@ -174,6 +175,55 @@
               }
             ]
           },
+          {
+            "group": "draft",
+            "pages": [
+              "specification/draft/index",
+              "specification/draft/changelog",
+              "specification/draft/architecture/index",
+              {
+                "group": "Base Protocol",
+                "pages": [
+                  "specification/draft/basic/index",
+                  "specification/draft/basic/lifecycle",
+                  "specification/draft/basic/transports",
+                  "specification/draft/basic/authorization",
+                  {
+                    "group": "Utilities",
+                    "pages": [
+                      "specification/draft/basic/utilities/cancellation",
+                      "specification/draft/basic/utilities/ping",
+                      "specification/draft/basic/utilities/progress"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Client Features",
+                "pages": [
+                  "specification/draft/client/roots",
+                  "specification/draft/client/sampling"
+                ]
+              },
+              {
+                "group": "Server Features",
+                "pages": [
+                  "specification/draft/server/index",
+                  "specification/draft/server/prompts",
+                  "specification/draft/server/resources",
+                  "specification/draft/server/tools",
+                  {
+                    "group": "Utilities",
+                    "pages": [
+                      "specification/draft/server/utilities/completion",
+                      "specification/draft/server/utilities/logging",
+                      "specification/draft/server/utilities/pagination"
+                    ]
+                  }
+                ]
+              }
+            ]
+          },
           {
             "group": "Resources",
             "pages": [

docs/docs.json

@@ -62,9 +62,7 @@ The protocol layer handles message framing, request/response linking, and high-l
             request: RequestT,
             result_type: type[Result]
         ) -> Result:
-            """
-            Send request and wait for response. Raises McpError if response contains error.
-            """
+            """Send request and wait for response. Raises McpError if response contains error."""
             # Request handling implementation
 
         async def send_notification(

docs/docs/concepts/architecture.mdx

@@ -30,6 +30,13 @@ Each tool is defined with the following structure:
   inputSchema: {         // JSON Schema for the tool's parameters
     type: "object",
     properties: { ... }  // Tool-specific parameters
+  },
+  annotations?: {        // Optional hints about tool behavior
+    title?: string;      // Human-readable title for the tool
+    readOnlyHint?: boolean;    // If true, the tool does not modify its environment
+    destructiveHint?: boolean; // If true, the tool may perform destructive updates
+    idempotentHint?: boolean;  // If true, repeated calls with same args have no additional effect
+    openWorldHint?: boolean;   // If true, tool interacts with external entities
   }
 }
 ```
@@ -302,6 +309,162 @@ Here's an example of proper error handling for tools:
 
 This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention.
 
+## Tool annotations
+
+Tool annotations provide additional metadata about a tool's behavior, helping clients understand how to present and manage tools. These annotations are hints that describe the nature and impact of a tool, but should not be relied upon for security decisions.
+
+### Purpose of tool annotations
+
+Tool annotations serve several key purposes:
+
+1. Provide UX-specific information without affecting model context
+2. Help clients categorize and present tools appropriately
+3. Convey information about a tool's potential side effects
+4. Assist in developing intuitive interfaces for tool approval
+
+### Available tool annotations
+
+The MCP specification defines the following annotations for tools:
+
+| Annotation | Type | Default | Description |
+|------------|------|---------|-------------|
+| `title` | string | - | A human-readable title for the tool, useful for UI display |
+| `readOnlyHint` | boolean | false | If true, indicates the tool does not modify its environment |
+| `destructiveHint` | boolean | true | If true, the tool may perform destructive updates (only meaningful when `readOnlyHint` is false) |
+| `idempotentHint` | boolean | false | If true, calling the tool repeatedly with the same arguments has no additional effect (only meaningful when `readOnlyHint` is false) |
+| `openWorldHint` | boolean | true | If true, the tool may interact with an "open world" of external entities |
+
+### Example usage
+
+Here's how to define tools with annotations for different scenarios:
+
+```typescript
+// A read-only search tool
+{
+  name: "web_search",
+  description: "Search the web for information",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: { type: "string" }
+    },
+    required: ["query"]
+  },
+  annotations: {
+    title: "Web Search",
+    readOnlyHint: true,
+    openWorldHint: true
+  }
+}
+
+// A destructive file deletion tool
+{
+  name: "delete_file",
+  description: "Delete a file from the filesystem",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string" }
+    },
+    required: ["path"]
+  },
+  annotations: {
+    title: "Delete File",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false
+  }
+}
+
+// A non-destructive database record creation tool
+{
+  name: "create_record",
+  description: "Create a new record in the database",
+  inputSchema: {
+    type: "object",
+    properties: {
+      table: { type: "string" },
+      data: { type: "object" }
+    },
+    required: ["table", "data"]
+  },
+  annotations: {
+    title: "Create Database Record",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  }
+}
+```
+
+### Integrating annotations in server implementation
+
+<Tabs>
+  <Tab title="TypeScript">
+    ```typescript
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: [{
+          name: "calculate_sum",
+          description: "Add two numbers together",
+          inputSchema: {
+            type: "object",
+            properties: {
+              a: { type: "number" },
+              b: { type: "number" }
+            },
+            required: ["a", "b"]
+          },
+          annotations: {
+            title: "Calculate Sum",
+            readOnlyHint: true,
+            openWorldHint: false
+          }
+        }]
+      };
+    });
+    ```
+  </Tab>
+  <Tab title="Python">
+    ```python
+    from mcp.server.fastmcp import FastMCP
+    
+    mcp = FastMCP("example-server")
+    
+    @mcp.tool(
+        annotations={
+            "title": "Calculate Sum",
+            "readOnlyHint": True,
+            "openWorldHint": False
+        }
+    )
+    async def calculate_sum(a: float, b: float) -> str:
+        """Add two numbers together.
+        
+        Args:
+            a: First number to add
+            b: Second number to add
+        """
+        result = a + b
+        return str(result)
+    ```
+  </Tab>
+</Tabs>
+
+### Best practices for tool annotations
+
+1. **Be accurate about side effects**: Clearly indicate whether a tool modifies its environment and whether those modifications are destructive.
+
+2. **Use descriptive titles**: Provide human-friendly titles that clearly describe the tool's purpose.
+
+3. **Indicate idempotency properly**: Mark tools as idempotent only if repeated calls with the same arguments truly have no additional effect.
+
+4. **Set appropriate open/closed world hints**: Indicate whether a tool interacts with a closed system (like a database) or an open system (like the web).
+
+5. **Remember annotations are hints**: All properties in ToolAnnotations are hints and not guaranteed to provide a faithful description of tool behavior. Clients should never make security-critical decisions based solely on annotations.
+
 ## Testing tools
 
 A comprehensive testing strategy for MCP tools should cover:

docs/docs/concepts/tools.mdx

@@ -46,6 +46,7 @@ These MCP servers are maintained by companies for their platforms:
 - **[E2B](https://github.com/e2b-dev/mcp-server)** - Execute code in secure cloud sandboxes
 - **[Neon](https://github.com/neondatabase/mcp-server-neon)** - Interact with the Neon serverless Postgres platform
 - **[Obsidian Markdown Notes](https://github.com/calclavia/mcp-obsidian)** - Read and search through Markdown notes in Obsidian vaults
+- **[Prisma](https://pris.ly/docs/mcp-server)** - Manage and interact with Prisma Postgres databases
 - **[Qdrant](https://github.com/qdrant/mcp-server-qdrant/)** - Implement semantic memory using the Qdrant vector search engine
 - **[Raygun](https://github.com/MindscapeHQ/mcp-server-raygun)** - Access crash reporting and monitoring data
 - **[Search1API](https://github.com/fatwang2/search1api-mcp)** - Unified API for search, crawling, and sitemaps
@@ -121,6 +122,7 @@ To use an MCP server with Claude, add it to your configuration:
 - [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - Curated list of MCP servers
 - [MCP CLI](https://github.com/wong2/mcp-cli) - Command-line inspector for testing MCP servers
 - [MCP Get](https://mcp-get.com) - Tool for installing and managing MCP servers
+- [Pipedream MCP](https://mcp.pipedream.com) - MCP servers with built-in auth for 3,000+ APIs and 10,000+ tools
 - [Supergateway](https://github.com/supercorp-ai/supergateway) - Run MCP stdio servers over SSE
 - [Zapier MCP](https://zapier.com/mcp) - MCP Server with over 7,000+ apps and 30,000+ actions
 

docs/examples.mdx

@@ -0,0 +1,64 @@
+---
+title: "FAQs"
+description: "Explaining MCP and why it matters in simple terms"
+---
+
+## What is MCP?
+
+MCP (Model Context Protocol) is a standard way for AI applications and agents to connect to and work with your data sources (e.g. local files, databases, or content repositories) and tools (e.g. GitHub, Google Maps, or Puppeteer).
+
+Think of MCP as a universal adapter for AI applications, similar to what USB-C is for physical devices. USB-C acts as a universal adapter to connect devices to various peripherals and accessories. Similarly, MCP provides a standardized way to connect AI applications to different data and tools.
+
+Before USB-C, you needed different cables for different connections. Similarly, before MCP, developers had to build custom connections to each data source or tool they wanted their AI application to work with—a time-consuming process that often resulted in limited functionality. Now, with MCP, developers can easily add connections to their AI applications, making their applications much more powerful from day one.
+
+## Why does MCP matter?
+
+### For AI application users
+
+MCP means your AI applications can access the information and tools you work with every day, making them much more helpful. Rather than AI being limited to what it already knows about, it can now understand your specific documents, data, and work context.
+
+For example, by using MCP servers, applications can access your personal documents from Google Drive or data about your codebase from GitHub, providing more personalized and contextually relevant assistance.
+
+Imagine asking an AI assistant: "Summarize last week's team meeting notes and schedule follow-ups with everyone."
+
+By using connections to data sources powered by MCP, the AI assistant can:
+
+- Connect to your Google Drive through an MCP server to read meeting notes
+- Understand who needs follow-ups based on the notes
+- Connect to your calendar through another MCP server to schedule the meetings automatically
+
+### For developers
+
+MCP reduces development time and complexity when building AI applications that need to access various data sources. With MCP, developers can focus on building great AI experiences rather than repeatedly creating custom connectors.
+
+Traditionally, connecting applications with data sources required building custom, one-off connections for each data source and each application. This created significant duplicative work—every developer wanting to connect their AI application to Google Drive or Slack needed to build their own connection.
+
+MCP simplifies this by enabling developers to build MCP servers for data sources that are then reusable by various applications. For example, using the open source Google Drive MCP server, many different applications can access data from Google Drive without each developer needing to build a custom connection.
+
+This open source ecosystem of MCP servers means developers can leverage existing work rather than starting from scratch, making it easier to build powerful AI applications that seamlessly integrate with the tools and data sources their users already rely on.
+
+## How does MCP work?
+
+<Frame>
+  <img src="/images/mcp-simple-diagram.png" />
+</Frame>
+
+MCP creates a bridge between your AI applications and your data through a straightforward system: 
+
+- **MCP servers** connect to your data sources and tools (like Google Drive or Slack)
+- **MCP clients** are run by AI applications (like Claude Desktop) to connect them to these servers
+- When you give permission, your AI application discovers available MCP servers
+- The AI model can then use these connections to read information and take actions
+
+This modular system means new capabilities can be added without changing AI applications themselves—just like adding new accessories to your computer without upgrading your entire system.
+
+## Who creates and maintains MCP servers?
+
+MCP servers are developed and maintained by: 
+
+- Developers at Anthropic who build servers for common tools and data sources 
+- Open source contributors who create servers for tools they use 
+- Enterprise development teams building servers for their internal systems 
+- Software providers making their applications AI-ready 
+
+Once an open source MCP server is created for a data source, it can be used by any MCP-compatible AI application, creating a growing ecosystem of connections. See our [list of example servers](https://modelcontextprotocol.io/examples), or [get started building your own server](https://modelcontextprotocol.io/quickstart/server).