large commit adding documentation (#26)

Author: grll

.gitignore

@@ -11,4 +11,7 @@ wheels/
 .env
 
 # Notebooks
-notebooks/
+notebooks/
+
+# mkdocs documentation
+/site

Makefile

@@ -0,0 +1,51 @@
+.PHONY: sync
+sync:
+	uv sync --all-extras --all-packages --group dev
+
+.PHONY: format
+format: 
+	uv run ruff format
+	uv run ruff check --fix
+
+.PHONY: lint
+lint: 
+	uv run ruff check
+
+.PHONY: mypy
+mypy: 
+	uv run mypy .
+
+.PHONY: tests
+tests: 
+	uv run pytest 
+
+.PHONY: coverage
+coverage:
+	
+	uv run coverage run -m pytest
+	uv run coverage xml -o coverage.xml
+	uv run coverage report -m --fail-under=95
+
+.PHONY: snapshots-fix
+snapshots-fix: 
+	uv run pytest --inline-snapshot=fix 
+
+.PHONY: snapshots-create 
+snapshots-create: 
+	uv run pytest --inline-snapshot=create 
+
+.PHONY: old_version_tests
+old_version_tests: 
+	UV_PROJECT_ENVIRONMENT=.venv_39 uv run --python 3.9 -m pytest
+
+.PHONY: build-docs
+build-docs:
+	uv run mkdocs build
+
+.PHONY: serve-docs
+serve-docs:
+	uv run mkdocs serve
+
+.PHONY: deploy-docs
+deploy-docs:
+	uv run mkdocs gh-deploy --force --verbose

README.md

@@ -47,7 +47,7 @@ You can also add multiple framework comma separated if needed.
 
 ## Usage
 
-⚠️ **Security Warning**: When using MCP servers, especially over SSE (Server-Sent Events), be extremely cautious and only connect to trusted and verified servers. Some adapters use Python's `exec` function internally, which could potentially allow for remote code execution if connected to a malicious server. Always verify the source and security of any MCP server before connecting.
+⚠️ **Security Warning**: When using MCP servers, especially over SSE (Server-Sent Events), be extremely cautious and only connect to trusted and verified servers. Always verify the source and security of any MCP server before connecting.
 
 ### Smolagents
 
@@ -129,3 +129,16 @@ class YourFrameworkAdapter(ToolAdapter):
 - [x] support for jupyter notebook
 - [x] add tests
 
+## Contributors
+
+We acknowledge the work and thanks every contributors and maintainers for their contributions.
+
+Core Maintainers:
+
+* [@grll](https://github.com/grll)
+
+Contributors:
+
+* [@murawakimitsuhiro](https://github.com/murawakimitsuhiro)
+* [@joejoe2](https://github.com/joejoe2)
+* [@tisDDM](https://github.com/tisDDM)

docs/assets/logo.png

@@ -0,0 +1,138 @@
+# CrewAI
+
+At the time of writing, MCPAdapt offers integration with CrewAI through its adapter system only. However a PR is underway to integrate directly into CrewAI's framework.
+
+Let's explore how to use MCPAdapt with CrewAI.
+
+## Using MCPAdapt CrewAI Adapter
+
+Ensure you have the necessary dependencies installed and set up your OpenAI API key as required by crewAI:
+
+```bash
+pip install mcpadapt[crewai]
+```
+
+### Creating a Simple Echo Server
+
+First, create an MCP server using FastMCP notation:
+
+```python
+# echo.py
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+# Create server
+mcp = FastMCP("Echo Server")
+
+
+@mcp.tool()
+def echo_tool(text: str = Field(description="The text to echo")) -> str:
+    """Echo the input text
+
+    Args:
+        text (str): The text to echo
+
+    Returns:
+        str: The echoed text
+    """
+    return text
+  
+mcp.run()
+```
+
+### Using the Echo Server
+
+Here's how to interact with the server using CrewAI:
+
+```python
+import os
+from crewai import Agent, Crew, Task
+from mcp import StdioServerParameters
+
+from mcpadapt.core import MCPAdapt
+from mcpadapt.crewai_adapter import CrewAIAdapter
+
+with MCPAdapt(
+    StdioServerParameters(command="uv", args=["run", "echo.py"]),
+    CrewAIAdapter(),
+) as tools:
+    # Create an echo agent
+    agent = Agent(
+        role="Echo Agent",
+        goal="Echo messages back to the user",
+        backstory="You help echo messages back to users",
+        verbose=True,
+        tools=[tools[0]],
+    )
+
+    # Create a task
+    task = Task(
+        description="Echo 'Hello, World!'",
+        agent=agent,
+        expected_output="The echoed message",
+    )
+
+    # Create and run the crew
+    crew = Crew(agents=[agent], tasks=[task], verbose=True)
+    crew.kickoff()
+```
+
+### Real-World Example: PubMed MCP Server
+
+In the real-world, you are most likely to run MCP server already built by the community.
+As an example, here's how to use the PubMed MCP server with CrewAI:
+
+```python
+import os
+from dotenv import load_dotenv
+from crewai import Agent, Crew, Task
+from mcp import StdioServerParameters
+
+from mcpadapt.core import MCPAdapt
+from mcpadapt.crewai_adapter import CrewAIAdapter
+
+# Load environment variables
+load_dotenv()
+if not os.environ.get("OPENAI_API_KEY"):
+    raise ValueError("OPENAI_API_KEY must be set in your environment variables")
+
+# Initialize MCPAdapt with CrewAI adapter
+with MCPAdapt(
+    StdioServerParameters(
+        command="uvx",
+        args=["--quiet", "[email protected]"],
+        env={"UV_PYTHON": "3.12", **os.environ},
+    ),
+    CrewAIAdapter(),
+) as tools:
+    # Create a research agent
+    agent = Agent(
+        role="Research Agent",
+        goal="Find studies about hangover",
+        backstory="You help find studies about hangover",
+        verbose=True,
+        tools=[tools[0]],
+    )
+
+    # Create a task
+    task = Task(
+        description="Find studies about hangover",
+        agent=agent,
+        expected_output="A list of studies about hangover",
+    )
+
+    # Create and run the crew
+    crew = Crew(agents=[agent], tasks=[task], verbose=True)
+    crew.kickoff()
+```
+
+#### Important Notes:
+- Always use the `--quiet` flag with uvx to prevent output interference with the stdio transport protocol
+- Including `**os.environ` helps resolve paths in the subprocess but consider security implications of sending your environment variables to the MCP server
+- Remote MCP servers are supported via Server Sent Events (SSE). See the [quickstart SSE guide](../quickstart.md#sse-server-sent-events-support)
+- Make sure to set your OPENAI_API_KEY in your environment variables or .env file
+
+## Full Working Code Example
+
+You can find a fully working script of this example [here](https://github.com/grll/mcpadapt/blob/main/examples/crewai_pubmed.py)
+

docs/assets/logo_dark.png

@@ -0,0 +1,167 @@
+# Google GenAI
+
+MCPAdapt offers integration with Google's genai SDK through its adapter system. Let's explore how to use MCPAdapt with Google GenAI.
+
+## Using MCPAdapt Google GenAI Adapter
+
+First, ensure you have the necessary dependencies installed:
+
+```bash
+pip install mcpadapt[google-genai]
+```
+
+You'll also need to set up your Google API key. You can get this from the Google AI Studio.
+
+### Creating a Simple Echo Server
+
+First, let's create an MCP server using FastMCP notation:
+
+```python
+# echo.py
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+# Create server
+mcp = FastMCP("Echo Server")
+
+@mcp.tool()
+def echo_tool(text: str = Field(description="The text to echo")) -> str:
+    """Echo the input text
+
+    Args:
+        text (str): The text to echo
+
+    Returns:
+        str: The echoed text
+    """
+    return text
+  
+mcp.run()
+```
+
+### Using the Echo Server with Google GenAI
+
+Here's how to interact with the server using Google's Generative AI:
+
+```python
+import os
+from google import genai
+from google.genai import types
+from mcp import StdioServerParameters
+
+from mcpadapt.core import MCPAdapt
+from mcpadapt.google_genai_adapter import GoogleGenAIAdapter
+
+# Initialize Google GenAI client
+client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
+
+# Create server parameters
+server_params = StdioServerParameters(
+    command="uv",
+    args=["run", "echo.py"]
+)
+
+async def run():
+    async with MCPAdapt(
+        server_params,
+        GoogleGenAIAdapter(),
+    ) as adapted_tools:
+        # Unpack tools and tool_functions
+        google_tools, tool_functions = zip(*adapted_tools)
+        tool_functions = dict(tool_functions)
+
+        prompt = "Please echo back 'Hello, World!'"
+
+        # Generate content with function declarations
+        response = client.models.generate_content(
+            model="gemini-2.0-flash",
+            contents=prompt,
+            config=types.GenerateContentConfig(
+                temperature=0.7,
+                tools=google_tools,
+            ),
+        )
+
+        # Handle the function call
+        if response.candidates[0].content.parts[0].function_call:
+            function_call = response.candidates[0].content.parts[0].function_call
+            result = await tool_functions[function_call.name](function_call.args)
+            print(result.content[0].text)
+        else:
+            print("No function call found in the response.")
+            print(response.text)
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(run())
+```
+
+### Real-World Example: Airbnb MCP Server
+
+Here's a real-world example using the Airbnb MCP server with Google GenAI:
+
+```python
+import os
+from google import genai
+from google.genai import types
+from mcp import StdioServerParameters
+
+from mcpadapt.core import MCPAdapt
+from mcpadapt.google_genai_adapter import GoogleGenAIAdapter
+
+# Initialize Google GenAI client
+client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
+
+# Create server parameters for Airbnb MCP
+server_params = StdioServerParameters(
+    command="npx",
+    args=[
+        "-y",
+        "@openbnb/mcp-server-airbnb",
+        "--ignore-robots-txt",
+    ],
+)
+
+async def run():
+    async with MCPAdapt(
+        server_params,
+        GoogleGenAIAdapter(),
+    ) as adapted_tools:
+        # Unpack tools and tool_functions
+        google_tools, tool_functions = zip(*adapted_tools)
+        tool_functions = dict(tool_functions)
+
+        prompt = "I want to book an apartment in Paris for 2 nights, March 28-30"
+
+        # Generate content with function declarations
+        response = client.models.generate_content(
+            model="gemini-2.0-flash",
+            contents=prompt,
+            config=types.GenerateContentConfig(
+                temperature=0.7,
+                tools=google_tools,
+            ),
+        )
+
+        # Handle the function call
+        if response.candidates[0].content.parts[0].function_call:
+            function_call = response.candidates[0].content.parts[0].function_call
+            result = await tool_functions[function_call.name](function_call.args)
+            print(result.content[0].text)
+        else:
+            print("No function call found in the response.")
+            print(response.text)
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(run())
+```
+
+#### Important Notes:
+- Make sure to set your `GEMINI_API_KEY` in your environment variables
+- The examples work with both synchronous and asynchronous code
+- Remote MCP servers are supported via Server Sent Events (SSE). See the [quickstart SSE guide](../quickstart.md#sse-server-sent-events-support)
+
+## Full Working Code Example
+
+You can find a fully working script of the Airbnb example [here](https://github.com/grll/mcpadapt/blob/main/examples/google_genai.py)