diff --git a/contributing/samples/mcp_stdio_github_agent/README.md b/contributing/samples/mcp_stdio_github_agent/README.md new file mode 100644 index 000000000..07a6ca55c --- /dev/null +++ b/contributing/samples/mcp_stdio_github_agent/README.md @@ -0,0 +1,30 @@ +# GitHub MCP Agent + +This is an agent that uses the GitHub MCP tool to call GitHub’s API. It demonstrates how to pass in your Personal Access Token and interact with repositories, issues, and pull requests. + +Follow the instructions below to use it: + +* Follow the installation instructions in the GitHub MCP Server README to set up and run the server via Docker: + https://github.com/github/github-mcp-server + +* Set the environment variable `GITHUB_PERSONAL_ACCESS_TOKEN` to the token you obtained in the previous step: + ```bash + export GITHUB_PERSONAL_ACCESS_TOKEN= + ``` + +* Run the agent in the ADK Web UI or via CLI: + ```bash + python agent.py + ``` + + +* Sample queries using GitHub MCP capabilities: + + - `List all my repositories for the authenticated user` + - `Search for issues in "octocat/Hello-World" with state "open"` + - `Get the contents of "src/" in repo "your-org/your-repo"` + - `Create a new issue in "your-org/your-repo" titled "MCP integration" with body "Please review the setup."` + - `Add a comment to issue #42 in "your-org/your-repo": "Looks good to me!"` + - `List pull requests in "your-org/your-repo" sorted by "created"` + - `Get code scanning alerts for "your-org/your-repo"` + - `Search code in "your-org/your-repo" for query "def initialize"` diff --git a/contributing/samples/mcp_stdio_github_agent/__init__.py b/contributing/samples/mcp_stdio_github_agent/__init__.py new file mode 100644 index 000000000..02c597e11 --- /dev/null +++ b/contributing/samples/mcp_stdio_github_agent/__init__.py @@ -0,0 +1 @@ +from . import agent diff --git a/contributing/samples/mcp_stdio_github_agent/agent.py b/contributing/samples/mcp_stdio_github_agent/agent.py new file mode 100644 index 000000000..3c71d64fb --- /dev/null +++ b/contributing/samples/mcp_stdio_github_agent/agent.py @@ -0,0 +1,57 @@ +# agent.py +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import json +from dotenv import load_dotenv +from google.adk.agents.llm_agent import LlmAgent +from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StdioServerParameters + +# Load environment variables from .env if present +load_dotenv() + +# Retrieve GitHub Personal Access Token +GITHUB_TOKEN = os.getenv("GITHUB_PERSONAL_ACCESS_TOKEN") +if not GITHUB_TOKEN: + raise ValueError("GITHUB_PERSONAL_ACCESS_TOKEN environment variable is not set") + +# Docker command for the GitHub MCP server +docker_command = "docker" +# Basic Docker arguments to launch the MCP server +docker_args = [ + "run", "-i", "--rm", + "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", + "ghcr.io/github/github-mcp-server" +] + +# Instantiate the ADK LLM Agent with GitHub MCP tool +github_agent = LlmAgent( + model="gemini-2.0-flash", + name="github_agent", + instruction=( + "You are a GitHub assistant. " + "Use the provided MCP tool to fetch repositories, issues, PRs, and perform GitHub API operations. " + "Ask clarifying questions only when essential details are missing." + ), + tools=[ + MCPToolset( + connection_params=StdioServerParameters( + command=docker_command, + args=docker_args, + env={"GITHUB_PERSONAL_ACCESS_TOKEN": GITHUB_TOKEN} + ) + ) + ], +) \ No newline at end of file