From d621f92df8b98808ba3fc26e5b0b1fe442265a6e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 2 Nov 2025 23:53:54 +0000 Subject: [PATCH 1/4] Initial plan From 095922960be0082c416a581169ac0a250235f9ad Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 3 Nov 2025 00:00:54 +0000 Subject: [PATCH 2/4] docs: add MCP servers documentation for copilot development Co-authored-by: bestdan <2766380+bestdan@users.noreply.github.com> --- CONTRIBUTING.md | 7 ++ README.md | 5 ++ docs/mcp-servers.md | 213 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 225 insertions(+) create mode 100644 docs/mcp-servers.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fe1a10..ded75be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -107,6 +107,13 @@ pnpm typecheck 4. Write tests in a `.test.ts` file 5. Export utilities from `src/index.ts` if needed +## Copilot Agent Development + +For information on using MCP servers for Copilot agent development: +- See [MCP Servers documentation](docs/mcp-servers.md) +- The GitHub MCP server provides extensive GitHub API access for AI agents +- Useful for automating issue management, PR creation, code analysis, and more + ## Test Coverage This project enforces test coverage for all code. Coverage checks are: diff --git a/README.md b/README.md index 0675bc6..9cbfcef 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,11 @@ For detailed command documentation, see: - [Dart Commands](docs/dart.md) - [Files Commands](docs/files.md) +## Development + +For Copilot agent development and MCP server information: +- [MCP Servers](docs/mcp-servers.md) - Model Context Protocol servers for AI development + [Contributing](CONTRIBUTING.md) ## License diff --git a/docs/mcp-servers.md b/docs/mcp-servers.md new file mode 100644 index 0000000..f8a209a --- /dev/null +++ b/docs/mcp-servers.md @@ -0,0 +1,213 @@ +# MCP Servers for Copilot Agent Development + +This document describes MCP (Model Context Protocol) servers that are useful for developing and testing Copilot agents with this repository. + +## What is MCP? + +The Model Context Protocol (MCP) is an open protocol developed by Anthropic that enables AI assistants to connect with external tools and data sources. MCP servers provide standardized interfaces for AI agents to interact with various services, APIs, and tools. + +## GitHub MCP Server + +**Repository:** [github/github-mcp-server](https://github.com/github/github-mcp-server) +**Status:** Official GitHub MCP server +**Relevance:** ⭐⭐⭐⭐⭐ Essential for Copilot agent development + +### Overview + +The GitHub MCP Server is GitHub's official MCP implementation that connects AI tools directly to GitHub's platform. It provides comprehensive GitHub functionality through natural language interactions. + +### Key Capabilities + +1. **Repository Management** + - Browse and query code + - Search files + - Analyze commits + - Understand project structure + +2. **Issue & PR Automation** + - Create, update, and manage issues + - Create and update pull requests + - Triage bugs + - Review code changes + +3. **CI/CD & Workflow Intelligence** + - Monitor GitHub Actions workflow runs + - Analyze build failures + - Manage releases + - Get insights into development pipeline + +4. **Code Analysis** + - Examine security findings (CodeQL) + - Review Dependabot alerts + - Understand code patterns + - Get comprehensive codebase insights + +5. **Team Collaboration** + - Access discussions + - Manage notifications + - Analyze team activity + +### Usage in Copilot Sessions + +When working with GitHub Copilot in VS Code or other IDEs with MCP support, the GitHub MCP server is typically available by default. Tools from this server are prefixed with `github-mcp-server-`, such as: + +- `github-mcp-server-get_file_contents` +- `github-mcp-server-list_issues` +- `github-mcp-server-search_code` +- `github-mcp-server-list_pull_requests` +- `github-mcp-server-get_workflow_run` + +### Installation Options + +#### Remote Server (Recommended) + +The easiest method is using the remote GitHub MCP Server hosted by GitHub: + +**VS Code Configuration:** +```json +{ + "servers": { + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/" + } + } +} +``` + +#### Local Server (Docker) + +For more control or enterprise scenarios: + +```bash +docker run -i --rm \ + -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + ghcr.io/github/github-mcp-server +``` + +**VS Code Configuration:** +```json +{ + "mcp": { + "inputs": [ + { + "type": "promptString", + "id": "github_token", + "description": "GitHub Personal Access Token", + "password": true + } + ], + "servers": { + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITHUB_PERSONAL_ACCESS_TOKEN", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + } + } + } + } +} +``` + +### Toolset Configuration + +The GitHub MCP server supports enabling/disabling specific toolsets. Default toolsets include: +- `context` - Current user and GitHub context (strongly recommended) +- `repos` - Repository operations +- `issues` - Issue management +- `pull_requests` - PR operations +- `users` - User information + +Additional toolsets available: +- `actions` - CI/CD workflows +- `code_security` - Code scanning +- `dependabot` - Dependency alerts +- `discussions` - GitHub Discussions +- `gists` - Gist management +- `labels` - Label operations +- `notifications` - Notification management +- `orgs` - Organization operations +- `projects` - GitHub Projects +- `secret_protection` - Secret scanning +- `stargazers` - Star operations + +To enable specific toolsets: +```bash +GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server +``` + +Or use `all` for all toolsets: +```bash +GITHUB_TOOLSETS="all" ./github-mcp-server +``` + +### Practical Use Cases for This Repository + +1. **Automated Issue Management** + - Query open issues + - Create issues for detected problems + - Update issue status based on code changes + +2. **Pull Request Automation** + - Create PRs with proper descriptions + - Review PR changes + - Check PR status and CI results + +3. **Code Analysis** + - Search for code patterns + - Analyze commit history + - Review security findings + +4. **CI/CD Monitoring** + - Check workflow status + - Analyze build failures + - Review test results + +5. **Documentation Updates** + - Find related files that need updates + - Create PRs for documentation improvements + +## Other Useful MCP Servers + +While the GitHub MCP server is the most relevant for this project, here are other MCP servers that might be useful: + +### Playwright MCP Server + +**Repository:** [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) +**Use Case:** Browser automation and web testing + +Useful for: +- Testing web-based documentation +- Automating browser interactions +- UI testing scenarios + +### Filesystem MCP Servers + +Various filesystem MCP servers enable: +- File operations +- Directory traversal +- Content search + +These can complement the GitHub server for local development workflows. + +## Best Practices + +1. **Use the Default Toolsets**: Unless you need specific functionality, stick with default toolsets to keep context focused +2. **Read-Only Mode**: For exploratory work, consider using read-only mode to prevent accidental modifications +3. **Toolset Selection**: Enable only the toolsets you need for your current task to reduce complexity +4. **Token Security**: Use environment variables or secure storage for GitHub Personal Access Tokens + +## References + +- [GitHub MCP Server Documentation](https://github.com/github/github-mcp-server) +- [Model Context Protocol Specification](https://modelcontextprotocol.io/) +- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) +- [VS Code MCP Integration](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) From 288015ffb9b7c5a78f20bcd5402d0f5de9f6ddc6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 3 Nov 2025 00:02:45 +0000 Subject: [PATCH 3/4] docs: improve MCP configuration examples consistency Co-authored-by: bestdan <2766380+bestdan@users.noreply.github.com> --- docs/mcp-servers.md | 81 ++++++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 27 deletions(-) diff --git a/docs/mcp-servers.md b/docs/mcp-servers.md index f8a209a..43f22dd 100644 --- a/docs/mcp-servers.md +++ b/docs/mcp-servers.md @@ -61,9 +61,11 @@ When working with GitHub Copilot in VS Code or other IDEs with MCP support, the #### Remote Server (Recommended) -The easiest method is using the remote GitHub MCP Server hosted by GitHub: +The easiest method is using the remote GitHub MCP Server hosted by GitHub. This is typically pre-configured in VS Code with GitHub Copilot. -**VS Code Configuration:** +**Configuration Location:** Add to `.vscode/mcp.json` or VS Code settings + +**For VS Code with OAuth (automatic authentication):** ```json { "servers": { @@ -75,48 +77,73 @@ The easiest method is using the remote GitHub MCP Server hosted by GitHub: } ``` +**For VS Code with Personal Access Token:** +```json +{ + "servers": { + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "Authorization": "Bearer ${input:github_mcp_pat}" + } + } + }, + "inputs": [ + { + "type": "promptString", + "id": "github_mcp_pat", + "description": "GitHub Personal Access Token", + "password": true + } + ] +} +``` + #### Local Server (Docker) -For more control or enterprise scenarios: +For more control, enterprise scenarios, or when the remote server is not available: +**Run the Docker container:** ```bash docker run -i --rm \ -e GITHUB_PERSONAL_ACCESS_TOKEN= \ ghcr.io/github/github-mcp-server ``` -**VS Code Configuration:** +**Configuration Location:** Add to `.vscode/mcp.json` or your IDE's MCP settings file + ```json { - "mcp": { - "inputs": [ - { - "type": "promptString", - "id": "github_token", - "description": "GitHub Personal Access Token", - "password": true - } - ], - "servers": { - "github": { - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", - "ghcr.io/github/github-mcp-server" - ], - "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" - } + "inputs": [ + { + "type": "promptString", + "id": "github_token", + "description": "GitHub Personal Access Token", + "password": true + } + ], + "servers": { + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITHUB_PERSONAL_ACCESS_TOKEN", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" } } } } ``` +**Note:** The configuration format may vary slightly depending on your IDE. VS Code uses `.vscode/mcp.json`, while other IDEs may have different locations or formats. Refer to your IDE's MCP documentation for the exact configuration syntax. + ### Toolset Configuration The GitHub MCP server supports enabling/disabling specific toolsets. Default toolsets include: From e60bf94c7b977b42f012648a234a0193c226bad0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 3 Nov 2025 00:04:40 +0000 Subject: [PATCH 4/4] docs: clarify MCP configuration and token requirements Co-authored-by: bestdan <2766380+bestdan@users.noreply.github.com> --- docs/mcp-servers.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/mcp-servers.md b/docs/mcp-servers.md index 43f22dd..b2fc10c 100644 --- a/docs/mcp-servers.md +++ b/docs/mcp-servers.md @@ -59,11 +59,13 @@ When working with GitHub Copilot in VS Code or other IDEs with MCP support, the ### Installation Options +> **Note:** These examples are for VS Code. Other IDEs with GitHub Copilot support (JetBrains, Visual Studio, etc.) may have different configuration formats. Refer to your IDE's MCP documentation for specifics. + #### Remote Server (Recommended) The easiest method is using the remote GitHub MCP Server hosted by GitHub. This is typically pre-configured in VS Code with GitHub Copilot. -**Configuration Location:** Add to `.vscode/mcp.json` or VS Code settings +**Configuration Location:** Create or edit `.vscode/mcp.json` in your project **For VS Code with OAuth (automatic authentication):** ```json @@ -78,6 +80,13 @@ The easiest method is using the remote GitHub MCP Server hosted by GitHub. This ``` **For VS Code with Personal Access Token:** + +First, [create a GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with these scopes: +- `repo` - Full control of private repositories +- `read:org` - Read organization membership +- `read:packages` - Read packages + +Then configure: ```json { "servers": { @@ -102,16 +111,21 @@ The easiest method is using the remote GitHub MCP Server hosted by GitHub. This #### Local Server (Docker) -For more control, enterprise scenarios, or when the remote server is not available: +For more control, enterprise scenarios, or when the remote server is not available. + +**Prerequisites:** +1. [Docker](https://www.docker.com/) installed and running +2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with scopes: `repo`, `read:org`, `read:packages` **Run the Docker container:** ```bash +# Replace with your actual GitHub Personal Access Token docker run -i --rm \ -e GITHUB_PERSONAL_ACCESS_TOKEN= \ ghcr.io/github/github-mcp-server ``` -**Configuration Location:** Add to `.vscode/mcp.json` or your IDE's MCP settings file +**Configuration Location:** Create or edit `.vscode/mcp.json` in your project ```json { @@ -142,8 +156,6 @@ docker run -i --rm \ } ``` -**Note:** The configuration format may vary slightly depending on your IDE. VS Code uses `.vscode/mcp.json`, while other IDEs may have different locations or formats. Refer to your IDE's MCP documentation for the exact configuration syntax. - ### Toolset Configuration The GitHub MCP server supports enabling/disabling specific toolsets. Default toolsets include: