Merge branch 'main' into patch-1

Author: anshulsharmas

.github/workflows/release.yml

@@ -212,10 +212,3 @@ jobs:
             --title "Release $VERSION" \
             --notes-file RELEASE_NOTES.md
 
-      - name: Docker MCP images
-        uses: peter-evans/repository-dispatch@v3
-        with:
-          token: ${{ secrets.DOCKER_TOKEN }}
-          repository: docker/labs-ai-tools-for-devs
-          event-type: build-mcp-images
-          client-payload: '{"ref": "${{ needs.create-metadata.outputs.version }}"}'

.vscode/settings.json

@@ -0,0 +1 @@
+{}

README.md

@@ -72,6 +72,14 @@ This MCP server attempts to exercise all the features of the MCP protocol. It is
      - Embedded resource with `type: "resource"`
      - Text instruction for using the resource URI
 
+9. `startElicitation`
+   - Initiates an elicitation (interaction) within the MCP client.
+   - Inputs:
+      - `color` (string): Favorite color
+      - `number` (number, 1-100): Favorite number
+      - `pets` (enum): Favorite pet
+   - Returns: Confirmation of the elicitation demo with selection summary.
+
 ### Resources
 
 The server provides 100 test resources in two formats:

src/everything/README.md

@@ -86,6 +86,17 @@ const GetResourceReferenceSchema = z.object({
     .describe("ID of the resource to reference (1-100)"),
 });
 
+const ElicitationSchema = z.object({});
+
+const GetResourceLinksSchema = z.object({
+  count: z
+    .number()
+    .min(1)
+    .max(10)
+    .default(3)
+    .describe("Number of resource links to return (1-10)"),
+});
+
 enum ToolName {
   ECHO = "echo",
   ADD = "add",
@@ -95,6 +106,8 @@ enum ToolName {
   GET_TINY_IMAGE = "getTinyImage",
   ANNOTATED_MESSAGE = "annotatedMessage",
   GET_RESOURCE_REFERENCE = "getResourceReference",
+  ELICITATION = "startElicitation",
+  GET_RESOURCE_LINKS = "getResourceLinks",
 }
 
 enum PromptName {
@@ -116,6 +129,7 @@ export const createServer = () => {
         tools: {},
         logging: {},
         completions: {},
+        elicitation: {},
       },
       instructions
     }
@@ -206,6 +220,21 @@ export const createServer = () => {
     return await server.request(request, CreateMessageResultSchema);
   };
 
+  const requestElicitation = async (
+    message: string,
+    requestedSchema: any
+  ) => {
+    const request = {
+      method: 'elicitation/create',
+      params: {
+        message,
+        requestedSchema
+      }
+    };
+
+    return await server.request(request, z.any());
+  };
+
   const ALL_RESOURCES: Resource[] = Array.from({ length: 100 }, (_, i) => {
     const uri = `test://static/resource/${i + 1}`;
     if (i % 2 === 0) {
@@ -459,6 +488,17 @@ export const createServer = () => {
           "Returns a resource reference that can be used by MCP clients",
         inputSchema: zodToJsonSchema(GetResourceReferenceSchema) as ToolInput,
       },
+      {
+        name: ToolName.ELICITATION,
+        description: "Demonstrates the Elicitation feature by asking the user to provide information about their favorite color, number, and pets.",
+        inputSchema: zodToJsonSchema(ElicitationSchema) as ToolInput,
+      },
+      {
+        name: ToolName.GET_RESOURCE_LINKS,
+        description:
+          "Returns multiple resource links that reference different types of resources",
+        inputSchema: zodToJsonSchema(GetResourceLinksSchema) as ToolInput,
+      },
     ];
 
     return { tools };
@@ -648,6 +688,91 @@ export const createServer = () => {
       return { content };
     }
 
+    if (name === ToolName.ELICITATION) {
+      ElicitationSchema.parse(args);
+
+      const elicitationResult = await requestElicitation(
+        'What are your favorite things?',
+        {
+          type: 'object',
+          properties: {
+            color: { type: 'string', description: 'Favorite color' },
+            number: { type: 'integer', description: 'Favorite number', minimum: 1, maximum: 100 },
+            pets: { 
+              type: 'string', 
+              enum: ['cats', 'dogs', 'birds', 'fish', 'reptiles'], 
+              description: 'Favorite pets' 
+            },
+          }
+        }
+      );
+
+      // Handle different response actions
+      const content = [];
+      
+      if (elicitationResult.action === 'accept' && elicitationResult.content) {
+        content.push({
+          type: "text",
+          text: `✅ User provided their favorite things!`,
+        });
+        
+        // Only access elicitationResult.content when action is accept
+        const { color, number, pets } = elicitationResult.content;
+        content.push({
+          type: "text",
+          text: `Their favorites are:\n- Color: ${color || 'not specified'}\n- Number: ${number || 'not specified'}\n- Pets: ${pets || 'not specified'}`,
+        });
+      } else if (elicitationResult.action === 'decline') {
+        content.push({
+          type: "text",
+          text: `❌ User declined to provide their favorite things.`,
+        });
+      } else if (elicitationResult.action === 'cancel') {
+        content.push({
+          type: "text",
+          text: `⚠️ User cancelled the elicitation dialog.`,
+        });
+      }
+      
+      // Include raw result for debugging
+      content.push({
+        type: "text",
+        text: `\nRaw result: ${JSON.stringify(elicitationResult, null, 2)}`,
+      });
+
+      return { content };
+    }
+    
+    if (name === ToolName.GET_RESOURCE_LINKS) {
+      const { count } = GetResourceLinksSchema.parse(args);
+      const content = [];
+
+      // Add intro text
+      content.push({
+        type: "text",
+        text: `Here are ${count} resource links to resources available in this server (see full output in tool response if your client does not support resource_link yet):`,
+      });
+
+      // Return resource links to actual resources from ALL_RESOURCES
+      const actualCount = Math.min(count, ALL_RESOURCES.length);
+      for (let i = 0; i < actualCount; i++) {
+        const resource = ALL_RESOURCES[i];
+        content.push({
+          type: "resource_link",
+          uri: resource.uri,
+          name: resource.name,
+          description: `Resource ${i + 1}: ${
+            resource.mimeType === "text/plain"
+              ? "plaintext resource"
+              : "binary blob resource"
+          }`,
+          mimeType: resource.mimeType,
+        });
+      }
+
+      return { content };
+    }
+
     throw new Error(`Unknown tool: ${name}`);
   });
 

src/everything/everything.ts

@@ -9,8 +9,58 @@ Node.js server implementing Model Context Protocol (MCP) for filesystem operatio
 - Move files/directories
 - Search files
 - Get file metadata
+- Dynamic directory access control via [Roots](https://modelcontextprotocol.io/docs/concepts/roots)
+
+## Directory Access Control
+
+The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via [Roots](https://modelcontextprotocol.io/docs/concepts/roots).
+
+### Method 1: Command-line Arguments
+Specify Allowed directories when starting the server:
+```bash
+mcp-server-filesystem /path/to/dir1 /path/to/dir2
+```
+
+### Method 2: MCP Roots (Recommended)
+MCP clients that support [Roots](https://modelcontextprotocol.io/docs/concepts/roots) can dynamically update the Allowed directories. 
+
+Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
+
+**Important**: If server starts without command-line arguments AND client doesn't support roots protocol (or provides empty roots), the server will throw an error during initialization.
+
+This is the recommended method, as this enables runtime directory updates via `roots/list_changed` notifications without server restart, providing a more flexible and modern integration experience.
+
+### How It Works
+
+The server's directory access control follows this flow:
+
+1. **Server Startup**
+   - Server starts with directories from command-line arguments (if provided)
+   - If no arguments provided, server starts with empty allowed directories
+
+2. **Client Connection & Initialization**
+   - Client connects and sends `initialize` request with capabilities
+   - Server checks if client supports roots protocol (`capabilities.roots`)
+   
+3. **Roots Protocol Handling** (if client supports roots)
+   - **On initialization**: Server requests roots from client via `roots/list`
+   - Client responds with its configured roots
+   - Server replaces ALL allowed directories with client's roots
+   - **On runtime updates**: Client can send `notifications/roots/list_changed`
+   - Server requests updated roots and replaces allowed directories again
+
+4. **Fallback Behavior** (if client doesn't support roots)
+   - Server continues using command-line directories only
+   - No dynamic updates possible
+
+5. **Access Control**
+   - All filesystem operations are restricted to allowed directories
+   - Use `list_allowed_directories` tool to see current directories
+   - Server requires at least ONE allowed directory to operate
+
+**Note**: The server will only allow operations within directories specified either via `args` or via Roots.
+
 
-**Note**: The server will only allow operations within directories specified via `args`.
 
 ## API
 

src/filesystem/README.md

@@ -0,0 +1,84 @@
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import { getValidRootDirectories } from '../roots-utils.js';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, realpathSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import type { Root } from '@modelcontextprotocol/sdk/types.js';
+
+describe('getValidRootDirectories', () => {
+  let testDir1: string;
+  let testDir2: string;
+  let testDir3: string;
+  let testFile: string;
+
+  beforeEach(() => {
+    // Create test directories
+    testDir1 = realpathSync(mkdtempSync(join(tmpdir(), 'mcp-roots-test1-')));
+    testDir2 = realpathSync(mkdtempSync(join(tmpdir(), 'mcp-roots-test2-')));
+    testDir3 = realpathSync(mkdtempSync(join(tmpdir(), 'mcp-roots-test3-')));
+
+    // Create a test file (not a directory)
+    testFile = join(testDir1, 'test-file.txt');
+    writeFileSync(testFile, 'test content');
+  });
+
+  afterEach(() => {
+    // Cleanup
+    rmSync(testDir1, { recursive: true, force: true });
+    rmSync(testDir2, { recursive: true, force: true });
+    rmSync(testDir3, { recursive: true, force: true });
+  });
+
+  describe('valid directory processing', () => {
+    it('should process all URI formats and edge cases', async () => {
+      const roots = [
+        { uri: `file://${testDir1}`, name: 'File URI' },
+        { uri: testDir2, name: 'Plain path' },
+        { uri: testDir3 } // Plain path without name property
+      ];
+
+      const result = await getValidRootDirectories(roots);
+
+      expect(result).toContain(testDir1);
+      expect(result).toContain(testDir2);
+      expect(result).toContain(testDir3);
+      expect(result).toHaveLength(3);
+    });
+
+    it('should normalize complex paths', async () => {
+      const subDir = join(testDir1, 'subdir');
+      mkdirSync(subDir);
+      
+      const roots = [
+        { uri: `file://${testDir1}/./subdir/../subdir`, name: 'Complex Path' }
+      ];
+
+      const result = await getValidRootDirectories(roots);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toBe(subDir);
+    });
+  });
+
+  describe('error handling', () => {
+
+    it('should handle various error types', async () => {
+      const nonExistentDir = join(tmpdir(), 'non-existent-directory-12345');
+      const invalidPath = '\0invalid\0path'; // Null bytes cause different error types
+      const roots = [
+        { uri: `file://${testDir1}`, name: 'Valid Dir' },
+        { uri: `file://${nonExistentDir}`, name: 'Non-existent Dir' },
+        { uri: `file://${testFile}`, name: 'File Not Dir' },
+        { uri: `file://${invalidPath}`, name: 'Invalid Path' }
+      ];
+
+      const result = await getValidRootDirectories(roots);
+
+      expect(result).toContain(testDir1);
+      expect(result).not.toContain(nonExistentDir);
+      expect(result).not.toContain(testFile);
+      expect(result).not.toContain(invalidPath);
+      expect(result).toHaveLength(1);
+    });
+  });
+});