Awesome Copilot Server

npm version License: MIT Build Status

A Model Context Protocol (MCP) server that provides access to awesome-copilot agents and collection resources.

Quick Start

One-Click Installation for VS Code

Click the badge to install directly in VS Code (will prompt to open VS Code):

Install in VS Code Install in VS Code Insiders

Note: Requires GitHub Copilot extension in VS Code. Click the badge on GitHub to trigger the installation prompt.

Manual Configuration

Add to your MCP Client configuration (e.g., Claude Desktop or VS Code):

{
  "mcpServers": {
    "awesome-copilot": {
      "command": "npx",
      "args": ["-y", "awesome-copilot-mcp", "start"]
    }
  }
}

This ensures you always run the latest version.

Usage

As MCP Server

Standard stdio usage (default). See configuration above.

As HTTP / OpenAPI Server

Run locally for remote access or OpenAPI testing:

npx -y awesome-copilot-mcp start-http --port 8080 --host 0.0.0.0

Available endpoints:

• GET /health Health check
• GET /metadata Return metadata index
• GET /metadata/stream SSE streaming output of metadata
• GET /search?q=kw Search
• GET /openapi.json API Documentation

Supported Content Types

This server now indexes all resources published in the official github/awesome-copilot repository:

• 🤖 Agents
• 💬 Prompts
• 📋 Instructions
• 🛠️ Skills (folder-aware)
• 📦 Collections
• 🎁 Plugins (from plugins/external.json)
• 🪝 Hooks
• ⚡ Agentic Workflows

Debugging

MCP Inspector is the recommended way to test and debug:

# Debug via Stdio (Recommended)
npx -y awesome-copilot-mcp debug --no-build

# Debug via HTTP
npm run inspect:http

Architecture

This server uses a Bundled + In-Memory architecture for maximum reliability:

1. Startup: Loads metadata.json bundled directly within the npm package. Zero external dependencies.
2. Hot Updates: refresh_metadata fetches the latest data from GitHub and stores it in memory for the current session.
3. Sandbox Friendly: No local disk cache (~/.cache) is used, preventing permission issues in restricted environments (e.g., macOS App Sandbox).

Environment Variables

Variable	Description
ACP_METADATA_URL	Optional. URL to a hosted metadata.json (e.g. https://yourname.github.io/repo/metadata.json). Overrides GitHub raw fetch.
ACP_REPOS_JSON	Custom repository configuration JSON.

Metadata Generation

Automated: GitHub Actions runs daily to fetch the latest metadata from github/awesome-copilot and publishes a new npm version if changes are detected.

Internal: The metadata file is lightweight (~170 KB) containing only index info. Actual content and download targets for agents, prompts, instructions, skills, collections, plugins, hooks, and workflows are resolved on-demand via the exposed tools and resources.

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

License

MIT