early version of huggingface open deep research project as an mcp ser…

…ver and copier mcp server template (#322)

It works, but requires API keys for services that we'd like to swap out,
but merging for folks to access early.

.devcontainer/devcontainer.json

@@ -24,7 +24,8 @@
       "nvmVersion": "latest"
     },
     "ghcr.io/devcontainers/features/azure-cli:1": {},
-    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+    "ghcr.io/devcontainers-extra/features/ffmpeg-apt-get:1": {}
   },
   // Use 'forwardPorts' to make a list of ports inside the container available locally.
   "forwardPorts": [3000, 4000, 5000],

assistants/codespace-assistant/assistant/extensions/tools/__model.py

@@ -68,7 +68,13 @@ class MCPServerConfig(BaseModel):
 
     key: Annotated[str, Field(title="Key", description="Unique key for the server configuration.")]
 
-    command: Annotated[str, Field(title="Command", description="Command to run the server.")]
+    command: Annotated[
+        str,
+        Field(
+            title="Command",
+            description="Command to run the server, use url if using SSE transport."
+        )
+    ]
 
     args: Annotated[List[str], Field(title="Arguments", description="Arguments to pass to the server.")]
 
@@ -172,6 +178,12 @@ class ToolsConfigModel(BaseModel):
             """).strip(),
             enabled=False,
         ),
+        MCPServerConfig(
+            key="deep_research",
+            command="http://127.0.0.1:6020/sse",
+            args=[],
+            enabled=False,
+        ),
         MCPServerConfig(
             key="vscode",
             command="http://127.0.0.1:6010/sse",

mcp-servers/ai-assist-content/README.md

@@ -15,4 +15,14 @@ that uses the Model Context Protocol (MCP).
 - [mcp-python-sdk-README.md](./mcp-python-sdk-README.md): README from the Python SDK at https://github.com/modelcontextprotocol/python-sdk
 - [mcp-typescript-sdk-README.md](./mcp-typescript-sdk-README.md): README from the TypeScript SDK at https://github.com/modelcontextprotocol/typescript-sdk
 
-* last updated 2/3/25
+## MPC Server Template
+
+There is a `copier` template available to quickly generate a new MCP Server project. See the [MCP Server Template README](../mcp-server-template/README.md) for more information.
+
+Users can generate a new MCP Server project from this template with the following command:
+
+```bash
+copier copy path/to/mcp-server-template path/to/destination
+```
+
+- last updated 2/12/25

mcp-servers/mcp-server-giphy/.env.example

@@ -1 +1,5 @@
-GIPHY_API_KEY=REPLACE_WITH_YOUR_GIPHY_API_KEY
+# Optional for the service
+#LOG_LEVEL=DEBUG
+
+# Required for the service
+GIPHY_API_KEY=REPLACE_WITH_YOUR_GIPHY_API_KEY

mcp-servers/mcp-server-giphy/.vscode/launch.json

@@ -2,13 +2,13 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "mcp-servers: mcp-server-giphy",
       "type": "debugpy",
       "request": "launch",
-      "program": "${workspaceFolder}/server/main.py",
+      "name": "mcp-servers: mcp-server-giphy",
+      "cwd": "${workspaceFolder}",
+      "module": "mcp_server.start",
       "args": ["--transport", "sse", "--port", "6000"],
-      "console": "integratedTerminal",
-      "consoleName": "mcp-server-giphy"
+      "consoleTitle": "mcp-server-giphy"
       // "justMyCode": false // Set to false to debug external libraries
     }
   ]

mcp-servers/mcp-server-giphy/.vscode/settings.json

@@ -48,5 +48,12 @@
     "settings.json",
     "uv.lock"
   ],
-  "cSpell.words": ["debugpy", "dotenv", "fastmcp", "GIPHY", "pyright"]
+  "cSpell.words": [
+    "debugpy",
+    "dotenv",
+    "fastmcp",
+    "GIPHY",
+    "pyright",
+    "toplevel"
+  ]
 }

mcp-servers/mcp-server-giphy/Makefile

@@ -1,3 +1,2 @@
 repo_root = $(shell git rev-parse --show-toplevel)
 include $(repo_root)/tools/makefiles/python.mk
-include $(repo_root)/tools/makefiles/docker-assistant.mk

mcp-servers/mcp-server-giphy/mcp_server/__init__.py

@@ -0,0 +1,6 @@
+from dotenv import load_dotenv
+from . import config
+
+# Load environment variables from .env into the settings object.
+load_dotenv()
+settings = config.Settings()

mcp-servers/mcp-server-giphy/mcp_server/config.py

@@ -0,0 +1,16 @@
+import os
+from pydantic_settings import BaseSettings
+
+log_level = os.environ.get("LOG_LEVEL", "INFO")
+
+def load_required_env_var(env_var_name: str) -> str:
+    value = os.environ.get(env_var_name, "")
+    if not value:
+        raise ValueError(f"Missing required environment variable: {env_var_name}")
+    return value
+
+giphy_api_key = load_required_env_var("GIPHY_API_KEY")
+
+class Settings(BaseSettings):
+    log_level: str = log_level
+    giphy_api_key: str = giphy_api_key

mcp-servers/mcp-server-giphy/mcp_server/server.py

@@ -0,0 +1,43 @@
+from typing import Optional
+from mcp.server.fastmcp import FastMCP
+
+
+from . import settings
+from .giphy_search import perform_search
+
+# Set the name of the MCP server
+server_name = "GIPHY MCP Server"
+
+def create_mcp_server() -> FastMCP:
+
+    # Initialize FastMCP with debug logging.
+    mcp = FastMCP(name=server_name, log_level=settings.log_level)
+
+    # Define each tool and its setup.
+
+    @mcp.tool()
+    async def giphy_search_tool(context: str, search_term: str) -> Optional[list]:
+        # Perform search using context and search term
+        search_results = perform_search(context, search_term)
+
+        # Sampling isn't implemented in FastMCP yet, so we'll need to extend it.
+        # For now, just return a simplified list.
+
+        return [
+            {
+                "title": result["title"],
+                "alt_text": result["alt_text"],
+                "image": result["images"]["original"],
+            }
+            for result in search_results
+        ]
+
+        # # Create sampling request message, integrating search results and context
+        # sampling_result = await perform_sampling(search_results, context)
+
+        # # Extract and return image selected by sampling
+        # final_image = next(
+        #     (content for content in sampling_result if content['type'] == "image"), None)
+        # return final_image["data"] if final_image else None
+
+    return mcp

mcp-servers/mcp-server-giphy/mcp_server/start.py

@@ -0,0 +1,31 @@
+# Main entry point for the MCP Server
+
+import argparse
+
+from .server import create_mcp_server
+
+def main() -> None:
+    # Command-line arguments for transport and port
+    parse_args = argparse.ArgumentParser(description=f"Start the MCP server.")
+    parse_args.add_argument(
+        "--transport",
+        default="stdio",
+        choices=["stdio", "sse"],
+        help="Transport protocol to use ('stdio' or 'sse'). Default is 'stdio'.",
+    )
+    parse_args.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port to use for SSE (default is 8000)."
+    )
+    args = parse_args.parse_args()
+
+    mcp = create_mcp_server()
+    if args.transport == "sse":
+        mcp.settings.port = args.port
+
+    mcp.run(transport=args.transport)
+
+if __name__ == "__main__":
+    main()

mcp-servers/mcp-server-giphy/pyproject.toml

@@ -7,15 +7,15 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = ["mcp>=1.2.1", "requests>=2.25"]
 
+[dependency-groups]
+dev = ["pyright>=1.1.389"]
+
 [tool.hatch.build.targets.wheel]
-packages = ["server"]
+packages = ["mcp_server"]
 
 [tool.uv]
 package = true
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
-
-[dependency-groups]
-dev = ["pyright>=1.1.389"]

mcp-servers/mcp-server-open-deep-research/.env.example

@@ -0,0 +1,8 @@
+# Optional for the service
+#DATA_FOLDER=.data
+#LOG_LEVEL=DEBUG
+
+# Required for the service
+HUGGINGFACE_API_KEY=YOUR_HUGGINGFACE_API_KEY
+OPENAI_API_KEY=YOUR_OPENAI_API_KEY
+SERP_API_KEY=YOUR_SERP_API_KEY

mcp-servers/mcp-server-open-deep-research/.gitignore

@@ -0,0 +1,38 @@
+# Python files
+__pycache__/
+*.py[cod]
+
+# Virtual environment
+.venv
+
+# Poetry
+poetry.lock
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+
+# Environment variables
+.env

mcp-servers/mcp-server-open-deep-research/.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "debugpy",
+      "request": "launch",
+      "name": "mcp-servers: mcp-server-open-deep-research",
+      "cwd": "${workspaceFolder}",
+      "module": "mcp_server.start",
+      "args": ["--transport", "sse", "--port", "6020"],
+      "consoleTitle": "mcp-server-open-deep-research"
+      // "justMyCode": false // Set to false to debug external libraries
+    }
+  ]
+}