chore(config): ignore local mcp.json and add example template

.gitignore

@@ -43,6 +43,7 @@ Thumbs.db
 
 # Config (contains API keys)
 config.yaml
+mcp.json
 
 # test file
 demo.py
@@ -58,4 +59,4 @@ docs/assets/preview.html
 
 claude.md
 
-.agent_memory.json
+.agent_memory.json

README.md

@@ -118,6 +118,10 @@ api_base: "https://api.minimax.io"  # Global
 model: "MiniMax-M2"
 ```
 
+(Optional) MCP tools (web search, memory):
+- The setup script also downloads a template `mcp.json` to `~/.mini-agent/config/mcp.json`.
+- Edit it to enable servers and add API keys, or leave it disabled to run without MCP tools.
+
 **Start Using:**
 
 ```bash
@@ -176,6 +180,11 @@ Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml
 vim mini_agent/config/config.yaml  # Or use your preferred editor
 ```
 
+(Optional) Configure MCP tools:
+- Copy `mini_agent/config/mcp-example.json` to `mini_agent/config/mcp.json` (this file is gitignored).
+- Edit `mini_agent/config/mcp.json` to enable MCP servers and set API keys.
+- If you skip this, Mini Agent still runs but without MCP tools.
+
 Fill in your API Key and corresponding API Base:
 
 ```yaml

README_CN.md

@@ -118,6 +118,10 @@ api_base: "https://api.minimaxi.com"  # 国内版
 model: "MiniMax-M2"
 ```
 
+（可选）MCP 工具（网页搜索、记忆等）配置：
+- 配置脚本也会下载一个模板 `mcp.json` 到 `~/.mini-agent/config/mcp.json`。
+- 如需启用 MCP 服务器，请编辑该文件并填写 API Key；不配置也可正常运行（仅不加载 MCP 工具）。
+
 **开始使用：**
 
 ```bash
@@ -176,6 +180,11 @@ Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml
 vim mini_agent/config/config.yaml  # 或使用您偏好的编辑器
 ```
 
+（可选）配置 MCP 工具：
+- 将 `mini_agent/config/mcp-example.json` 复制为 `mini_agent/config/mcp.json`（该文件已加入 gitignore）。
+- 编辑 `mini_agent/config/mcp.json`，启用需要的 MCP 服务器并填写 API Key。
+- 不配置也可运行，但不会加载 MCP 工具。
+
 填入您的 API Key 和对应的 API Base：
 
 ```yaml

examples/04_full_agent.py

@@ -90,12 +90,12 @@ async def demo_full_agent():
 
         # Load MCP tools (if configured)
         try:
-            mcp_tools = await load_mcp_tools_async(config_path="mini_agent/config/mcp.json")
+            mcp_tools = await load_mcp_tools_async(config_path="mini_agent/config/mcp-example.json")
             if mcp_tools:
                 tools.extend(mcp_tools)
                 print(f"✓ Loaded {len(mcp_tools)} MCP tools")
             else:
-                print("⚠️  No MCP tools configured (mcp.json is empty or disabled)")
+                print("⚠️  No MCP tools configured (config is empty or disabled)")
         except Exception as e:
             print(f"⚠️  MCP tools not loaded: {e}")
 

mini_agent/config/mcp.json → mini_agent/config/mcp-example.json

@@ -26,4 +26,4 @@
       "disabled": true
     }
   }
-}
+}

scripts/setup-config.ps1

@@ -63,9 +63,9 @@ try {
     Write-ColorOutput "   ✗ Failed to download: config.yaml" -Color "Red"
 }
 
-# Download mcp.json (optional)
+# Download mcp.json (optional, from example template)
 try {
-    $mcpUrl = "$GITHUB_RAW_URL/mcp.json"
+    $mcpUrl = "$GITHUB_RAW_URL/mcp-example.json"
     $mcpPath = Join-Path $CONFIG_DIR "mcp.json"
     Invoke-WebRequest -Uri $mcpUrl -OutFile $mcpPath -UseBasicParsing
     Write-ColorOutput "   ✓ Downloaded: mcp.json" -Color "Green"

scripts/setup-config.sh

@@ -48,8 +48,8 @@ else
     echo -e "${RED}   ✗ Failed to download: config.yaml${NC}"
 fi
 
-# Download mcp.json (optional)
-if curl -fsSL "$GITHUB_RAW_URL/mcp.json" -o "$CONFIG_DIR/mcp.json" 2>/dev/null; then
+# Download mcp.json (optional, from example template)
+if curl -fsSL "$GITHUB_RAW_URL/mcp-example.json" -o "$CONFIG_DIR/mcp.json" 2>/dev/null; then
     echo -e "${GREEN}   ✓ Downloaded: mcp.json${NC}"
     FILES_COPIED=$((FILES_COPIED + 1))
 fi

tests/test_integration.py

@@ -72,16 +72,16 @@ async def test_basic_agent_usage():
 
         # Load MCP tools (optional) - with timeout protection
         try:
-            # MCP tools are disabled by default to prevent test hangs
-            # Enable specific MCP servers in mcp.json if needed
+            # MCP tools are disabled by default to prevent test hangs.
+            # To enable, copy mcp-example.json to mcp.json and edit it.
             mcp_tools = await load_mcp_tools_async(
-                config_path="mini_agent/config/mcp.json"
+                config_path="mini_agent/config/mcp-example.json"
             )
             if mcp_tools:
                 print(f"✓ Loaded {len(mcp_tools)} MCP tools")
                 tools.extend(mcp_tools)
             else:
-                print("⚠️  No MCP tools configured (mcp.json is empty)")
+                print("⚠️  No MCP tools configured (config is empty or disabled)")
         except Exception as e:
             print(f"⚠️  MCP tools not loaded: {e}")
 

tests/test_mcp.py

@@ -12,7 +12,7 @@
 @pytest.fixture(scope="module")
 def mcp_config():
     """Read MCP configuration."""
-    mcp_config_path = Path("mini_agent/config/mcp.json")
+    mcp_config_path = Path("mini_agent/config/mcp-example.json")
     with open(mcp_config_path, encoding="utf-8") as f:
         return json.load(f)
 
@@ -24,7 +24,7 @@ async def test_mcp_tools_loading():
 
     try:
         # Load MCP tools
-        tools = await load_mcp_tools_async("mini_agent/config/mcp.json")
+        tools = await load_mcp_tools_async("mini_agent/config/mcp-example.json")
 
         print(f"Loaded {len(tools)} MCP tools")
 
@@ -56,7 +56,7 @@ async def test_git_mcp_loading(mcp_config):
 
     try:
         # Load MCP tools
-        tools = await load_mcp_tools_async("mini_agent/config/mcp.json")
+        tools = await load_mcp_tools_async("mini_agent/config/mcp-example.json")
 
         print("\n✅ Loaded successfully!")
         print("\n📊 Statistics:")
@@ -111,7 +111,7 @@ async def test_git_mcp_tool_availability():
     print("\n=== Testing Git MCP Tool Availability ===")
 
     try:
-        tools = await load_mcp_tools_async("mini_agent/config/mcp.json")
+        tools = await load_mcp_tools_async("mini_agent/config/mcp-example.json")
 
         if not tools:
             pytest.skip("No MCP tools loaded")
@@ -137,7 +137,7 @@ async def test_mcp_tool_execution():
     print("\n=== Testing MCP Tool Execution ===")
 
     try:
-        tools = await load_mcp_tools_async("mini_agent/config/mcp.json")
+        tools = await load_mcp_tools_async("mini_agent/config/mcp-example.json")
 
         if not tools:
             print("⚠️  No MCP tools loaded, skipping execution test")
@@ -180,7 +180,7 @@ async def main():
     print("=" * 80)
     print("Running MCP Integration Tests")
     print("=" * 80)
-    print("\nNote: These tests require Node.js and will use MCP servers defined in mcp.json")
+    print("\nNote: These tests require Node.js and will use MCP servers defined in mcp-example.json or your local mcp.json")
     print("Tests will pass even if MCP is not configured.\n")
 
     await test_mcp_tools_loading()