docs: add more MCP integration examples (#441) (#754)

docs/mcp_integrations.md

@@ -1,15 +1,28 @@
-# MCP Integrations（Beta）
+# MCP Integrations (Beta)
 
-Now This feature is diabled by default. You can enable it by setting the environment ENABLE_MCP_SERVER_CONFIGURATION to be true
+This feature is disabled by default. You can enable it by setting the environment variable `ENABLE_MCP_SERVER_CONFIGURATION=true`.
 
 > [!WARNING]
-> Please enable this feature before securing your frond-end and back-end in a managed environment.
-> Otherwise, you system could be compromised.
+> Please enable this feature only after securing your front-end and back-end in a managed environment.
+> Otherwise, your system could be compromised.
 
-This feature is diabled by default. You can enable it by setting the environment ENABLE_MCP_SERVER_CONFIGURATION
-Please enable this feature before securing your frond-end and back-end in an internal environment.q
+## Enabling MCP
 
-## Example of MCP Server Configuration
+Set the following environment variable in your `.env` file:
+
+```bash
+ENABLE_MCP_SERVER_CONFIGURATION=true
+```
+
+Then restart the DeerFlow server.
+
+---
+
+## MCP Server Examples
+
+### 1. GitHub Trending
+
+Fetches trending repositories from GitHub.
 
 ```json
 {
@@ -17,27 +30,147 @@ Please enable this feature before securing your frond-end and back-end in an int
     "mcp-github-trending": {
       "transport": "stdio",
       "command": "uvx",
+      "args": ["mcp-github-trending"]
+    }
+  }
+}
+```
+
+**Available Tools:**
+- `get_github_trending_repositories` - Get trending repositories by language and time range
+
+---
+
+### 2. Filesystem Access
+
+Provides secure file system access with configurable allowed directories.
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "transport": "stdio",
+      "command": "npx",
       "args": [
-          "mcp-github-trending"
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/path/to/allowed/directory"
       ]
     }
   }
 }
 ```
 
+**Available Tools:**
+- `read_text_file` - Read contents of a text file
+- `read_multiple_files` - Read multiple files at once
+- `write_file` - Write content to a file
+- `edit_file` - Edit a file with line-based replacements
+- `create_directory` - Create a new directory
+- `list_directory` - List files and directories
+- `directory_tree` - Get a recursive tree view
+- `move_file` - Move or rename files
+- `search_files` - Search for files by pattern
+- `get_file_info` - Get file metadata
+
+---
+
+### 3. Brave Search
+
+Web search using Brave Search API.
+
+**Prerequisites:** Get API key from [Brave Search API](https://brave.com/search/api/)
+
+```json
+{
+  "mcpServers": {
+    "brave-search": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "your-brave-api-key"
+      }
+    }
+  }
+}
+```
+
+**Available Tools:**
+- `brave_web_search` - Perform web searches
+- `brave_local_search` - Search for local businesses and places
+
+---
+
+### 4. Tavily Search
+
+AI-optimized search engine for research tasks.
+
+**Prerequisites:** Get API key from [Tavily](https://tavily.com/)
+
+```json
+{
+  "mcpServers": {
+    "tavily": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "tavily-mcp"],
+      "env": {
+        "TAVILY_API_KEY": "tvly-your-api-key"
+      }
+    }
+  }
+}
+```
+
+**Available Tools:**
+- `tavily-search` - Perform AI-optimized web search
+- `tavily-extract` - Extract content from web pages
+
+---
+
+## Adding MCP Tools to Agents
+
+When using MCP tools in DeerFlow, you need to specify:
+
+1. **`enabled_tools`** - Which tools from the MCP server to enable
+2. **`add_to_agents`** - Which DeerFlow agents can use these tools (`researcher`, `coder`, or both)
+
+### Example: Full Configuration for Chat API
+
+```json
+{
+  "messages": [{"role": "user", "content": "Research the top GitHub trends"}],
+  "mcp_settings": {
+    "servers": {
+      "github-trending": {
+        "transport": "stdio",
+        "command": "uvx",
+        "args": ["mcp-github-trending"],
+        "enabled_tools": ["get_github_trending_repositories"],
+        "add_to_agents": ["researcher"]
+      }
+    }
+  }
+}
+```
+
+---
+
 ## APIs
 
-### Get metadata of MCP Server
+### Get MCP Server Metadata
 
 **POST /api/mcp/server/metadata**
 
+Use this endpoint to discover available tools from an MCP server.
+
 For `stdio` type:
 ```json
 {
   "transport": "stdio",
   "command": "npx",
-  "args": ["-y", "tavily-mcp@0.1.3"],
-  "env": {"TAVILY_API_KEY":  "tvly-dev-xxx"}
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
 }
 ```
 
@@ -47,7 +180,7 @@ For `sse` type:
   "transport": "sse",
   "url": "http://localhost:3000/sse",
   "headers": {
-    "API_KEY": "value"
+    "Authorization": "Bearer your-token"
   }
 }
 ```
@@ -58,31 +191,39 @@ For `streamable_http` type:
   "transport": "streamable_http",
   "url": "http://localhost:3000/mcp",
   "headers": {
-    "API_KEY": "value"
+    "API_KEY": "your-api-key"
   }
 }
 ```
 
-### Chat Stream
+### Chat Stream with MCP
 
 **POST /api/chat/stream**
 
 ```json
 {
-  ...
+  "messages": [{"role": "user", "content": "Your research query"}],
+  "thread_id": "unique-thread-id",
   "mcp_settings": {
     "servers": {
-      "mcp-github-trending": {
+      "your-mcp-server": {
         "transport": "stdio",
         "command": "uvx",
-        "args": ["mcp-github-trending"],
+        "args": ["your-mcp-package"],
         "env": {
-          "MCP_SERVER_ID": "mcp-github-trending"
+          "API_KEY": "your-api-key"
         },
-        "enabled_tools": ["get_github_trending_repositories"],
+        "enabled_tools": ["tool1", "tool2"],
         "add_to_agents": ["researcher"]
       }
     }
-  },
+  }
 }
 ```
+
+---
+
+## Additional Resources
+
+- [MCP Official Documentation](https://modelcontextprotocol.io/)
+- [MCP Server Registry](https://github.com/modelcontextprotocol/servers)