项目概述与核心目标

claude-skills-mcp 是由 K-Dense AI 维护的开源 Model Context Protocol（MCP）服务器，目标是让任何 MCP 兼容的 AI 助手（Cursor、Codex、Claude Desktop、Windsurf 等）都能以向量语义检索的方式发现并加载 Claude Agent Skills README.md:1-30。仓库采用 monorepo 双包架构，将轻量 MCP 代理与重型 RAG 检索引擎解耦，从而在客户端超时窗口内完成启动并按需扩展。

核心特性包括：开箱即用地加载 Anthropic 官方技能集与 K-Dense 自身的科学技能集、支持 GitHub 与本地双数据源、本地嵌入模型无需 API 密钥、可自定义内容长度与图像大小 README.md:7-30。版本协调通过仓库根目录的 VERSION 文件统一管理，scripts/sync-version.py 负责把版本号同步到前后端包的 pyproject.toml、__init__.py、HTTP 健康端点以及 CI 工作流中 scripts/sync-version.py:1-30。

双包架构设计

整套系统拆分为两个独立可分发的 PyPI 包：claude-skills-mcp（frontend，约 15 MB）与 claude-skills-mcp-backend（backend，约 250 MB）packages/frontend/README.md:1-15, packages/backend/README.md:5-20。Frontend 体积小、启动快（<5 秒），承担 stdio MCP 协议端角色并即时返回工具 schema；Backend 包含 PyTorch、sentence-transformers、FastAPI/uvicorn 等重型依赖，负责实际的嵌入索引与语义搜索 packages/backend/README.md:25-45。

flowchart LR
    IDE[MCP 客户端<br/>Cursor / Codex / Claude Desktop] -->|stdio JSON-RPC| FE[claude-skills-mcp<br/>Frontend Proxy]
    FE -->|按需后台拉取| PyPI[PyPI claude-skills-mcp-backend]
    FE -->|Streamable HTTP /mcp| BE[claude-skills-mcp-backend<br/>FastAPI 服务]
    BE -->|sentence-transformers| EMB[all-MiniLM-L6-v2<br/>本地嵌入模型]
    BE -->|httpx + GitHub API| GH[anthropics/skills<br/>K-Dense-AI/claude-scientific-skills]
    BE -->|本地路径| LOCAL[~/.claude/skills]
    BE -->|/health| HC[健康检查端点]

Frontend 在首次调用工具时会触发后台下载 backend，Cursor 等客户端先于网络就绪就拿到工具清单，因此可以避免超时 packages/frontend/README.md:25-45。Backend 通过 config.py 中的 DEFAULT_CONFIG 定义默认数据源、嵌入模型、文本与图像扩展名白名单等 packages/backend/src/claude_skills_mcp_backend/config.py:1-30。Frontend 与 Backend 之间通过 localhost:8765/mcp 的 Streamable HTTP 协议通信，并提供 /health 健康端点用于存活探测 packages/backend/README.md:55-65。

MCP 工具接口与数据流

Backend 在 http_server.py 中注册了三个 MCP 工具：find_helpful_skills、read_skill_document、list_skills packages/backend/src/claude_skills_mcp_backend/http_server.py:1-40。find_helpful_skills 接收 task_description、top_k（默认 3）、list_documents（默认 True）三参数，由 mcp_handlers.py 中的 handle_search_skills 调度底层搜索引擎 packages/frontend/src/claude_skills_mcp/mcp_proxy.py:1-40, packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py:1-30。

read_skill_document 支持通配符匹配（如 scripts/*.py），对文本文件返回内容、对图像默认只返回 URL（可通过 include_base64=true 改为 base64 编码），5MB 以上图像会自动切换为 URL 模式以避免上下文爆炸 packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py:30-80, config.example.json:1-15。list_skills 返回当前已加载的完整技能清单（名称、描述、来源、文档数量），便于调试与浏览 packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py:1-20。

技能加载流程由 skill_loader.py 统一处理：GitHub 源通过 tree API 枚举文件并按白名单扩展名构建文档元数据，本地源直接遍历目录 packages/backend/src/claude_skills_mcp_backend/skill_loader.py:1-40, packages/backend/src/claude_skills_mcp_backend/skill_loader.py:60-90。update_checker.py 则通过比对 GitHub commit SHA 跟踪仓库变更，默认每小时检查一次，配合本地状态文件避免触发未授权的 API 配额 packages/backend/src/claude_skills_mcp_backend/update_checker.py:1-30, config.example.json:1-15。

已知问题与部署注意事项

社区反馈显示该架构在某些环境下仍存在兼容性问题。Windows 10 上首次启动 Backend 会因依赖下载超时（issue #4）而失败，团队正在持续修复 issue #4。macOS x86_64 (Intel) 设备因 PyTorch 没有兼容的预编译 wheel 导致 Backend 安装失败（issue #13）issue #13。在自定义端口场景下，Frontend 与 Backend 都默认监听 8765，可能出现 address already in use 冲突（issue #12），建议显式指定 --port 并先确认端口空闲 issue #12。Codex 等部分客户端在 UI 上显示 No MCP tools available，但实际 list_skills 等工具仍可调用（issue #11），属于发现层兼容差异 issue #11。Windsurf、ai-agent-skills 等第三方集成也已开启讨论，验证该架构在更广 AI 工具链中的可移植性 issue #5, issue #7。

See Also

• Getting Started — 安装、Cursor 配置与 CLI 用法
• Architecture Guide — 模块依赖与组件交互详解
• Configuration Reference — config.json 字段说明与默认值
• Tool Reference — find_helpful_skills / read_skill_document / list_skills 完整参数文档

概述

Claude Skills MCP 是一个基于 Model Context Protocol 的服务器，旨在让任何兼容 MCP 的 AI 助手（包括 Cursor、Codex、GPT-5、Gemini 等）能够通过向量语义搜索发现并加载 Anthropic 的 Agent Skills 资料库。其核心功能围绕三个 MCP 工具构建：语义搜索、技能文档读取以及技能清单列举。

系统采用前后端分离的轻量化设计：前端 claude-skills-mcp（约 15 MB）作为 stdio 代理在 5 秒内快速启动并向 Cursor 注册工具 schema，后端 claude-skills-mcp-backend（约 250 MB）在后台异步下载并加载 PyTorch / sentence-transformers 依赖 资料来源：packages/frontend/README.md。当前最新版本为 v1.0.6 资料来源：packages/backend/src/claude_skills_mcp_backend/__init__.py:3。

MCP 工具参考

三个核心 MCP 工具分别在 http_server.py 中通过 @mcp.tool 装饰器注册，并在前端 mcp_proxy.py 中镜像定义 schema，使 IDE 在后端尚未就绪时也能立即看到工具列表 资料来源：packages/backend/src/claude_skills_mcp_backend/http_server.py:14-66。

1. `find_helpful_skills` — 语义搜索

该工具是首要入口，建议在任何任务开始时优先调用。底层使用 all-MiniLM-L6-v2 sentence-transformers 模型对 task_description 计算嵌入向量，并在已加载技能语料上做余弦相似度排序 资料来源：packages/backend/src/claude_skills_mcp_backend/config.py:19。

资料来源：packages/frontend/src/claude_skills_mcp/mcp_proxy.py:5-25。

2. `read_skill_document` — 读取技能文档与资源

在 find_helpful_skills 命中相关技能后调用。支持 glob 模式（如 scripts/*.py）批量获取文本、图片、参考资料。该工具永远不会执行代码，仅返回文本内容或资源 URL 资料来源：packages/backend/src/claude_skills_mcp_backend/http_server.py:39-58。

资料来源：packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py:21-46。

3. `list_skills` — 列举全部已加载技能

返回完整技能清单（名称、描述、来源、文档数量），用于调试或探索。对于任务驱动的场景，仍建议优先使用 find_helpful_skills 资料来源：packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py:48-57。

架构与数据流

flowchart LR
    A[MCP 客户端<br/>Cursor / Codex / Claude Desktop] -->|stdio JSON-RPC| B[Frontend<br/>claude-skills-mcp]
    B -->|Streamable HTTP| C[Backend<br/>claude-skills-mcp-backend]
    C --> D[Search Engine<br/>sentence-transformers]
    C --> E[Skill Loader<br/>GitHub + Local]
    C --> F[Update Checker<br/>commit SHA 跟踪]
    E --> G[(GitHub Repos<br/>anthropics/skills<br/>K-Dense-AI/claude-scientific-skills)]
    E --> H[(Local: ~/.claude/skills)]
    F --> G
    D -->|top-k 结果| A
    C -->|text/URL| A

关键时序要点：

• 后端懒启动：前端启动时立刻返回工具 schema（满足 Cursor 5 秒超时），后端在后台线程中按 batch_size（默认 10）分批加载技能并通过回调注入搜索引擎 资料来源：packages/backend/src/claude_skills_mcp_backend/http_server.py:78-103。
• GitHub 资源发现：通过 GitHub tree API 列出仓库文件，按 text_extensions 与 image_extensions 过滤，SKILL.md 自身被跳过作为元数据 资料来源：packages/backend/src/claude_skills_mcp_backend/skill_loader.py:33-66。
• 自动更新检测：update_checker.py 通过提交 SHA 对比判断 GitHub 源是否有变更；可选 github_api_token 可将限额从 60 req/hr 提升至 5000 req/hr 资料来源：packages/backend/src/claude_skills_mcp_backend/update_checker.py:8-58。

关键配置项

config.example.json 暴露了用户最常调整的旋钮：

资料来源：config.example.json 与 packages/backend/src/claude_skills_mcp_backend/config.py:10-39。

CLI 用法：claude-skills-mcp --example-config > config.json 生成模板，--config config.json 应用自定义配置 资料来源：README.md。

已知问题与社区讨论

• Windows 后端启动超时（Issue #4）：用户报告在 Windows 10 + Claude Desktop 与 uvx claude-skills-mcp 下后端无法加载。维护者表示正在排查，建议结合后端 README 的 verbose 日志进行诊断 资料来源：packages/backend/README.md。
• macOS x86_64 (Intel) PyTorch 兼容性（Issue #13）：Intel Mac 上后端因 PyTorch 缺失兼容 wheel 而启动失败；社区建议关注 issue 跟踪的替代安装路径。
• 自定义 --port 与端口占用（Issue #12）：在某些 MCP 客户端中 address already in use 反复出现，前端自定义端口并不总能避免后端冲突；默认后端监听 8765，健康检查位于 /health，MCP 端点位于 /mcp 资料来源：packages/backend/README.md。
• Codex 工具发现显示异常（Issue #11）：Codex UI 显示 No MCP tools available，但 list_skills 等调用实际可用——属于客户端侧的发现/注册兼容问题。
• 多 IDE 接入：项目被列在 CodeGuilds 注册表；社区已就 Windsurf 接入 与 ai-agent-skills npm 安装器 的互操作展开讨论，理论上任何标准 MCP 客户端均可使用。

最佳实践小结

1. 始终先调用 find_helpful_skills——其描述明确要求"在任何动作之前先调用以获取最佳方法" 资料来源：packages/backend/src/claude_skills_mcp_backend/http_server.py:15-23。
2. 首次启动预留 60-120 秒给后端依赖下载与技能索引；之后查询响应 < 1 秒 资料来源：packages/backend/README.md。
3. 仅按需 read_skill_document——为节约上下文窗口，使用 glob 仅拉取当前步骤所需文件。
4. 生产环境配置 github_api_token 以避免未认证状态下的 60 req/hr 限制 资料来源：packages/backend/src/claude_skills_mcp_backend/config.py:33-37。

See Also

• Getting Started — 安装与 Cursor 快速接入
• Architecture Guide — 前后端分离设计的完整说明
• Anthropic Agent Skills Engineering Blog — 渐进式披露（progressive disclosure）架构原型
• Model Context Protocol — 协议规范

概述与目的

claude-skills-mcp 是一个基于 Model Context Protocol (MCP) 的服务器，让任何兼容 MCP 的 AI 助手能够通过向量嵌入与语义相似度搜索，从一个精心策划的 Claude Agent Skills 库中智能检索相关技能。本页聚焦于该系统的三个核心支撑面：配置体系（决定加载哪些技能、如何索引、如何限制返回内容）、技能源（Skill Sources）（GitHub 仓库与本地目录的拉取策略）以及完整的数据流（从配置读取到 MCP 工具调用）。

系统采用前后端分离架构：轻量前端 (claude-skills-mcp) 作为 stdio MCP 服务器立即向客户端返回工具 schema，而重型后端 (claude-skills-mcp-backend) 在后台按需下载并启动，负责实际加载、嵌入、索引与检索逻辑。资料来源：README.md、packages/frontend/README.md。

配置体系

默认配置与文件格式

后端在 packages/backend/src/claude_skills_mcp_backend/config.py 中定义了 DEFAULT_CONFIG 字典，作为内置默认值。顶层键包括：skill_sources、embedding_model、default_top_k、max_skill_content_chars、load_skill_documents、max_image_size_bytes、allowed_image_extensions、text_file_extensions、auto_update_enabled 与 auto_update_interval_minutes、github_api_token 等。资料来源：config.py:DEFAULT_CONFIG。

用户可通过 CLI 导出示例配置：

uvx claude-skills-mcp --example-config > config.json
uvx claude-skills-mcp --config config.json

config.example.json 提供了带注释的完整样例，便于按需裁剪。资料来源：README.md:Quick Start、config.example.json。

关键配置项

资料来源：config.example.json、config.py:DEFAULT_CONFIG。

技能源加载机制

来源类型

skill_loader.py 中的加载逻辑依据 type 字段分支：github 类型调用 load_from_github(url, subpath, config)，从 GitHub API 拉取仓库树；local 类型调用 load_from_local(path, config)，扫描指定目录。所有技能最终汇总到 all_skills 列表。资料来源：skill_loader.py:load_skills。

文档收集策略

Skill 数据类承载 name、description、content（来自 SKILL.md）、source、documents 等字段。文档收集阶段遍历 GitHub tree 中的 blob，过滤 SKILL.md 自身并按扩展名分类：文本文件（text_extensions）与图片文件（image_extensions）存储元数据与可访问的 raw.githubusercontent.com URL；图片超过 max_image_size_bytes 时仅保留 URL。资料来源：skill_loader.py:Skill、skill_loader.py:_collect_documents_metadata。

批量与回调加载

load_skills_in_batches() 支持按 batch_size（默认 10）增量加载，并通过 batch_callback(batch_skills, total_loaded) 回调触发渐进式索引，保证大量技能时仍能流式输出。资料来源：skill_loader.py:load_skills_in_batches。

数据流与生命周期

下图描绘了从配置文件到 MCP 工具调用的完整数据流：

flowchart LR
    A[config.json / DEFAULT_CONFIG] --> B[config.py 解析]
    B --> C[skill_loader.py 拉取源]
    C -->|GitHub API| D[GitHubSourceTracker]
    C -->|local path| E[本地目录扫描]
    D --> F[Skill 列表 + 文档元数据]
    E --> F
    F --> G[sentence-transformers 嵌入]
    G --> H[向量索引 / SearchEngine]
    I[MCP Client 调用 find_helpful_skills] --> J[mcp_handlers.py 路由]
    J --> K[SearchEngine 语义检索]
    K --> L[Top-K Skill 命中]
    L --> M[返回 TextContent 给前端]
    M --> N[mcp_proxy.py stdio 转 HTTP]

具体路径上：HTTP 服务器在 packages/backend/src/claude_skills_mcp_backend/http_server.py 中通过 @mcp.tool 注册 find_helpful_skills、read_skill_document、list_skills 三个工具，调用进入 mcp_handlers.py 的 call_tool() 分发器，再由 _handle_search_skills、_handle_read_skill_document、list_skills 三个处理器与 SearchEngine 交互。前端 packages/frontend/src/claude_skills_mcp/mcp_proxy.py 立即暴露相同的工具 schema，使 Cursor/Codex/Windsurf 等 MCP 客户端无需等待后端启动即可见到工具。资料来源：http_server.py:tool decorators、mcp_handlers.py:Tool schemas。

自动更新与社区已知问题

update_checker.py 中的 UpdateResult 数据类聚合 has_updates、changed_sources、api_calls_made、errors 字段；GitHubSourceTracker 通过 state_manager.StateManager("github_tracker") 持久化 commit SHA，每小时比对一次（受 auto_update_interval_minutes 控制）。scheduler.py 据此周期性触发再索引。资料来源：update_checker.py:UpdateResult、update_checker.py:GitHubSourceTracker。

社区中与本页主题相关的几个常见问题：

• Windows 后端超时（Issue #4）：在 Windows 10 下经 Claude Desktop 或 uvx 启动时后端加载超时，与配置无关，属平台兼容问题。
• macOS x86_64 安装失败（Issue #13）：后端因 PyTorch 在 Intel Mac 上无兼容 wheel 而失败，解决方案为替换 embedding_model（如更小的句向量模型）或自编译 PyTorch。
• 端口冲突（Issue #12）：默认 8765/8766 端口在 MCP 客户端自定义 --port 时未与后端协同，可能触发 address already in use。
• Codex 工具未列出（Issue #11）：尽管 find_helpful_skills 可调用，Codex MCP 面板显示 No MCP tools available，属客户端发现兼容性问题。
• 认证方式（Issue #16）：当前未在 find_helpful_skills 上强制鉴权，团队部署需自建网关层。

资料来源：update_checker.py、Issue #4、Issue #11、Issue #12、Issue #13、Issue #16。

See Also

• Architecture Guide
• Getting Started
• Backend README
• Frontend README
• MCP 协议规范
• Claude Agent Skills 工程博客

一、部署架构概览

Claude Skills MCP 采用前后端分离的双包架构，前端为轻量 MCP 代理，后端为重型向量检索服务。该架构的核心理念是「让 Cursor、Codex 等 MCP 客户端在数秒内拿到工具列表，同时将 ~250 MB 的 PyTorch/sentence-transformers 依赖放在后台按需拉取」 资料来源：README.md:60-75。

flowchart LR
    A[MCP 客户端<br/>Cursor / Codex / Claude Desktop] -->|stdio| B[前端 claude-skills-mcp<br/>~15 MB]
    B -->|HTTP /mcp| C[后端 claude-skills-mcp-backend<br/>~250 MB]
    C -->|sentence-transformers| D[(all-MiniLM-L6-v2<br/>向量索引)]
    C -->|GitHub API / 本地| E[技能源<br/>anthropics/skills 等]

后端通过 FastMCP 暴露 Streamable HTTP 端点 http://localhost:8765/mcp 以及 /health 健康检查 资料来源：packages/backend/README.md:50-55。前端在第一次收到工具调用时会自动启动子进程托管后端，并对 Cursor 的启动超时形成缓冲 资料来源：packages/frontend/README.md:25-40。

二、部署方式

2.1 标准客户端安装（推荐）

最简方式是通过 uvx 触发一次性沙箱，由前端按需下载后端 资料来源：README.md:70-75：

uvx claude-skills-mcp

在 Cursor 中，只需将以下片段写入 ~/.cursor/mcp.json 即可完成注册 资料来源：README.md:55-65：

{
  "mcpServers": {
    "claude-skills": {
      "command": "uvx",
      "args": ["claude-skills-mcp"]
    }
  }
}

2.2 远程 / 自托管后端

当需要在内网或云端集中托管后端时，应显式安装 claude-skills-mcp-backend 并暴露 HTTP 端口 资料来源：packages/backend/README.md:30-45：

uv tool install claude-skills-mcp-backend
claude-skills-mcp-backend --host 0.0.0.0 --port 8080

2.3 Docker 部署

后端仓库自带 Dockerfile，可通过以下命令构建镜像并以 8765 对外暴露 资料来源：packages/backend/README.md:60-75：

docker build -t claude-skills-mcp-backend .
docker run -p 8080:8765 -e HOST=0.0.0.0 claude-skills-mcp-backend

首次启动时需要从网络下载 PyTorch 与 sentence-transformers，预估耗时 60–180 秒，部署脚本应配置就绪探针 资料来源：packages/backend/README.md:80-90。

三、运维配置

核心配置由 packages/backend/src/claude_skills_mcp_backend/config.py 中的 DEFAULT_CONFIG 定义，可通过 --config <file> 覆盖 资料来源：packages/backend/src/claude_skills_mcp_backend/config.py:8-58。下表列出关键配置项。

更新检测逻辑由 UpdateChecker 与 GitHubSourceTracker 实现，通过比对 commit SHA 判断变更，避免重复抓取 资料来源：packages/backend/src/claude_skills_mcp_backend/update_checker.py:1-60。当配置 auto_update_enabled=true 时，后端会按 auto_update_interval_minutes 周期轮询 GitHub；不提供 token 则受限于 60 次/小时匿名额度 资料来源：packages/backend/src/claude_skills_mcp_backend/config.py:50-58。

版本管理由根目录 VERSION 文件集中维护，scripts/sync-version.py 会将版本号同步至前后端 pyproject.toml、__init__.py、健康检查端点以及 CI 工作流 资料来源：scripts/sync-version.py:1-60。

四、常见故障与排查

4.1 Windows 启动超时

社区报告在 Windows 10 通过 uvx claude-skills-mcp 或 Claude Desktop 调用时出现超时（issue #4）。根本原因是 PyTorch 在 Windows 上体积庞大，加载耗时超出 MCP 客户端默认握手窗口。临时缓解策略是直接安装持久化后端包，避免每次重启都重新解析依赖 资料来源：README.md:95-110。

4.2 macOS x86_64 (Intel) 安装失败

issue #13 反馈在 Intel Mac + Python 3.12 + uvx 环境下后端依赖解析失败，原因为 PyTorch 不再为 macOS x86_64 发布兼容 wheel。规避方式是改用 Apple Silicon 主机、conda-forge 的 PyTorch 构建，或在远端 Linux 主机运行后端再通过 HTTP 反向代理 资料来源：packages/backend/README.md:80-95。

4.3 端口冲突

issue #12 指出当用户传入自定义 --port 时，前端与后端的端口分配可能错位（如 8765/8766 同时被占用）。后端默认监听 8765；若需要修改，必须同时确认前端 MCP 客户端的连接配置 资料来源：packages/backend/src/claude_skills_mcp_backend/http_server.py:1-60、packages/frontend/src/claude_skills_mcp/mcp_proxy.py:1-60]()。

4.4 MCP 客户端发现异常

Codex 在面板显示「No MCP tools available」但底层 list_skills 仍可调用（issue #11），属于客户端 UI 与 stdio 工具注册之间的兼容问题，并非服务端缺陷。Windsurf 用户（issue #5）则被建议优先验证 claude-skills-mcp 命令在终端能否独立启动，再在 IDE MCP 设置中复用同一行配置 资料来源：README.md:55-75`。

4.5 自动更新失败

启用 auto_update_enabled 后若长时间无新技能，需检查 GitHubSourceTracker 日志。匿名模式每小时仅 60 次请求，频繁重启进程会消耗额度；配置 github_api_token 可将上限提升至 5000 次/小时 资料来源：packages/backend/src/claude_skills_mcp_backend/update_checker.py:30-60`。

另请参阅

• 快速上手与 Cursor 集成：README.md
• 后端独立部署与 Docker：packages/backend/README.md
• 前端代理行为：packages/frontend/README.md
• 配置项参考：packages/backend/src/claude_skills_mcp_backend/config.py
• 版本发布流程：scripts/sync-version.py

Pitfall Log / 踩坑日志

项目：k-dense-ai/claude-skills-mcp

摘要：发现 30 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：Add Windows Support (timeout as of now)。

1. 配置坑 · 来源证据：Add Windows Support (timeout as of now)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add Windows Support (timeout as of now)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_89d42546abe14de4920a1710883f0c21 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/4 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：Integration with ai-agent-skills

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration with ai-agent-skills
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b675c30cf1f247968d5423dc667787d8 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/7 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

3. 安装坑 · 失败模式：installation: Backend fails to install on macOS x86_64 (Intel) — PyTorch has no compatible wheels

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Backend fails to install on macOS x86_64 (Intel) — PyTorch has no compatible wheels
• 对用户的影响：Developers may fail before the first successful local run: Backend fails to install on macOS x86_64 (Intel) — PyTorch has no compatible wheels
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Backend fails to install on macOS x86_64 (Intel) — PyTorch has no compatible wheels. Context: Observed when using python, windows, macos, linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_db8b3d22ee0758dad0bf51ec4c8896a9 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/13 | Backend fails to install on macOS x86_64 (Intel) — PyTorch has no compatible wheels

4. 安装坑 · 失败模式：installation: Integration with ai-agent-skills

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Integration with ai-agent-skills
• 对用户的影响：Developers may fail before the first successful local run: Integration with ai-agent-skills
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Integration with ai-agent-skills. Context: Observed when using node
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_002c29655ab3908a3ee515b54df2ce0b | https://github.com/K-Dense-AI/claude-skills-mcp/issues/7 | Integration with ai-agent-skills

5. 安装坑 · 来源证据：Backend fails to install on macOS x86_64 (Intel) — PyTorch has no compatible wheels

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Backend fails to install on macOS x86_64 (Intel) — PyTorch has no compatible wheels
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_10247512c34842958321501a9c716683 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/13 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：Your project is now listed on CodeGuilds

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your project is now listed on CodeGuilds
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_85a8d45a7a1c48248e5c29b0d1d10337 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/17 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

7. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | host_targets=mcp_host, claude, claude_code, cursor

8. 配置坑 · 失败模式：configuration: Codex shows 'No MCP tools available' while claude-skills tools are callable

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Codex shows 'No MCP tools available' while claude-skills tools are callable
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Codex shows 'No MCP tools available' while claude-skills tools are callable
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Codex shows 'No MCP tools available' while claude-skills tools are callable. Context: Observed when using python, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_9c0155406f689e1323dda4ddef20ea06 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/11 | Codex shows 'No MCP tools available' while claude-skills tools are callable

9. 配置坑 · 失败模式：configuration: Port conflict on startup (address already in use) with custom frontend --port in MCP clients

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Port conflict on startup (address already in use) with custom frontend --port in MCP clients
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Port conflict on startup (address already in use) with custom frontend --port in MCP clients
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Port conflict on startup (address already in use) with custom frontend --port in MCP clients. Context: Observed when using python, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_d7242c7ea6c8b750e59ca7cd18464f49 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/12 | Port conflict on startup (address already in use) with custom frontend --port in MCP clients

10. 配置坑 · 失败模式：configuration: Question about auth approach

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Question about auth approach
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Question about auth approach
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Question about auth approach. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_63c4fc984cbeb30d50abef9502dd3aea | https://github.com/K-Dense-AI/claude-skills-mcp/issues/16 | Question about auth approach

11. 配置坑 · 来源证据：Port conflict on startup (address already in use) with custom frontend --port in MCP clients

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Port conflict on startup (address already in use) with custom frontend --port in MCP clients
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0ca57a9e8e754554b9ae966c4a2c0dec | https://github.com/K-Dense-AI/claude-skills-mcp/issues/12 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

12. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | README/documentation is current enough for a first validation pass.

13. 运行坑 · 失败模式：runtime: Add Windows Support (timeout as of now)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: Add Windows Support (timeout as of now)
• 对用户的影响：Developers may hit a documented source-backed failure mode: Add Windows Support (timeout as of now)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Add Windows Support (timeout as of now). Context: Observed when using windows, linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_ff4e435ee429aad947d25a62410876cb | https://github.com/K-Dense-AI/claude-skills-mcp/issues/4 | Add Windows Support (timeout as of now)

14. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | last_activity_observed missing

15. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | no_demo; severity=medium

16. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | no_demo; severity=medium

17. 安全/权限坑 · 来源证据：Codex shows 'No MCP tools available' while claude-skills tools are callable

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Codex shows 'No MCP tools available' while claude-skills tools are callable
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_cbafe3bac49247aa8900be1a6e34c3eb | https://github.com/K-Dense-AI/claude-skills-mcp/issues/11 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：Question about auth approach

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Question about auth approach
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6267b73e491e42e69f90275aa253bda6 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/16 | 来源类型 github_issue 暴露的待验证使用条件。

19. 能力坑 · 失败模式：capability: Windsurf support

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Windsurf support
• 对用户的影响：Developers may hit a documented source-backed failure mode: Windsurf support
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windsurf support. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_ed97ee5ef96f0f27d7bb2d0f54c4e616 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/5 | Windsurf support

20. 能力坑 · 失败模式：capability: Your project is now listed on CodeGuilds

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Your project is now listed on CodeGuilds
• 对用户的影响：Developers may hit a documented source-backed failure mode: Your project is now listed on CodeGuilds
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Your project is now listed on CodeGuilds. Context: Observed when using node
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_71175af6da91fe6c1176b8001cab641f | https://github.com/K-Dense-AI/claude-skills-mcp/issues/17 | Your project is now listed on CodeGuilds

21. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | issue_or_pr_quality=unknown

22. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | release_recency=unknown

23. 维护坑 · 失败模式：maintenance: v0.1.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.1.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.1
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.1.1. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_4d307b2134a9a0ea9555454484cc48ac | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v0.1.1 | v0.1.1

24. 维护坑 · 失败模式：maintenance: v0.1.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.1.2
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.2
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.1.2. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_35d0e8f219646a00a0a1bdd7ad1e3d91 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v0.1.2 | v0.1.2

25. 维护坑 · 失败模式：maintenance: v1.0.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.0.0. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_fa8597f9b9050af664a3c68d881633da | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.0 | v1.0.0

26. 维护坑 · 失败模式：maintenance: v1.0.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.1
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.1
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.0.1. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_215164d49601bf6aef9bd77c7d07235f | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.1 | v1.0.1

27. 维护坑 · 失败模式：maintenance: v1.0.3

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.3
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.3
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.0.3. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_20cfef5f8d0b08f066632c50a4dd9509 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.3 | v1.0.3

28. 维护坑 · 失败模式：maintenance: v1.0.4

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.4
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.4
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.0.4. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_336feaca823117608f5da5dfd3535d63 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.4 | v1.0.4

29. 维护坑 · 失败模式：maintenance: v1.0.5

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.5
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.5
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.0.5. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_5947dd5ffe9055bc7e33bf96e8603142 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.5 | v1.0.5

30. 维护坑 · 失败模式：maintenance: v1.0.6

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.6
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.6
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.0.6. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_ff9001a368987158a758726da568c572 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.6 | v1.0.6