README.md

MCP Server: Awesome Copilot

This is an MCP server that retrieves GitHub Copilot customizations from the awesome-copilot repository.

Install

Prerequisites

• .NET 10 SDK
• Visual Studio Code with
  • C# Dev Kit extension
• Azure CLI
• Azure Developer CLI
• Docker Desktop

What's Included

Awesome Copilot MCP server includes:

Building Block	Name	Description	Usage
Tools	search_instructions	Searches agents, hooks, instructions, prompts, skills, and workflows based on keywords in their names and descriptions.	#search_instructions
Tools	load_instruction	Loads a custom instruction, agent, hook, prompt, skill, or workflow from the repository.	#load_instruction
Prompts	get_search_prompt	Get a prompt for searching copilot instructions.	/mcp.awesome-copilot.get_search_prompt

Getting Started

• Getting repository root
• Running MCP server
  • On a local machine
  • In a container
  • On Azure
• Connect MCP server to an MCP host/client
  • VS Code + Agent Mode + Local MCP server

Getting repository root

1. Get the repository root.

   # bash/zsh
   REPOSITORY_ROOT=$(git rev-parse --show-toplevel)

   # PowerShell
   $REPOSITORY_ROOT = git rev-parse --show-toplevel

Running MCP server

On a local machine

1. Run the MCP server app.

   cd $REPOSITORY_ROOT/awesome-copilot
   dotnet run --project ./src/McpSamples.AwesomeCopilot.HybridApp

   Make sure take note the absolute directory path of the McpSamples.AwesomeCopilot.HybridApp project.

   Parameters:

   • --http: The switch that indicates to run this MCP server as a streamable HTTP type. When this switch is added, the MCP server URL is http://localhost:5250.

   With this parameter, you can run the MCP server like:

   dotnet run --project ./src/McpSamples.AwesomeCopilot.HybridApp -- --http

In a container

1. Build the MCP server app as a container image.

   cd $REPOSITORY_ROOT
   docker build -f Dockerfile.awesome-copilot -t awesome-copilot:latest .

2. Run the MCP server app in a container.

   docker run -i --rm -p 8080:8080 awesome-copilot:latest

   Alternatively, use the container image from the container registry.

   docker run -i --rm -p 8080:8080 ghcr.io/microsoft/mcp-dotnet-samples/awesome-copilot:latest

   Parameters:

   • --http: The switch that indicates to run this MCP server as a streamable HTTP type. When this switch is added, the MCP server URL is http://localhost:8080.

   With this parameter, you can run the MCP server like:

   # use local container image
   docker run -i --rm -p 8080:8080 awesome-copilot:latest --http

   # use container image from the container registry
   docker run -i --rm -p 8080:8080 ghcr.io/microsoft/mcp-dotnet-samples/awesome-copilot:latest --http

On Azure

1. Navigate to the directory.

   cd $REPOSITORY_ROOT/awesome-copilot

2. Login to Azure.

   # Login with Azure Developer CLI
   azd auth login

3. Deploy the MCP server app to Azure.

   azd up

   While provisioning and deploying, you'll be asked to provide subscription ID, location, environment name.

4. After the deployment is complete, get the information by running the following commands:

   • Azure Container Apps FQDN:

     azd env get-value AZURE_RESOURCE_MCP_AWESOME_COPILOT_FQDN

Connect MCP server to an MCP host/client

VS Code + Agent Mode + Local MCP server

1. Copy mcp.json to the repository root.

   For locally running MCP server (STDIO):

   mkdir -p $REPOSITORY_ROOT/.vscode
   cp $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.stdio.local.json \
      $REPOSITORY_ROOT/.vscode/mcp.json

   New-Item -Type Directory -Path $REPOSITORY_ROOT/.vscode -Force
   Copy-Item -Path $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.stdio.local.json `
             -Destination $REPOSITORY_ROOT/.vscode/mcp.json -Force

   For locally running MCP server (HTTP):

   mkdir -p $REPOSITORY_ROOT/.vscode
   cp $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.http.local.json \
      $REPOSITORY_ROOT/.vscode/mcp.json

   New-Item -Type Directory -Path $REPOSITORY_ROOT/.vscode -Force
   Copy-Item -Path $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.http.local.json `
             -Destination $REPOSITORY_ROOT/.vscode/mcp.json -Force

   For locally running MCP server in a container (STDIO):

   mkdir -p $REPOSITORY_ROOT/.vscode
   cp $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.stdio.container.json \
      $REPOSITORY_ROOT/.vscode/mcp.json

   New-Item -Type Directory -Path $REPOSITORY_ROOT/.vscode -Force
   Copy-Item -Path $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.stdio.container.json `
             -Destination $REPOSITORY_ROOT/.vscode/mcp.json -Force

   For locally running MCP server in a container (HTTP):

   mkdir -p $REPOSITORY_ROOT/.vscode
   cp $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.http.container.json \
      $REPOSITORY_ROOT/.vscode/mcp.json

   New-Item -Type Directory -Path $REPOSITORY_ROOT/.vscode -Force
   Copy-Item -Path $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.http.container.json `
             -Destination $REPOSITORY_ROOT/.vscode/mcp.json -Force

   For remotely running MCP server in a container (HTTP):

   mkdir -p $REPOSITORY_ROOT/.vscode
   cp $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.http.remote.json \
      $REPOSITORY_ROOT/.vscode/mcp.json

   New-Item -Type Directory -Path $REPOSITORY_ROOT/.vscode -Force
   Copy-Item -Path $REPOSITORY_ROOT/awesome-copilot/.vscode/mcp.http.remote.json `
             -Destination $REPOSITORY_ROOT/.vscode/mcp.json -Force

2. Open Command Palette by typing F1 or Ctrl+Shift+P on Windows or Cmd+Shift+P on Mac OS, and search MCP: List Servers.

3. Choose awesome-copilot then click Start Server.

4. When prompted, enter one of the following values:

   • The absolute directory path of the McpSamples.AwesomeCopilot.HybridApp project
   • The FQDN of Azure Container Apps.

5. Use a prompt by typing /mcp.awesome-copilot.get_search_prompt and enter keywords to search. You'll get a prompt like:

   Please search all the agents, hooks, instructions, prompts, skills, and workflows that are related to the search keyword, `{keyword}`.
   
   Here's the process to follow:
   
   1. Use the `awesome-copilot` MCP server.
   1. Search all agents, hooks, instructions, prompts, skills, and workflows for the keyword provided.
   1. DO NOT load any items from the MCP server until the user asks to do so.
   1. Scan local instructions, prompts, and agents markdown files in `.github/instructions`, `.github/prompts`, and `.github/agents` directories respectively.
   1. Compare existing items with the search results.
   1. Provide a structured response in a table format that includes the already exists, mode (agents, hooks, instructions, prompts, skills, or workflows), filename, name and description of each item found. Here's an example of the table format:
   
       | Exists | Mode         | Filename                      | Name          | Description   |
       |--------|--------------|-------------------------------|---------------|---------------|
       | ✅    | agents       | agent1.agent.md               | Agent 1       | Description 1 |
       | ❌    | instructions | instruction1.instructions.md  | Instruction 1 | Description 1 |
       | ✅    | prompts      | prompt1.prompt.md             | Prompt 1      | Description 1 |
       | ❌    | skills       | skill1/SKILL.md               | Skill 1       | Description 1 |
   
       ✅ indicates that the item already exists in this repository, while ❌ indicates that it does not.
   
   1. If any item doesn't exist in the repository, ask which item the user wants to save.
   1. If the user wants to save it, save the item in the appropriate directory (`.github/instructions`, `.github/prompts`, or `.github/agents`) using the mode and filename, with NO modification.
   

6. Confirm the result.