用 awesome-copilot-mcp 把官方资源库接进 Agent：stdio 配置、MCP Inspector 调试、HTTP 端点与 refresh_metadata 热更新实操

# 核对本机运行时（包要求 Node >=20.0.0）
node --version
npm --version

# 查 npm 上的当前版本与元数据（不安装）
npm view awesome-copilot-mcp version
npm view awesome-copilot-mcp engines
npm view awesome-copilot-mcp license
npm view awesome-copilot-mcp bin

# 查看 CLI 支持哪些子命令，用来裁决 start 参数之争
npx -y awesome-copilot-mcp --help

# 审阅包来源（浏览器打开也可以）
# https://github.com/RbBtSn0w/awesome-copilot-mcp
# 重点看：README.md、LICENSE、package.json 的 scripts

# 文件：你的 MCP 客户端配置（如 claude_desktop_config.json）
{
  "mcpServers": {
    "awesome-copilot": {
      "command": "npx",
      "args": ["-y", "awesome-copilot-mcp", "start"]
    }
  }
}

# 若本地 --help 显示不需要 start 子命令，改用这个写法
# "args": ["-y", "awesome-copilot-mcp"]

# 想锁版本时（团队 / CI 推荐）
# "args": ["-y", "[email protected]", "start"]

# 改完配置后重启客户端，让它重新拉起 MCP 进程
# 在客户端里问一句：列出 awesome-copilot 这个服务提供的工具
# 预期：能看到资源检索相关工具与 refresh_metadata

# 路线 A：stdio 调试（README 推荐，发布包自带 dist）
npx -y awesome-copilot-mcp debug --no-build

# 路线 B：HTTP 调试，需要先克隆仓库并装好开发依赖
git clone https://github.com/RbBtSn0w/awesome-copilot-mcp.git
cd awesome-copilot-mcp
npm install
npm run build
npm run inspect:http

# 对应的 stdio 开发脚本
npm run inspect:stdio

# 在 Inspector 里重点核对
# 1. 工具清单里是否有 refresh_metadata
# 2. 8 类资源是否都能作为资源或工具被列出
# 3. 调一次搜索类工具，看返回结构里有没有下载地址字段

# 官方 README 的示例（注意 host 是 0.0.0.0）
npx -y awesome-copilot-mcp start-http --port 8080 --host 0.0.0.0

# 本地调试建议改绑回环地址
npx -y awesome-copilot-mcp start-http --port 8080 --host 127.0.0.1

# 另开一个终端，逐个验端点
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/metadata
curl "http://127.0.0.1:8080/search?q=agent"
curl http://127.0.0.1:8080/openapi.json

# SSE 流式输出（用 -N 保持连接，按 Ctrl+C 退出）
curl -N http://127.0.0.1:8080/metadata/stream

# 用完记得停掉服务，别把端口一直开着
# Ctrl+C 结束前台进程

# 在 Agent 或 Inspector 里调用（官方 README 给出的工具名）
# refresh_metadata  —— 从 GitHub 拉最新数据，存到当前会话内存

# 环境变量（官方 README）
# ACP_METADATA_URL  可选，指向托管的 metadata.json
#                   例如 https://yourname.github.io/repo/metadata.json
#                   设置后覆盖 GitHub raw 拉取
# ACP_REPOS_JSON    自定义仓库配置 JSON

# 验热更新是否生效：调用前后各查一次
curl "http://127.0.0.1:8080/search?q=skill"
# 在客户端里调用 refresh_metadata 后再查同一个关键词
curl "http://127.0.0.1:8080/search?q=skill"

# 注意：进程重启后回到包内自带的 metadata.json
# 需要长期用新数据时，等新 npm 版本或自己托管 metadata.json

# 在已接好 MCP 的客户端里下达一句任务，例如：
# 「用 awesome-copilot 找一份适合做代码审查的 agent，
#   列出名字、来源与内容地址，先不要写入我的项目」

# 核对返回里是否有资源类型与下载地址，再决定是否落地
# 落地前先留可回滚状态
git status --short
git log -1 --oneline

# 升级：先查新版本，再改锁定的版本号并重跑验收
npm view awesome-copilot-mcp version
# "args": ["-y", "awesome-copilot-mcp@新版本", "start"]
# 重启客户端 → 让 Agent 复述工具清单 → 重新搜同一个关键词

# 回退：把 args 里的版本改回 0.8.8，重启客户端
git diff --stat

# 卸载：从客户端配置的 mcpServers 里删掉 awesome-copilot 这一项
# 若克隆过仓库做开发调试，再删掉克隆目录与占用 8080 的进程