# mcp-agent

A **multi-service MCP (Model Context Protocol) server** that gives an AI agent access to 34 tools across 9 platforms — GitHub, Jira, Azure DevOps, Slack, PagerDuty, Linear, Notion, HuggingFace, and OpenWeather.

Instead of switching between tabs and dashboards, you talk to your AI assistant in plain English and it queries or acts on these systems directly.

Works with **Claude, GPT-4o, Azure OpenAI**, and any MCP-compatible client.

---

## What is MCP?

The **Model Context Protocol** is an open standard by Anthropic that lets AI models communicate with external tools and APIs in a structured, secure way. The AI stays in the conversation but can reach out to real systems to fetch data or take actions — autonomously deciding which tools to call and in what order.

→ [How it works in detail](docs/how-it-works.md)

---

## Services & Tools

### GitHub
| Tool | Type | What it does |
|------|------|-------------|
| `get_user_profile` | read | Bio, location, followers, and public repo count |
| `get_user_repos` | read | Public repositories sorted by activity, stars, or date |
| `get_repo_info` | read | Stars, forks, open issues, topics, license, last push |
| `get_repo_issues` | read | Open or closed issues |
| `get_pull_requests` | read | Open or merged pull requests |
| `get_file_content` | read | Content of any file in a repository |
| `get_repo_contributors` | read | Top contributors ranked by commit count |
| `get_repo_releases` | read | Latest releases and changelogs |
| `get_trending` | read | Trending repos by language and period (daily/weekly/monthly) |
| `search_repos` | read | Search by keyword, topic, or language |
| `create_issue` | **write** | Create a new issue (requires `repo` token scope) |

### Jira
| Tool | Type | What it does |
|------|------|-------------|
| `jira_search_issues` | read | Search issues using JQL |
| `jira_get_issue` | read | Full details of an issue by key |
| `jira_get_project_issues` | read | Issues for a project filtered by status |
| `jira_create_issue` | **write** | Create a Task, Bug, Story, or Epic |

### Azure DevOps
| Tool | Type | What it does |
|------|------|-------------|
| `ado_list_pipelines` | read | List CI/CD pipelines in a project |
| `ado_get_pipeline_runs` | read | Recent runs for a pipeline |
| `ado_search_work_items` | read | Search work items by keyword |
| `ado_create_work_item` | **write** | Create a Task, Bug, User Story, or Epic |

### Slack
| Tool | Type | What it does |
|------|------|-------------|
| `slack_get_channels` | read | List public channels in the workspace |
| `slack_get_messages` | read | Read recent messages from a channel |
| `slack_send_message` | **write** | Send a message to a channel or user |

### PagerDuty
| Tool | Type | What it does |
|------|------|-------------|
| `pagerduty_get_incidents` | read | List incidents by status |
| `pagerduty_get_services` | read | List configured services |
| `pagerduty_create_incident` | **write** | Trigger a new incident |

### Linear
| Tool | Type | What it does |
|------|------|-------------|
| `linear_get_teams` | read | List teams in the workspace |
| `linear_get_issues` | read | Issues for a team filtered by state |
| `linear_create_issue` | **write** | Create an issue in a team |

### Notion
| Tool | Type | What it does |
|------|------|-------------|
| `notion_search` | read | Search pages and databases by keyword |
| `notion_get_page` | read | Get the content of a page |
| `notion_create_page` | **write** | Create a new page under a parent |

### HuggingFace
| Tool | Type | What it does |
|------|------|-------------|
| `hf_search_models` | read | Search models by keyword and task |
| `hf_get_model` | read | Detailed model info (downloads, likes, tags) |
| `hf_search_datasets` | read | Search datasets by keyword |

### OpenWeather
| Tool | Type | What it does |
|------|------|-------------|
| `weather_current` | read | Current weather for a city |
| `weather_forecast` | read | Multi-day forecast for a city |

---

## Example use cases

**Cross-service reasoning**
> *"Check if there are any open Jira bugs related to our Azure DevOps pipeline failures this week, then create a GitHub issue summarizing them."*

The agent calls `jira_search_issues` → `ado_get_pipeline_runs` → `create_issue` autonomously.

---

**Incident response**
> *"There's an active PagerDuty incident on the payments service. Find the latest PR merged to that repo and notify the #incidents Slack channel."*

The agent calls `pagerduty_get_incidents` → `get_pull_requests` → `slack_send_message`.

---

**AI research**
> *"Find the most downloaded text-generation models on HuggingFace, then search GitHub for projects using the top one."*

The agent calls `hf_search_models` → `search_repos`.

---

**Developer onboarding**
> *"Who are the top 5 contributors to this repo? Get their GitHub profiles and create a Notion page summarizing the team."*

The agent calls `get_repo_contributors` → `get_user_profile` (×5) → `notion_create_page`.

→ [More use cases](docs/use-cases.md)

---

## Setup

**1. Clone and install**
```bash
git clone https://github.com/Abdessamad-Y/mcp-github-agent.git
cd mcp-github-agent
pip install -r requirements.txt
```

**2. Configure your services**
```bash
cp .env.example .env
# Add tokens only for the services you want to use
# Unused services are safely ignored
```

**3. Connect to your AI client**

→ See [docs/integrations.md](docs/integrations.md) for setup guides:
- **Claude Desktop** — native MCP, no code needed
- **Claude API** — Python script with agentic loop
- **OpenAI (GPT-4o)** — via `openai-agents` SDK
- **Azure OpenAI** — via OpenAI SDK + Azure endpoint
- **Cursor / VS Code Copilot**

---

## Run the demo

```bash
GITHUB_TOKEN=your_token python demo.py
```

Runs 4 live scenarios with formatted terminal output. No AI API key needed.

---

## Run the examples

```bash
# With Claude API
GITHUB_TOKEN=your_token ANTHROPIC_API_KEY=your_key python examples/with_claude.py

# With OpenAI
GITHUB_TOKEN=your_token OPENAI_API_KEY=your_key python examples/with_openai.py

# With Azure OpenAI
GITHUB_TOKEN=your_token \
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com \
AZURE_OPENAI_KEY=your_key \
AZURE_OPENAI_DEPLOYMENT=gpt-4o \
python examples/with_azure_openai.py
```

---

## Project structure

```
mcp-github-agent/
├── server.py              # Entry point — registers all tools
├── mcp_instance.py        # Shared FastMCP instance
├── tools/
│   ├── github.py          # 11 GitHub tools
│   ├── jira.py            # 4 Jira tools
│   ├── azure_devops.py    # 4 Azure DevOps tools
│   ├── slack.py           # 3 Slack tools
│   ├── pagerduty.py       # 3 PagerDuty tools
│   ├── linear.py          # 3 Linear tools
│   ├── notion.py          # 3 Notion tools
│   ├── huggingface.py     # 3 HuggingFace tools
│   └── weather.py         # 2 OpenWeather tools
├── examples/
│   ├── with_claude.py
│   ├── with_openai.py
│   └── with_azure_openai.py
├── docs/
│   ├── how-it-works.md
│   ├── use-cases.md
│   └── integrations.md
├── demo.py
├── requirements.txt
└── .env.example
```

---

## Stack

| | |
|---|---|
| Language | Python 3.10+ |
| MCP SDK | `mcp[cli]` — Anthropic's official Python SDK |
| HTTP client | `httpx` |
| Terminal output | `rich` |

---

## Docs

| | |
|---|---|
| [How it works](docs/how-it-works.md) | Architecture, MCP protocol, transport |
| [Use cases](docs/use-cases.md) | Real-world prompts and agent behavior |
| [Integrations](docs/integrations.md) | Setup for Claude, OpenAI, Azure OpenAI, Cursor, VS Code |

---

## License

MIT