Copilot Compass

Copilot Compass

Navigate your GitHub Copilot adoption with actionable insights

An MCP App that delivers comprehensive GitHub Copilot usage analytics through an interactive React dashboard, powered by the MCP Apps SDK.

Features • Quick Start • Codespaces • Usage • Architecture • Troubleshooting

______________________________________________________________________

概述

副驾驶指南针 是一个模型上下文协议（MCP）应用程序，它将原始GitHub Copilot指标转换为可操作的情报。它采用MCP Apps SDK构建，提供AI可读数据和交互式可视化仪表板，可直接在与MCP兼容的主机（如VS Code和Claude Desktop）中呈现。

是什么让这个特别？

与传统仪表板不同，Copilot Compass利用了 MCP应用软件开发工具包 图案：

• AI优先：工具返回AI模型可以分析和总结的结构化数据
• 可视化仪表板：相同的工具调用在宿主中呈现交互式React UI
• 实时同步：当新数据通过以下方式到达时，UI会自动更新 ontoolresult
• 主持人主题：仪表板通过以下方式适应主机的配色方案 useHostStyles

特性

分析仪表板

• 活跃用户趋势 --14天折线图，显示每日活跃用户数
• 接受率 --随时间推移跟踪代码建议接受情况
• 语言细分 --按建议、接受度和参与用户分列的热门语言
• 编辑器分布 --使用情况在VS Code、JetBrains、Neovim等平台上进行划分
• 聊天指标 --Copilot聊天中的会话、代码插入和复制事件
• 公关情报 --拉取请求摘要生成统计信息

了解指标

报告生成

• 企业与组织支持 --获取企业或组织级别的指标
• 灵活的日期范围 --分析任何时间段
• 自动回退 -当API不可用时，具有真实模拟数据的演示模式
• 缓存层 -5分钟的TTL减少了API调用并提高了响应时间

MCP应用程序SDK功能

• 工具+UI绑定 — _meta.ui.resourceUri 将工具链接到其视觉表示
• 仅限应用程序的工具 — visibility: ["app"] 用于对AI隐藏的UI启动操作
• 主机上下文 --安全区镶嵌和主题整合
• 生命周期挂钩 — ontoolresult, ontoolinput, onteardown 回调

快速开始

先决条件

• Node.js 18+
• VS代码内部人员 --MCP Apps SDK（交互式仪表板）需要。 点击此处下载. *VS Code Stable支持MCP工具，但尚不支持可视化仪表板UI。*
• GitHub PAT 范围：

- manage_billing:copilot --访问副驾驶指标 - read:enterprise --企业级访问 - read:org --组织指标

安装

# Clone the repository
git clone https://github.com/samueltauil/copilot-compass.git
cd copilot-compass

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your GITHUB_TOKEN

构建与运行

# Build the React dashboard and TypeScript server
npm run build

# Start the MCP server
npm start

服务器启动于 http://localhost:3001 与：

• MCP端点: http://localhost:3001/mcp
• 健康检查: http://localhost:3001/health

连接您的MCP客户端

添加到您的MCP客户端配置中（例如，Claude Desktop、VS Code）：

对于远程HTTP连接：

{
  "mcpServers": {
    "copilot-compass": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

对于本地stdio连接（可选）：

{
  "mcpServers": {
    "copilot-compass": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/path/to/copilot-compass",
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

对于VS Code用户：

复制附带的示例文件以创建MCP配置：

cp .vscode/mcp.json.example .vscode/mcp.json

默认使用 localhost:3001.如果使用隧道（cloudflared，ngrok），请编辑 .vscode/mcp.json 使用您的隧道URL：

{
  "servers": {
    "copilot-compass": {
      "type": "http",
      "url": "https://your-tunnel-url.trycloudflare.com/mcp"
    }
  }
}

注： .vscode/mcp.json 是gitignore，因此您的本地配置不会被覆盖。

在GitHub代码空间中运行

⚠️ 重要提示： MCP Apps SDK（交互式仪表板UI）目前需要 VS代码内部人员Codespaces web编辑器使用稳定的VS Code。要使用完整的仪表板UI，您必须从本地计算机上的VS Code Insiders连接。

选项A：从VS Code Insiders桌面连接（完整UI）

这为您提供了交互式仪表板的完整MCP Apps体验。

1. 安装 VS代码内部人员 本地
2. 安装 VS代码内部人士
3. 在以下位置创建代码空间
4. 在Codespace web视图中，单击汉堡包菜单（≡）→ 在VS Code桌面中打开
5. 出现提示时，选择 Visual Studio代码内部人员

选项B：使用代码空间Web编辑器（仅限工具）

如果你只需要MCP 工具 （不是可视化仪表板），web编辑器工作正常：

](https://codespaces.new/samueltauil/copilot-compass?quickstart=1)

或手动：

1. 首选
2. 点击 代码 → 代码空间 → 在main上创建代码空间
3. 等待容器构建（约2分钟）

自动发生的事情

当您的代码空间开始时：

1. ✅ 安装依赖项并构建项目
2. ✅ MCP服务器在端口3001的后台自动启动
3. ✅ 端口3001已通过HTTPS公开
4. ✅ MCP配置创建于 /home/codespace/.vscode-remote/data/Machine/mcp.json
5. ✅ MCP设置已启用(chat.mcp.enabled, chat.mcp.discovery.enabled)

MCP服务器URL为： http://localhost:3001/mcp （通过端口转发）

配置GitHub令牌（可选）

对于实时Copilot指标（而不是演示数据），请将您的GitHub令牌添加为Codespace机密：

1. 首选
2. 点击 新机密
3. 姓名： GITHUB_TOKEN
4. 价值：您的PAT manage_billing:copilot, read:enterprise, read:org 范围
5. 存储库访问：选择运行代码空间的存储库
6. 将秘密应用于您的代码空间：

- 如果Codespace尚未运行：只需创建它——秘密将自动可用 - 如果Codespace已在运行首选 ，单击 ... 代码空间上的菜单→ 停止那么 开始 再次 - 从终端快速重启：新闻 Ctrl+Shift+P → “代码空间：停止当前代码空间”，然后重新打开

或者，创建一个 .env Codespace终端中的文件：

echo "GITHUB_TOKEN=your-token-here" > .env
npm start  # Restart the server

验证它是否正常工作

1. MCP服务器在后台自动启动。检查日志：

   cat /tmp/mcp-server.log

您应该看到：

   🧭 Copilot Compass - Codespaces Setup
   ✅ Codespaces detected: your-codespace-name
   ✅ MCP config written to: ~/.vscode-server/data/User/mcp.json
   🚀 Starting MCP server...
   ✅ Port 3001 is now public

1. 打开 港口 选项卡并验证端口3001显示 公共 可见性

- 如果它显示 私人，右键单击该端口→ 港口可见性 → 公共 - 或运行： gh codespace ports visibility 3001:public -c $CODESPACE_NAME

1. MCP服务器现已准备就绪！从副驾驶聊天中使用它——MCP发现功能会自动启用。

手动启动（如果需要）

如果服务器停止或您需要重新启动：

# Quick restart
npm start

# Full setup with config
nohup bash .devcontainer/setup.sh > /tmp/mcp-server.log 2>&1 &

小贴士：只要您的代码空间正在运行，代码空间URL就会一直存在。对于长期使用，可以考虑保持代码空间活动或使用专用VM。

隧道公共通道（当地开发）

要将本地MCP服务器暴露于互联网（可用于共享、移动访问或基于云的MCP客户端），您可以使用隧道服务。

选项1:Cloudflare隧道（推荐）

云雾缭绕 提供免费、安全的隧道和自动HTTPS。

# Install cloudflared (Windows)
winget install cloudflare.cloudflared

# Install cloudflared (macOS)
brew install cloudflared

# Install cloudflared (Linux)
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared

启动隧道：

# In one terminal, start the MCP server
npm start

# In another terminal, create the tunnel
cloudflared tunnel --url http://localhost:3001

Cloudflared输出一个公共URL，如 https://random-words.trycloudflare.com.在MCP客户端配置中使用此选项：

{
  "mcpServers": {
    "copilot-compass": {
      "type": "http",
      "url": "https://random-words.trycloudflare.com/mcp"
    }
  }
}

备注：自由 trycloudflare.com 每次重新启动隧道时，URL都会更改。对于持久URL，设置 命名隧道 拥有自己的域名。

选项2:ngrok

吸烟 是另一种流行的隧道选项，具有免费层。

# Install ngrok
npm install -g ngrok

# Or download from https://ngrok.com/download

启动隧道：

# Start the MCP server
npm start

# In another terminal
ngrok http 3001

ngrok提供了一个类似的URL https://abc123.ngrok.io。相应地更新您的MCP配置。

方案3：尾鳞片漏斗

如果你使用 尾标，您可以使用 漏斗 公开服务。

tailscale funnel 3001

作为后台服务运行

对于生产或持久部署：

使用PM2（Node.js进程管理器）：

# Install PM2
npm install -g pm2

# Start the server
pm2 start dist/server.js --name copilot-compass

# View logs
pm2 logs copilot-compass

# Stop the server
pm2 stop copilot-compass

# Auto-start on system boot
pm2 startup
pm2 save

使用systemd（Linux）：

创建 /etc/systemd/system/copilot-compass.service:

[Unit]
Description=Copilot Compass MCP Server
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/copilot-compass
ExecStart=/usr/bin/node dist/server.js
Restart=on-failure
Environment=GITHUB_TOKEN=your-token
Environment=PORT=3001

[Install]
WantedBy=multi-user.target

然后：

sudo systemctl daemon-reload
sudo systemctl enable copilot-compass
sudo systemctl start copilot-compass

建筑

flowchart TB
    subgraph Host["MCP Host (VS Code, Claude Desktop)"]
        User([User]) --> Model[AI Model]
        Model -->|Tool Call| Server
        Server -->|JSON Report| Model
        Model -->|Summary| Response([Response])
        
        subgraph Dashboard["React Dashboard"]
            useApp["useApp() hook"]
            Charts["Chart.js Visualizations"]
        end
    end
    
    subgraph Server["Copilot Compass Server"]
        Tools["registerAppTool()
        • generate_copilot_report
        • refresh_report"]
        Resources["registerAppResource()
        • ui://copilot-metrics/mcp-app.html"]
        Tools --> Resources
    end
    
    Resources -->|HTML Bundle| Dashboard
    Server -->|ontoolresult| useApp
    
    subgraph GitHub["GitHub API"]
        API["/enterprises/{slug}/copilot/metrics"]
    end
    
    Server -->|Fetch| API
    API -->|Metrics Data| Server

数据流

sequenceDiagram
    participant User
    participant Model as AI Model
    participant Server as MCP Server
    participant API as GitHub API
    participant UI as React Dashboard

    User->>Model: "Generate Copilot report for acme-corp"
    Model->>Server: generate_copilot_report(enterpriseSlug, dateRange)
    Server->>API: GET /enterprises/acme-corp/copilot/metrics
    API-->>Server: CopilotUsageMetrics[]
    Server->>Server: Transform to CopilotReport
    Server-->>Model: JSON Report
    Server-->>UI: ontoolresult(report)
    UI->>UI: Render charts & tables
    Model-->>User: Summary with insights

MCP集成

工具

generate_copilot_report

使用交互式仪表板生成全面的Copilot使用报告。

示例提示：

Generate a Copilot report for enterprise "acme-corp" from 2024-01-01 to 2024-01-31

refresh_report （仅限应用程序）

与上述参数相同，但具有 visibility: ["app"] --对AI隐藏，仅可由UI调用以进行刷新操作。

资源

用法示例

以下是一些常见的提示，以充分利用Copilot Compass：

📸 See example prompt

基本报告生成

Generate a Copilot report for enterprise "acme-corp" from 2024-01-01 to 2024-01-31

月度采用分析

Show me Copilot usage for "my-enterprise" for the last 30 days and highlight adoption trends

组织特定指标

Generate a Copilot report for organization "engineering-team" within enterprise "acme-corp" for Q4 2024

比较时间段

Generate Copilot reports for enterprise "acme-corp" for January and February 2024 and compare the adoption rates

深度分析

Analyze the Copilot report for "acme-corp" and tell me:
1. Which languages have the highest acceptance rates?
2. What's the trend in daily active users?
3. Which editors are most popular?
4. How is Copilot Chat being used?

仪表板见解

AI模型可以分析报告数据并提供以下见解：

• 收养健康：活跃用户是在增长、稳定还是在下降？
• 语言热点：哪些语言从Copilot中受益最大？
• 功能使用：代码完成、聊天和PR摘要之间的平衡
• 编辑器首选项：您的团队更喜欢哪种IDE进行Copilot交互

项目结构

copilot-compass/
├── server.ts                    # MCP server entry (tools + resources)
├── src/
│   ├── types.ts                 # TypeScript interfaces
│   ├── github-client.ts         # GitHub API client with caching
│   ├── report-generator.ts      # Report generation + mock data
│   ├── html-report-generator.ts # Standalone HTML export
│   ├── svg-charts.ts            # Inline SVG for markdown
│   ├── visual-report-generator.ts # Markdown report with charts
│   ├── mcp-app.tsx              # React dashboard entry
│   └── global.css               # Dashboard styles
├── mcp-app.html                 # Vite entry point
├── assets/
│   └── icon.svg                 # Compass icon
├── dist/                        # Build output
├── .env.example                 # Sample environment variables
├── vite.config.ts               # Vite config (singlefile plugin)
├── tsconfig.json                # TypeScript config (React)
└── tsconfig.server.json         # TypeScript config (Node.js)

配置

复制示例环境文件并配置设置：

cp .env.example .env

环境变量

GitHub代币范围

发展

# Watch mode for UI development
npm run dev

# Build for production
npm run build

# Run server (requires build first)
npm start

# Type checking
npx tsc --noEmit

测试

该项目包括一个全面的测试套件，使用 维测试.

运行测试

# Run all tests
npm test

# Run tests in watch mode (re-runs on file changes)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

测试覆盖率

测试结构

tests/
├── setup.ts                  # Global test setup and mocks
├── github-client.test.ts     # API client tests (15 tests)
├── report-generator.test.ts  # Report generator tests (18 tests)
├── svg-charts.test.ts        # Chart generation tests (40 tests)
├── integration.test.ts       # End-to-end pipeline tests (37 tests)
└── fixtures/
    └── api-responses.ts      # Realistic GitHub API response fixtures

总计：110次测试

测试内容

• GitHub API客户端：令牌验证、企业/组织端点、缓存行为、错误处理
• 报告生成器：实时数据转换、模拟数据回退、汇总聚合、边缘案例
• SVG图表：条形图、折线图、圆环图、水平条形图和火花线图生成
• 模式验证：Zod架构解析、API响应验证、错误格式化
• 集成管道：端到端数据流，具有企业和组织指标的现实夹具

API响应验证

该项目使用Zod模式在运行时验证GitHub API响应，确保数据完整性：

// Validation is automatic - errors are thrown if API response is malformed
const metrics = await client.getEnterpriseMetrics('my-enterprise', dateRange);

可以禁用性能验证（不建议）：

VALIDATE_API_RESPONSES=false npm start

故障排除

常见问题

“GitHub API错误（403）：资源不可访问”

原因：您的GitHub令牌缺少所需的作用域。

解决方案：使用以下范围创建新的PAT：

• manage_billing:copilot （必填）
• read:enterprise 用于企业度量
• read:org 用于组织度量

“GitHub API错误（404）：找不到”

原因：企业slug或组织名称不存在，或者您没有访问权限。

解决方案:

1. 在GitHub设置中验证企业/组织名称
2. 确保您的帐户具有复制业务/企业访问权限
3. 检查您是否是该组织的成员

仪表板显示“演示数据”/模拟数据

原因：GitHub API调用失败，因此应用程序返回到演示数据。

解决方案:

1. 检查服务器日志中的API错误消息
2. 验证您的 GITHUB_TOKEN 环境变量已设置
3. 确保令牌具有正确的作用域
4. 尝试较短的日期范围（API每次请求最多返回28天）

服务器无法启动/端口已在使用中

解决方案:

# Find and kill the process using port 3001
npx kill-port 3001

# Or use a different port
PORT=3002 npm start

MCP客户端中“找不到工具”

原因：MCP客户端尚未连接到服务器或需要刷新。

解决方案:

1. 重新启动MCP服务器
2. 重新加载/重新启动MCP客户端（VS Code，Claude Desktop）
3. 检查MCP配置中的服务器URL

TypeScript编译错误

解决方案:

# Clean build artifacts and rebuild
rm -rf dist && npm run build

调试模式

启用详细日志记录以诊断问题：

DEBUG=* npm start

常见问题解答

GitHub Copilot支持哪些计划？

Copilot Compass适用于：

• 复印机业务 --组织级访问
• 企业版副驾驶 --企业+组织级访问

单个Copilot Pro订阅无法访问指标API。

我可以查询多久以前的数据？

GitHub API返回到 每次请求28天的数据。对于较长的时间段，该应用程序会自动处理分页。历史数据可从您的组织启用Copilot时获得。

API响应是否已缓存？

是的，响应已缓存 5分钟 （可通过以下方式配置 CACHE_TTL_SECONDS).这减少了重复查询或仪表板刷新期间的API调用。

我可以在没有GitHub令牌的情况下运行它吗？

是的，用于演示。如果没有提供令牌或API失败，应用程序将返回到真实的模拟数据。寻找 dataSource: "mock" 在报告中。

企业报告和组织报告有什么区别？

• 企业：企业中所有组织的汇总指标
• 组织：仅针对特定组织的指标

我该如何解读录取率？

• ≥40%：太好了——副驾驶显著提高了生产率
• 25-40%：很好——开发人员正在发现建议的价值
• **\MCP Apps SDK