✨ feat(common): integrate DeepWiki MCP tools with dynamic tool loading

- Add enable_deepwiki flag to Context with env var support and default qwen-turbo model
- Implement MCP client management and tool retrieval for DeepWiki MCP server
- Dynamically load DeepWiki tools in common.tools.get_tools if enabled in context
- Modify agent graph to use dynamic tools node executing tools based on current config
- Update Makefile test target to run unit and integration tests
- Add langchain-mcp-adapters dependency to pyproject.toml
- Refactor test fixtures and e2e tests to cover DeepWiki MCP tool usage strictly
- Improve test react agent suite for tool usage, streaming, and context persistence

Author: webup

Makefile

@@ -7,9 +7,8 @@ all: help
 # TESTING
 ######################
 
-# Legacy test command (defaults to unit tests for backward compatibility)
-test:
-	python -m pytest tests/unit_tests/
+# Legacy test command (defaults to unit and integration tests for backward compatibility)
+test: test_unit test_integration
 
 # Specific test targets
 test_unit:

pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "python-dotenv>=1.0.1",
     "langchain-tavily>=0.1",
     "langchain-qwq>=0.2.1",
+    "langchain-mcp-adapters>=0.1.9",
 ]
 
 

src/common/__init__.py

@@ -3,14 +3,13 @@
 from . import prompts
 from .context import Context
 from .models import create_qwen_model, get_supported_qwen_models
-from .tools import TOOLS, web_search
+from .tools import web_search
 from .utils import load_chat_model
 
 __all__ = [
     "Context",
     "create_qwen_model",
     "get_supported_qwen_models",
-    "TOOLS",
     "web_search",
     "load_chat_model",
     "prompts",

src/common/context.py

@@ -2,8 +2,7 @@
 
 from __future__ import annotations
 
-import os
-from dataclasses import dataclass, field, fields
+from dataclasses import dataclass, field
 from typing import Annotated
 
 from . import prompts
@@ -22,7 +21,7 @@ class Context:
     )
 
     model: Annotated[str, {"__template_metadata__": {"kind": "llm"}}] = field(
-        default="qwen:qwen-plus",
+        default="qwen:qwen-turbo",
         metadata={
             "description": "The name of the language model to use for the agent's main interactions. "
             "Should be in the form: provider:model-name."
@@ -36,11 +35,33 @@ class Context:
         },
     )
 
+    enable_deepwiki: bool = field(
+        default=False,
+        metadata={
+            "description": "Whether to enable the DeepWiki MCP tool for accessing open source project documentation."
+        },
+    )
+
     def __post_init__(self) -> None:
         """Fetch env vars for attributes that were not passed as args."""
+        import os
+        from dataclasses import fields
+
         for f in fields(self):
             if not f.init:
                 continue
 
-            if getattr(self, f.name) == f.default:
-                setattr(self, f.name, os.environ.get(f.name.upper(), f.default))
+            current_value = getattr(self, f.name)
+            default_value = f.default
+            env_var_name = f.name.upper()
+            env_value = os.environ.get(env_var_name)
+
+            # Only override with environment variable if current value equals default
+            # This preserves explicit configuration from LangGraph configurable
+            if current_value == default_value and env_value is not None:
+                if isinstance(default_value, bool):
+                    # Handle boolean environment variables
+                    env_bool_value = env_value.lower() in ("true", "1", "yes", "on")
+                    setattr(self, f.name, env_bool_value)
+                else:
+                    setattr(self, f.name, env_value)

src/common/mcp.py

@@ -0,0 +1,99 @@
+"""MCP Client setup and management for LangGraph ReAct Agent."""
+
+import logging
+from typing import Any, Callable, Dict, List, Optional, cast
+
+from langchain_mcp_adapters.client import (  # type: ignore[import-untyped]
+    MultiServerMCPClient,
+)
+
+logger = logging.getLogger(__name__)
+
+# Global MCP client and tools cache
+_mcp_client: Optional[MultiServerMCPClient] = None
+_mcp_tools_cache: Dict[str, List[Callable[..., Any]]] = {}
+
+# MCP Server configurations
+MCP_SERVERS = {
+    "deepwiki": {
+        "url": "https://mcp.deepwiki.com/mcp",
+        "transport": "streamable_http",
+    },
+    # Add more MCP servers here as needed
+    # "context7": {
+    #     "url": "https://mcp.context7.com/sse",
+    #     "transport": "sse",
+    # },
+}
+
+
+async def get_mcp_client(
+    server_configs: Optional[Dict[str, Any]] = None,
+) -> Optional[MultiServerMCPClient]:
+    """Get or initialize the global MCP client with given server configurations."""
+    global _mcp_client
+
+    if _mcp_client is None:
+        configs = server_configs or MCP_SERVERS
+        try:
+            _mcp_client = MultiServerMCPClient(configs)  # pyright: ignore[reportArgumentType]
+            logger.info(f"Initialized MCP client with servers: {list(configs.keys())}")
+        except Exception as e:
+            logger.error("Failed to initialize MCP client: %s", e)
+            return None
+    return _mcp_client
+
+
+async def get_mcp_tools(server_name: str) -> List[Callable[..., Any]]:
+    """Get MCP tools for a specific server, initializing client if needed."""
+    global _mcp_tools_cache
+
+    # Return cached tools if available
+    if server_name in _mcp_tools_cache:
+        return _mcp_tools_cache[server_name]
+
+    try:
+        client = await get_mcp_client()
+        if client is None:
+            _mcp_tools_cache[server_name] = []
+            return []
+
+        # Get all tools and filter by server (if tools have server metadata)
+        all_tools = await client.get_tools()
+        tools = cast(List[Callable[..., Any]], all_tools)
+
+        _mcp_tools_cache[server_name] = tools
+        logger.info(f"Loaded {len(tools)} tools from MCP server '{server_name}'")
+        return tools
+    except Exception as e:
+        logger.warning(f"Failed to load tools from MCP server '{server_name}': %s", e)
+        _mcp_tools_cache[server_name] = []
+        return []
+
+
+async def get_deepwiki_tools() -> List[Callable[..., Any]]:
+    """Get DeepWiki MCP tools."""
+    return await get_mcp_tools("deepwiki")
+
+
+async def get_all_mcp_tools() -> List[Callable[..., Any]]:
+    """Get all tools from all configured MCP servers."""
+    all_tools = []
+    for server_name in MCP_SERVERS.keys():
+        tools = await get_mcp_tools(server_name)
+        all_tools.extend(tools)
+    return all_tools
+
+
+def add_mcp_server(name: str, config: Dict[str, Any]) -> None:
+    """Add a new MCP server configuration."""
+    MCP_SERVERS[name] = config
+    # Clear client to force reinitialization with new config
+    clear_mcp_cache()
+
+
+def clear_mcp_cache() -> None:
+    """Clear the MCP client and tools cache (useful for testing)."""
+    global _mcp_client, _mcp_tools_cache
+    _mcp_client = None
+    _mcp_tools_cache = {}

src/common/tools.py

@@ -6,12 +6,16 @@
 consider implementing more robust and specialized tools tailored to your needs.
 """
 
+import logging
 from typing import Any, Callable, List, Optional, cast
 
 from langchain_tavily import TavilySearch
 from langgraph.runtime import get_runtime
 
 from common.context import Context
+from common.mcp import get_deepwiki_tools
+
+logger = logging.getLogger(__name__)
 
 
 async def web_search(query: str) -> Optional[dict[str, Any]]:
@@ -26,4 +30,15 @@ async def web_search(query: str) -> Optional[dict[str, Any]]:
     return cast(dict[str, Any], await wrapped.ainvoke({"query": query}))
 
 
-TOOLS: List[Callable[..., Any]] = [web_search]
+async def get_tools() -> List[Callable[..., Any]]:
+    """Get all available tools based on configuration."""
+    tools = [web_search]
+
+    runtime = get_runtime(Context)
+
+    if runtime.context.enable_deepwiki:
+        deepwiki_tools = await get_deepwiki_tools()
+        tools.extend(deepwiki_tools)
+        logger.info(f"Loaded {len(deepwiki_tools)} deepwiki tools")
+
+    return tools

src/react_agent/graph.py

@@ -6,13 +6,13 @@
 from datetime import UTC, datetime
 from typing import Dict, List, Literal, cast
 
-from langchain_core.messages import AIMessage
+from langchain_core.messages import AIMessage, ToolMessage
 from langgraph.graph import StateGraph
 from langgraph.prebuilt import ToolNode
 from langgraph.runtime import Runtime
 
 from common.context import Context
-from common.tools import TOOLS
+from common.tools import get_tools
 from common.utils import load_chat_model
 from react_agent.state import InputState, State
 
@@ -33,8 +33,11 @@ async def call_model(
     Returns:
         dict: A dictionary containing the model's response message.
     """
+    # Get available tools based on configuration
+    available_tools = await get_tools()
+
     # Initialize the model with tool binding. Change the model or add more tools here.
-    model = load_chat_model(runtime.context.model).bind_tools(TOOLS)
+    model = load_chat_model(runtime.context.model).bind_tools(available_tools)
 
     # Format the system prompt. Customize this to change the agent's behavior.
     system_message = runtime.context.system_prompt.format(
@@ -64,13 +67,33 @@ async def call_model(
     return {"messages": [response]}
 
 
+async def dynamic_tools_node(
+    state: State, runtime: Runtime[Context]
+) -> Dict[str, List[ToolMessage]]:
+    """Execute tools dynamically based on configuration.
+
+    This function gets the available tools based on the current configuration
+    and executes the requested tool calls from the last message.
+    """
+    # Get available tools based on configuration
+    available_tools = await get_tools()
+
+    # Create a ToolNode with the available tools
+    tool_node = ToolNode(available_tools)
+
+    # Execute the tool node
+    result = await tool_node.ainvoke(state)
+
+    return cast(Dict[str, List[ToolMessage]], result)
+
+
 # Define a new graph
 
 builder = StateGraph(State, input_schema=InputState, context_schema=Context)
 
 # Define the two nodes we will cycle between
 builder.add_node(call_model)
-builder.add_node("tools", ToolNode(TOOLS))
+builder.add_node("tools", dynamic_tools_node)
 
 # Set the entrypoint as `call_model`
 # This means that this node is the first one called

tests/conftest.py

@@ -2,15 +2,12 @@
 
 import os
 from pathlib import Path
-from unittest.mock import AsyncMock, Mock
 
 import pytest
 from dotenv import load_dotenv
-from langchain_core.messages import AIMessage, HumanMessage
+from langchain_core.messages import HumanMessage
 from langgraph_sdk import get_client
 
-from tests.test_data import TestModels, TestUrls
-
 
 @pytest.fixture(scope="session", autouse=True)
 def load_env():
@@ -24,51 +21,17 @@ def load_env():
 
     # Ensure required environment variables are available for tests
     # You can add fallback values or skip tests if keys are missing
-    required_keys = ["OPENAI_API_KEY", "TAVILY_API_KEY"]
+    required_keys = ["DASHSCOPE_API_KEY", "TAVILY_API_KEY"]
     missing_keys = [key for key in required_keys if not os.getenv(key)]
 
     if missing_keys:
         pytest.skip(f"Missing required environment variables: {missing_keys}")
 
 
-@pytest.fixture
-def mock_model():
-    """Create a mock model for testing."""
-    mock = Mock()
-    mock.bind_tools.return_value = mock
-    mock.ainvoke = AsyncMock()
-    return mock
-
-
-@pytest.fixture
-def sample_ai_response():
-    """Create a sample AI response for testing."""
-    return AIMessage(
-        content="This is a test response from the AI model.", tool_calls=[]
-    )
-
-
-@pytest.fixture
-def sample_human_message():
-    """Create a sample human message for testing."""
-    return HumanMessage(content="This is a test message from human.")
-
-
-@pytest.fixture
-def test_context():
-    """Create a test context with common configuration."""
-    from common.context import Context
-
-    return Context(
-        model=TestModels.QWEN_PLUS,
-        system_prompt="You are a helpful AI assistant for testing.",
-    )
-
-
 @pytest.fixture
 async def langgraph_client():
     """Create a LangGraph client for e2e testing."""
-    return get_client(url=TestUrls.LANGGRAPH_LOCAL)
+    return get_client(url="http://127.0.0.1:2024")
 
 
 @pytest.fixture
@@ -80,14 +43,6 @@ async def assistant_id(langgraph_client):
     return assistants[0]["assistant_id"]
 
 
-@pytest.fixture
-async def test_thread(langgraph_client):
-    """Create a test thread for e2e testing."""
-    thread = await langgraph_client.threads.create()
-    yield thread
-    # Cleanup could be added here if needed
-
-
 class TestHelpers:
     """Helper methods for common test operations."""