decodingtrust-agent-sdk 0.1.0__py3-none-any.whl

dt_arena/mcp_server/research/main.py

@@ -0,0 +1,777 @@
+#!/usr/bin/env python3
+"""
+Research MCP server for academic search and code execution.
+Provides tools for:
+- Academic search: ArXiv API + Semantic Scholar API
+- ArXiv HTML: Fetch HTML content from ArXiv paper pages
+- Code execution: Terminal commands in Docker environment
+"""
+import os
+import asyncio
+import json
+import sys
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+import httpx
+from defusedxml.ElementTree import fromstring
+from mcp.server.fastmcp import FastMCP
+
+# Research Docker environment config
+from dt_arena.utils.research.helpers import get_research_container_name
+
+RESEARCH_CONTAINER_NAME = get_research_container_name()
+DOCKER_HOST = os.getenv("DOCKER_HOST", "unix:///var/run/docker.sock")
+
+# API Keys
+SEMANTIC_SCHOLAR_API_KEY = os.getenv("SEMANTIC_SCHOLAR_API_KEY", "")  # Optional
+
+# Debug: Print config on startup
+print(f"[Research MCP Server] ===== STARTING =====", file=sys.stderr)
+print(f"[Research MCP Server] CONTAINER_NAME: {RESEARCH_CONTAINER_NAME}", file=sys.stderr)
+print(f"[Research MCP Server] DOCKER_HOST: {DOCKER_HOST}", file=sys.stderr)
+print(f"[Research MCP Server] SEMANTIC_SCHOLAR_API_KEY: {'SET' if SEMANTIC_SCHOLAR_API_KEY else 'NOT SET'}", file=sys.stderr)
+print(f"[Research MCP Server] ==================", file=sys.stderr)
+sys.stderr.flush()
+
+# Create a FastMCP server (host/port from env, used by streamable-http transport)
+mcp = FastMCP(
+    "Research Agent",
+    host=os.getenv("HOST", "0.0.0.0"),
+    port=int(os.getenv("PORT", "8846")),
+)
+
+_http_client: Optional[httpx.AsyncClient] = None
+
+
+async def get_http() -> httpx.AsyncClient:
+    """Get HTTP client."""
+    global _http_client
+    if _http_client is None:
+        _http_client = httpx.AsyncClient(timeout=30.0)
+    return _http_client
+
+
+# ==================== Academic Search Tools ====================
+
+# async def _search_arxiv(query: str, max_results: int = 10, search_type: str = "all") -> List[Dict[str, Any]]:
+#     """Search ArXiv for papers.
+    
+#     Args:
+#         query: Search query
+#         max_results: Maximum number of results (default: 10, max: 100)
+#         search_type: Search field - "all", "title", "abstract", "author", "cat"
+    
+#     Returns:
+#         List of paper dictionaries
+#     """
+#     try:
+#         # Build query URL (use https to avoid redirect)
+#         base_url = "https://export.arxiv.org/api/query"
+        
+#         # Format query for ArXiv API
+#         if search_type != "all":
+#             # Specific field search
+#             search_query = f"{search_type}:{query}"
+#         else:
+#             # For "all" search, use smart query formatting
+#             query_stripped = query.strip()
+#             if " " in query_stripped:
+#                 # Multi-word query: try title search first for better precision
+#                 # For known paper titles, title search is more accurate
+#                 words = query_stripped.split()
+#                 # Filter out common stop words
+#                 stop_words = {"is", "the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for", "of", "with", "by"}
+#                 meaningful_words = [w for w in words if w.lower() not in stop_words]
+                
+#                 if len(meaningful_words) >= 2:
+#                     # For multi-word queries, search in title for better precision
+#                     # Use first 2 meaningful words in title search (most important keywords)
+#                     key_words = meaningful_words[:2]  # Use first 2 meaningful words
+#                     search_query = " AND ".join([f"ti:{word}" for word in key_words])
+#                 elif meaningful_words:
+#                     # Single meaningful word, use all: prefix
+#                     search_query = f"all:{meaningful_words[0]}"
+#                 else:
+#                     # All stop words, search in title
+#                     search_query = f'ti:"{query_stripped}"'
+#             else:
+#                 # Single word query: use all: prefix
+#                 search_query = f"all:{query_stripped}"
+        
+#         params = {
+#             "search_query": search_query,
+#             "max_results": str(min(max(1, max_results), 100)),
+#             "start": "0"
+#         }
+        
+#         query_string = "&".join([f"{k}={urllib.parse.quote(str(v))}" for k, v in params.items()])
+#         url = f"{base_url}?{query_string}"
+        
+#         # Debug: print the actual query being sent
+#         print(f"[Research MCP Server] ArXiv API query: {search_query}", file=sys.stderr)
+#         print(f"[Research MCP Server] ArXiv API URL: {url}", file=sys.stderr)
+        
+#         # Make request (follow redirects automatically)
+#         async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+#             response = await client.get(url)
+#             response.raise_for_status()
+#             response_text = response.text
+            
+#         # Debug: print response info
+#         print(f"[Research MCP Server] ArXiv API response length: {len(response_text)}", file=sys.stderr)
+        
+#         # Parse Atom XML response
+#         root = fromstring(response_text)
+#         ns = {'atom': 'http://www.w3.org/2005/Atom',
+#               'arxiv': 'http://arxiv.org/schemas/atom'}
+        
+#         # Debug: print number of entries found
+#         entries = root.findall('atom:entry', ns)
+#         print(f"[Research MCP Server] ArXiv API found {len(entries)} entries", file=sys.stderr)
+        
+#         papers = []
+#         for entry in entries:
+#             paper = {
+#                 "id": entry.find('atom:id', ns).text if entry.find('atom:id', ns) is not None else "",
+#                 "title": entry.find('atom:title', ns).text if entry.find('atom:title', ns) is not None else "",
+#                 "summary": entry.find('atom:summary', ns).text if entry.find('atom:summary', ns) is not None else "",
+#                 "published": entry.find('atom:published', ns).text if entry.find('atom:published', ns) is not None else "",
+#                 "updated": entry.find('atom:updated', ns).text if entry.find('atom:updated', ns) is not None else "",
+#                 "authors": [author.find('atom:name', ns).text for author in entry.findall('atom:author', ns) if author.find('atom:name', ns) is not None],
+#                 "primary_category": entry.find('arxiv:primary_category', ns).get('term') if entry.find('arxiv:primary_category', ns) is not None else "",
+#                 "categories": [cat.get('term') for cat in entry.findall('atom:category', ns)],
+#                 "links": []
+#             }
+            
+#             # Extract links
+#             for link in entry.findall('atom:link', ns):
+#                 rel = link.get('rel', '')
+#                 href = link.get('href', '')
+#                 if rel == 'alternate' or rel == '':
+#                     paper['pdf_url'] = href
+#                 elif rel == 'related':
+#                     paper['abs_url'] = href
+#                 paper["links"].append({"rel": rel, "href": href})
+            
+#             papers.append(paper)
+        
+#         return papers
+#     except httpx.HTTPStatusError as e:
+#         print(f"[Research MCP Server] ArXiv API HTTP error: {e.response.status_code} - {e.response.text[:200]}", file=sys.stderr)
+#         print(f"[Research MCP Server] ArXiv API query used: {search_query}", file=sys.stderr)
+#         return []
+#     except Exception as e:
+#         print(f"[Research MCP Server] ArXiv search error: {e}", file=sys.stderr)
+#         print(f"[Research MCP Server] ArXiv API query used: {search_query}", file=sys.stderr)
+#         return []
+
+async def _search_arxiv(query: str, max_results: int = 10, search_type: str = "all") -> List[Dict[str, Any]]:
+    """Search ArXiv for papers using local ArXiv API."""
+    
+    try:
+        # Use local ArXiv API instead of real arXiv
+        base_url = os.getenv("ARXIV_API_URL", "http://localhost:8034")
+        
+        # Build query parameters for local API
+        # Local API uses simpler query format: just pass the search term
+        params = {
+            "q": query.strip(),
+            "limit": min(max(1, max_results), 100)
+        }
+        
+        # If searching by category, add category filter
+        if search_type == "cat":
+            params["category"] = query.strip()
+            params.pop("q", None)  # Remove q when searching by category
+        
+        url = f"{base_url}/api/v1/papers"
+        
+        print(f"[Research MCP Server] Local ArXiv API query: {query}", file=sys.stderr)
+        print(f"[Research MCP Server] Local ArXiv API URL: {url}", file=sys.stderr)
+        print(f"[Research MCP Server] Query params: {params}", file=sys.stderr)
+        
+        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+            response = await client.get(url, params=params)
+            response.raise_for_status()
+            data = response.json()
+        
+        print(f"[Research MCP Server] Local ArXiv API found {data.get('total', 0)} papers", file=sys.stderr)
+        
+        # Convert local API response to arXiv-like format
+        papers = []
+        for paper_data in data.get("papers", []):
+            paper = {
+                "id": f"http://arxiv.org/abs/{paper_data['id']}",  # Format as arXiv URL
+                "title": paper_data.get("title", ""),
+                "summary": paper_data.get("abstract", ""),
+                "published": paper_data.get("submitted_date", ""),
+                "updated": paper_data.get("updated_date", ""),
+                "authors": paper_data.get("authors", []),
+                "primary_category": paper_data["categories"][0] if paper_data.get("categories") else "",
+                "categories": paper_data.get("categories", []),
+                "links": [
+                    {"rel": "alternate", "href": paper_data.get("arxiv_url", f"{base_url}/abs/{paper_data['id']}")},
+                    {"rel": "related", "href": paper_data.get("pdf_url", f"{base_url}/pdf/{paper_data['id']}")}
+                ],
+                "abs_url": paper_data.get("arxiv_url", f"{base_url}/abs/{paper_data['id']}"),
+                "pdf_url": paper_data.get("pdf_url", f"{base_url}/pdf/{paper_data['id']}")
+            }
+            papers.append(paper)
+        
+        return papers
+    
+    except httpx.HTTPStatusError as e:
+        print(f"[Research MCP Server] Local ArXiv API HTTP error: {e.response.status_code} - {e.response.text[:200]}", file=sys.stderr)
+        return []
+    except Exception as e:
+        print(f"[Research MCP Server] Local ArXiv API error: {e}", file=sys.stderr)
+        import traceback
+        traceback.print_exc(file=sys.stderr)
+        return []
+
+
+async def _search_semantic_scholar(query: str, limit: int = 10) -> List[Dict[str, Any]]:
+    """Search Semantic Scholar for papers.
+    
+    Args:
+        query: Search query
+        limit: Maximum number of results (default: 10, max: 100)
+    
+    Returns:
+        List of paper dictionaries
+    """
+    try:
+        url = "https://api.semanticscholar.org/graph/v1/paper/search"
+        params = {
+            "query": query,
+            "limit": min(max(1, limit), 100),
+            "fields": "paperId,title,abstract,authors,year,venue,citationCount,referenceCount,url"
+        }
+        
+        headers = {}
+        if SEMANTIC_SCHOLAR_API_KEY:
+            headers["x-api-key"] = SEMANTIC_SCHOLAR_API_KEY
+        
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.get(url, params=params, headers=headers)
+            response.raise_for_status()
+            data = response.json()
+        
+        papers = []
+        for paper in data.get("data", []):
+            papers.append({
+                "paperId": paper.get("paperId", ""),
+                "title": paper.get("title", ""),
+                "abstract": paper.get("abstract", ""),
+                "authors": [{"name": author.get("name", ""), "authorId": author.get("authorId")} for author in paper.get("authors", [])],
+                "year": paper.get("year"),
+                "venue": paper.get("venue", ""),
+                "citationCount": paper.get("citationCount", 0),
+                "referenceCount": paper.get("referenceCount", 0),
+                "url": paper.get("url", ""),
+            })
+        
+        return papers
+    except Exception as e:
+        print(f"[Research MCP Server] Semantic Scholar search error: {e}", file=sys.stderr)
+        return []
+
+
+# search_arxiv tool removed - use search_arxiv_html instead for HTML-based search
+
+
+@mcp.tool()
+async def search_semantic_scholar(query: str, limit: int = 10) -> str:
+    """Search Semantic Scholar for academic papers.
+    
+    Args:
+        query: Search query (e.g., "quantum computing", "machine learning")
+        limit: Maximum number of results (default: 10, max: 100)
+    
+    Returns:
+        JSON string containing Semantic Scholar search results
+        
+    Example:
+        search_semantic_scholar("quantum computing", limit=5) -> Returns Semantic Scholar papers
+    """
+    if not query or not query.strip():
+        return json.dumps({
+            "error": "Query cannot be empty",
+            "success": False
+        })
+    
+    limit = min(max(1, limit), 100)
+    
+    try:
+        print(f"[Research MCP Server] Searching Semantic Scholar: {query}", file=sys.stderr)
+        s2_results = await _search_semantic_scholar(query, limit=limit)
+        return json.dumps({
+            "query": query,
+            "results": s2_results,
+            "source": "semanticscholar",
+            "success": True
+        }, ensure_ascii=False, indent=2)
+    except Exception as e:
+        return json.dumps({
+            "error": f"Failed to search Semantic Scholar: {str(e)}",
+            "success": False,
+            "query": query
+        })
+
+
+@mcp.tool()
+async def fetch_arxiv_paper_html(paper_id: str, base_url: Optional[str] = None) -> str:
+    """Fetch paper abstract page as HTML from local ArXiv (like real arXiv website).
+    
+    This tool returns the full HTML content of a paper's abstract page,
+    including title, authors, abstract, metadata, and styling.
+    
+    Args:
+        paper_id: ArXiv paper ID (e.g., "2301.12345" or "arxiv:2301.12345")
+        base_url: Base URL for ArXiv (default: "http://localhost:8034")
+    
+    Returns:
+        JSON string containing the HTML content, paper URL, and success status
+        
+    Example:
+        fetch_arxiv_paper_html("2308.03298") -> Returns full HTML page for the paper
+    """
+    if not paper_id or not paper_id.strip():
+        return json.dumps({
+            "error": "Paper ID cannot be empty",
+            "success": False
+        })
+    
+    # Clean paper ID
+    paper_id = paper_id.strip()
+    if paper_id.startswith("arxiv:"):
+        paper_id = paper_id[6:]
+    elif "arxiv.org/abs/" in paper_id:
+        paper_id = paper_id.split("arxiv.org/abs/")[-1]
+    
+    # Remove version suffix
+    if "v" in paper_id and paper_id.split("v")[-1].isdigit():
+        paper_id = paper_id.rsplit("v", 1)[0]
+    
+    # Default to local ArXiv
+    if base_url is None:
+        base_url = os.getenv("ARXIV_API_URL", "http://localhost:8034")
+    
+    base_url = base_url.rstrip("/")
+    
+    try:
+        # Fetch HTML page
+        paper_url = f"{base_url}/abs/{paper_id}"
+        
+        print(f"[Research MCP Server] Fetching paper HTML: {paper_url}", file=sys.stderr)
+        
+        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+            response = await client.get(paper_url)
+            response.raise_for_status()
+            html_content = response.text
+        
+        print(f"[Research MCP Server] Successfully fetched HTML (length: {len(html_content)})", file=sys.stderr)
+        
+        return json.dumps({
+            "paper_id": paper_id,
+            "url": paper_url,
+            "html_content": html_content,
+            "content_length": len(html_content),
+            "success": True
+        }, ensure_ascii=False, indent=2)
+        
+    except httpx.HTTPStatusError as e:
+        error_msg = f"HTTP {e.response.status_code}"
+        if e.response.status_code == 404:
+            error_msg = f"Paper {paper_id} not found"
+        return json.dumps({
+            "error": error_msg,
+            "paper_id": paper_id,
+            "url": paper_url,
+            "status_code": e.response.status_code,
+            "success": False
+        })
+    except Exception as e:
+        return json.dumps({
+            "error": f"Failed to fetch paper HTML: {str(e)}",
+            "paper_id": paper_id,
+            "success": False
+        })
+
+
+@mcp.tool()
+async def search_arxiv_html(query: str, category: Optional[str] = None, limit: int = 20) -> str:
+    """Search arXiv and get results as HTML page (like real arXiv search results).
+    
+    This tool returns search results formatted as an HTML page with paper listings,
+    similar to the real arXiv website.
+    
+    Args:
+        query: Search query (searches in title, abstract, authors)
+        category: Optional category filter (e.g., "cs", "math", "physics")
+        limit: Maximum number of results (default: 20, max: 100)
+    
+    Returns:
+        JSON string containing the HTML content and search metadata
+        
+    Example:
+        search_arxiv_html("transformer", category="cs", limit=10)
+    """
+    if not query or not query.strip():
+        return json.dumps({
+            "error": "Query cannot be empty",
+            "success": False
+        })
+    
+    base_url = os.getenv("ARXIV_API_URL", "http://localhost:8034")
+    limit = min(max(1, limit), 100)
+    
+    try:
+        # Build URL
+        params = {"q": query.strip(), "limit": limit}
+        if category:
+            params["category"] = category
+        
+        url = f"{base_url}/html/search"
+        
+        print(f"[Research MCP Server] Searching arXiv HTML: {query}", file=sys.stderr)
+        
+        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+            response = await client.get(url, params=params)
+            response.raise_for_status()
+            html_content = response.text
+        
+        print(f"[Research MCP Server] Search HTML fetched (length: {len(html_content)})", file=sys.stderr)
+        
+        return json.dumps({
+            "query": query,
+            "category": category,
+            "url": url,
+            "html_content": html_content,
+            "content_length": len(html_content),
+            "success": True
+        }, ensure_ascii=False, indent=2)
+        
+    except Exception as e:
+        return json.dumps({
+            "error": f"Failed to search arXiv HTML: {str(e)}",
+            "query": query,
+            "success": False
+        })
+
+
+@mcp.tool()
+async def list_arxiv_papers_html(category: Optional[str] = None, limit: int = 20) -> str:
+    """List recent arXiv papers as HTML page.
+    
+    This tool returns a list of recent papers formatted as an HTML page.
+    
+    Args:
+        category: Optional category filter (e.g., "cs", "math", "physics")
+        limit: Maximum number of results (default: 20, max: 100)
+    
+    Returns:
+        JSON string containing the HTML content
+        
+    Example:
+        list_arxiv_papers_html(category="cs", limit=15)
+    """
+    base_url = os.getenv("ARXIV_API_URL", "http://localhost:8034")
+    limit = min(max(1, limit), 100)
+    
+    try:
+        params = {"limit": limit}
+        if category:
+            params["category"] = category
+        
+        url = f"{base_url}/html/list"
+        
+        print(f"[Research MCP Server] Listing arXiv papers HTML", file=sys.stderr)
+        
+        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+            response = await client.get(url, params=params)
+            response.raise_for_status()
+            html_content = response.text
+        
+        print(f"[Research MCP Server] List HTML fetched (length: {len(html_content)})", file=sys.stderr)
+        
+        return json.dumps({
+            "category": category,
+            "url": url,
+            "html_content": html_content,
+            "content_length": len(html_content),
+            "success": True
+        }, ensure_ascii=False, indent=2)
+        
+    except Exception as e:
+        return json.dumps({
+            "error": f"Failed to list arXiv papers HTML: {str(e)}",
+            "success": False
+        })
+
+
+@mcp.tool()
+async def upload_arxiv_paper(
+    paper_id: str,
+    title: str,
+    authors: List[str],
+    abstract: str,
+    categories: List[str],
+    submitted_date: Optional[str] = None,
+    pdf_url: Optional[str] = None
+) -> str:
+    """Upload a new paper to arXiv (local sandbox).
+    
+    This tool allows the agent to submit/upload a new paper to the local arXiv database.
+    Useful for testing paper submission workflows or populating the database.
+    
+    Args:
+        paper_id: Paper ID (e.g., "2401.12345", should be unique)
+        title: Paper title
+        authors: List of author names (e.g., ["John Doe", "Jane Smith"])
+        abstract: Paper abstract/summary
+        categories: List of arXiv categories (e.g., ["cs.AI", "cs.LG"])
+        submitted_date: Submission date in ISO format (default: current date)
+        pdf_url: Optional PDF URL (default: auto-generated)
+    
+    Returns:
+        JSON string containing the uploaded paper info and success status
+        
+    Example:
+        upload_arxiv_paper(
+            paper_id="2401.99999",
+            title="A Novel Approach to Machine Learning",
+            authors=["John Doe", "Jane Smith"],
+            abstract="This paper presents...",
+            categories=["cs.LG", "cs.AI"]
+        )
+    """
+    if not paper_id or not paper_id.strip():
+        return json.dumps({
+            "error": "Paper ID cannot be empty",
+            "success": False
+        })
+    
+    if not title or not title.strip():
+        return json.dumps({
+            "error": "Title cannot be empty",
+            "success": False
+        })
+    
+    if not authors or len(authors) == 0:
+        return json.dumps({
+            "error": "At least one author is required",
+            "success": False
+        })
+    
+    if not abstract or not abstract.strip():
+        return json.dumps({
+            "error": "Abstract cannot be empty",
+            "success": False
+        })
+    
+    if not categories or len(categories) == 0:
+        return json.dumps({
+            "error": "At least one category is required",
+            "success": False
+        })
+    
+    base_url = os.getenv("ARXIV_API_URL", "http://localhost:8034")
+    
+    try:
+        # Prepare paper data
+        from datetime import datetime as dt
+        if not submitted_date:
+            submitted_date = dt.utcnow().isoformat()
+        
+        paper_data = {
+            "id": paper_id.strip(),
+            "title": title.strip(),
+            "authors": authors,
+            "abstract": abstract.strip(),
+            "categories": categories,
+            "submitted_date": submitted_date,
+            "updated_date": submitted_date,
+        }
+        
+        if pdf_url:
+            paper_data["pdf_url"] = pdf_url
+        else:
+            paper_data["pdf_url"] = f"{base_url}/pdf/{paper_id}"
+        
+        paper_data["arxiv_url"] = f"{base_url}/abs/{paper_id}"
+        
+        url = f"{base_url}/api/v1/papers"
+        
+        print(f"[Research MCP Server] Uploading paper to arXiv: {paper_id}", file=sys.stderr)
+        print(f"[Research MCP Server] Title: {title}", file=sys.stderr)
+        
+        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+            response = await client.post(url, json=paper_data)
+            response.raise_for_status()
+            result = response.json()
+        
+        print(f"[Research MCP Server] Successfully uploaded paper: {paper_id}", file=sys.stderr)
+        
+        return json.dumps({
+            "paper_id": paper_id,
+            "title": title,
+            "url": f"{base_url}/abs/{paper_id}",
+            "paper_data": result,
+            "success": True,
+            "message": "Paper successfully uploaded to arXiv"
+        }, ensure_ascii=False, indent=2)
+        
+    except httpx.HTTPStatusError as e:
+        error_msg = f"HTTP {e.response.status_code}"
+        error_detail = ""
+        try:
+            error_detail = e.response.json().get("detail", "")
+        except:
+            error_detail = e.response.text[:200]
+        
+        if e.response.status_code == 400:
+            error_msg = f"Paper upload failed: {error_detail}"
+        
+        print(f"[Research MCP Server] Upload failed: {error_msg}", file=sys.stderr)
+        
+        return json.dumps({
+            "error": error_msg,
+            "paper_id": paper_id,
+            "status_code": e.response.status_code,
+            "success": False
+        })
+    except Exception as e:
+        print(f"[Research MCP Server] Upload error: {str(e)}", file=sys.stderr)
+        return json.dumps({
+            "error": f"Failed to upload paper: {str(e)}",
+            "paper_id": paper_id,
+            "success": False
+        })
+
+
+# ==================== Code Execution Tools ====================
+
+async def _execute_command_in_container(command: str, timeout: int = 180) -> Dict[str, Any]:
+    """Execute a command in the terminal Docker container.
+    
+    Args:
+        command: The command to execute
+        timeout: Timeout in seconds (default: 180)
+    
+    Returns:
+        Dictionary with stdout, stderr, return_code, and success status
+    """
+    try:
+        docker_cmd = [
+            "docker", "exec",
+            "-u", "root",
+            RESEARCH_CONTAINER_NAME,
+            "bash", "-c", command
+        ]
+        
+        print(f"[Research MCP Server] Executing command: {' '.join(docker_cmd)}", file=sys.stderr)
+        
+        # Execute the command with timeout
+        process = await asyncio.create_subprocess_exec(
+            *docker_cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE
+        )
+        
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=timeout
+            )
+            
+            stdout_str = stdout.decode('utf-8', errors='replace')
+            stderr_str = stderr.decode('utf-8', errors='replace')
+            return_code = process.returncode
+            
+            return {
+                "stdout": stdout_str,
+                "stderr": stderr_str,
+                "return_code": return_code,
+                "success": return_code == 0,
+                "command": command
+            }
+            
+        except asyncio.TimeoutError:
+            # Kill the process if it times out
+            process.kill()
+            await process.wait()
+            return {
+                "stdout": "",
+                "stderr": f"Command timed out after {timeout} seconds",
+                "return_code": -1,
+                "success": False,
+                "command": command,
+                "error": "timeout"
+            }
+            
+    except Exception as e:
+        return {
+            "stdout": "",
+            "stderr": f"Failed to execute command: {str(e)}",
+            "return_code": -1,
+            "success": False,
+            "command": command,
+            "error": str(e)
+        }
+
+
+@mcp.tool()
+async def execute_command(command: str, timeout: int = 180) -> str:
+    """Execute a command in the terminal Docker environment (for code execution and programming tasks).
+    
+    Args:
+        command: The command to execute (e.g., "ls", "pwd", "python script.py", "git clone ...")
+        timeout: Timeout in seconds (default: 180, max: 300)
+    
+    Returns:
+        JSON string containing the command output, stderr, return code, and success status
+        
+    Example:
+        execute_command("ls -la") -> Returns directory listing
+        execute_command("python script.py") -> Executes Python script
+        execute_command("git clone https://github.com/user/repo.git") -> Clones repository
+    """
+    if not command or not command.strip():
+        return json.dumps({
+            "error": "Command cannot be empty",
+            "success": False
+        })
+    
+    # Limit timeout to prevent abuse
+    timeout = min(max(timeout, 1), 300)
+    
+    try:
+        result = await _execute_command_in_container(command.strip(), timeout)
+        return json.dumps(result, ensure_ascii=False, indent=2)
+    except Exception as e:
+        return json.dumps({
+            "error": f"Failed to execute command: {str(e)}",
+            "success": False,
+            "command": command
+        })
+
+
+def main():
+    print("Starting Research MCP server...", file=sys.stderr)
+    sys.stderr.flush()
+
+    host = os.getenv("HOST", "0.0.0.0")
+    port = int(os.getenv("PORT", "8846"))
+
+    print(f"[Research MCP Server] Starting on {host}:{port}", file=sys.stderr)
+    sys.stderr.flush()
+
+    mcp.run(transport="streamable-http")
+
+
+if __name__ == "__main__":
+    main()
+