# https://github.com/K-Dense-AI/claude-skills-mcp 项目说明书

生成时间：2026-06-09 10:23:09 UTC

## 目录

- [Project Overview & Two-Package Architecture](#page-1)
- [Core Features & MCP Tool Reference](#page-2)
- [Configuration, Skill Sources & Data Flow](#page-3)
- [Operations, Deployment & Troubleshooting](#page-4)

<a id='page-1'></a>

## Project Overview & Two-Package Architecture

### 相关页面

相关主题：[Core Features & MCP Tool Reference](#page-2), [Configuration, Skill Sources & Data Flow](#page-3), [Operations, Deployment & Troubleshooting](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md)
- [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json)
- [packages/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md)
- [packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md)
- [packages/frontend/src/claude_skills_mcp/mcp_proxy.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/mcp_proxy.py)
- [packages/backend/src/claude_skills_mcp_backend/http_server.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/http_server.py)
- [packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py](https://github.com/K-Dense-AI/claude-skills_mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py)
- [packages/backend/src/claude_skills_mcp_backend/config.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/config.py)
- [packages/backend/src/claude_skills_mcp_backend/skill_loader.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/skill_loader.py)
- [packages/backend/src/claude_skills_mcp_backend/update_checker.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/update_checker.py)
- [scripts/sync-version.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/scripts/sync-version.py)
</details>

# Project Overview & Two-Package Architecture

## 项目概述与核心目标

`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]()。

```mermaid
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](getting-started.md) — 安装、Cursor 配置与 CLI 用法
- [Architecture Guide](architecture.md) — 模块依赖与组件交互详解
- [Configuration Reference](configuration.md) — `config.json` 字段说明与默认值
- [Tool Reference](tool-reference.md) — `find_helpful_skills` / `read_skill_document` / `list_skills` 完整参数文档

---

<a id='page-2'></a>

## Core Features & MCP Tool Reference

### 相关页面

相关主题：[Project Overview & Two-Package Architecture](#page-1), [Configuration, Skill Sources & Data Flow](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/backend/src/claude_skills_mcp_backend/http_server.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/http_server.py)
- [packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py)
- [packages/frontend/src/claude_skills_mcp/mcp_proxy.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/mcp_proxy.py)
- [packages/backend/src/claude_skills_mcp_backend/config.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/config.py)
- [packages/backend/src/claude_skills_mcp_backend/skill_loader.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/skill_loader.py)
- [packages/backend/src/claude_skills_mcp_backend/update_checker.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/update_checker.py)
- [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json)
- [README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md)
- [packages/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md)
- [packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md)
</details>

# Core Features & MCP Tool Reference

## 概述

Claude Skills MCP 是一个基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的服务器，旨在让任何兼容 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](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md)。当前最新版本为 **v1.0.6** 资料来源：[packages/backend/src/claude_skills_mcp_backend/__init__.py:3](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/__init__.py)。

## MCP 工具参考

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

### 1. `find_helpful_skills` — 语义搜索

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

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `task_description` | string | 必填 | 任务描述，例："process genomic data" |
| `top_k` | integer | `default_top_k` (3) | 返回候选技能数量，范围 1-20 |
| `list_documents` | boolean | `True` | 是否附带返回可用文档清单 |

资料来源：[packages/frontend/src/claude_skills_mcp/mcp_proxy.py:5-25](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/mcp_proxy.py)。

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

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

| 参数 | 类型 | 说明 |
|---|---|---|
| `skill_name` | string | 必填，技能名（来自 `find_helpful_skills` 结果） |
| `document_path` | string | 可选，路径或 glob 模式 |
| `include_base64` | boolean | 仅对图片有效；为 `True` 时返回 base64 内容，否则仅返回 URL |

资料来源：[packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py:21-46](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py)。

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

返回完整技能清单（名称、描述、来源、文档数量），用于调试或探索。对于任务驱动的场景，仍建议优先使用 `find_helpful_skills` 资料来源：[packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py:48-57](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py)。

## 架构与数据流

```mermaid
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](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/http_server.py)。
- **GitHub 资源发现**：通过 GitHub `tree` API 列出仓库文件，按 `text_extensions` 与 `image_extensions` 过滤，`SKILL.md` 自身被跳过作为元数据 资料来源：[packages/backend/src/claude_skills_mcp_backend/skill_loader.py:33-66](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/skill_loader.py)。
- **自动更新检测**：`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](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/update_checker.py)。

## 关键配置项

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

| 字段 | 默认值 | 用途 |
|---|---|---|
| `embedding_model` | `all-MiniLM-L6-v2` | sentence-transformers 模型名 |
| `default_top_k` | `3` | `find_helpful_skills` 默认返回数量 |
| `max_skill_content_chars` | `null` | 截断技能正文；`null` 表示不限制 |
| `load_skill_documents` | `true` | 是否加载 SKILL.md 之外的脚本/资源 |
| `max_image_size_bytes` | `5242880` (5MB) | 超过该大小的图片只存 URL |
| `auto_update_enabled` | `true` | 是否启用周期性更新检查 |
| `auto_update_interval_minutes` | `60` | 检查间隔 |
| `github_api_token` | `null` | 可选 GitHub PAT，提升 API 限额 |

资料来源：[config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json) 与 [packages/backend/src/claude_skills_mcp_backend/config.py:10-39](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/config.py)。

CLI 用法：`claude-skills-mcp --example-config > config.json` 生成模板，`--config config.json` 应用自定义配置 资料来源：[README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md)。

## 已知问题与社区讨论

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

## 最佳实践小结

1. **始终先调用 `find_helpful_skills`**——其描述明确要求"在任何动作之前先调用以获取最佳方法" 资料来源：[packages/backend/src/claude_skills_mcp_backend/http_server.py:15-23](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/http_server.py)。
2. **首次启动预留 60-120 秒**给后端依赖下载与技能索引；之后查询响应 < 1 秒 资料来源：[packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/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](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/config.py)。

## See Also

- [Getting Started](docs/getting-started.md) — 安装与 Cursor 快速接入
- [Architecture Guide](docs/architecture.md) — 前后端分离设计的完整说明
- [Anthropic Agent Skills Engineering Blog](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — 渐进式披露（progressive disclosure）架构原型
- [Model Context Protocol](https://modelcontextprotocol.io/) — 协议规范

---

<a id='page-3'></a>

## Configuration, Skill Sources & Data Flow

### 相关页面

相关主题：[Project Overview & Two-Package Architecture](#page-1), [Core Features & MCP Tool Reference](#page-2), [Operations, Deployment & Troubleshooting](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json)
- [packages/backend/src/claude_skills_mcp_backend/config.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/config.py)
- [packages/backend/src/claude_skills_mcp_backend/skill_loader.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/skill_loader.py)
- [packages/backend/src/claude_skills_mcp_backend/update_checker.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/update_checker.py)
- [packages/backend/src/claude_skills_mcp_backend/state_manager.py](https://github.com/K-Dense-AI/claude-skills_mcp_backend/blob/main/packages/backend/src/claude_skills_mcp_backend/state_manager.py)
- [packages/backend/src/claude_skills_mcp_backend/scheduler.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/scheduler.py)
- [packages/frontend/src/claude_skills_mcp/mcp_proxy.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/mcp_proxy.py)
- [packages/backend/src/claude_skills_mcp_backend/http_server.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/http_server.py)
- [README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md)
</details>

# Configuration, Skill Sources & Data Flow

## 概述与目的

`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`](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/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 导出示例配置：

```bash
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]()。

### 关键配置项

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| `skill_sources` | Anthropic 官方 skills + K-Dense AI scientific skills + `~/.claude/skills` | 技能来源列表，支持 `github` 与 `local` 两种类型 |
| `embedding_model` | `all-MiniLM-L6-v2` | sentence-transformers 使用的嵌入模型 |
| `default_top_k` | `3` | `find_helpful_skills` 默认返回数量 |
| `max_skill_content_chars` | `null`（不限制） | 单个技能内容字符上限，`null` 表示无限制 |
| `load_skill_documents` | `true` | 是否加载脚本、参考、资产等额外文件 |
| `max_image_size_bytes` | `5242880`（5MB） | 图片阈值，超过时只存 URL |
| `text_file_extensions` | `.md/.py/.txt/.json/.yaml/.yml/.sh/.r/.ipynb/.xml` | 作为文本加载的文件扩展名 |
| `auto_update_enabled` | `true` | 是否启用周期性更新 |
| `auto_update_interval_minutes` | `60` | 更新检测间隔（分钟） |
| `github_api_token` | `null` | 可选，未提供时 60 req/hr，提供后 5000 req/hr |

资料来源：[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 工具调用的完整数据流：

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

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

## See Also

- [Architecture Guide](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/docs/architecture.md)
- [Getting Started](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/docs/getting-started.md)
- [Backend README](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md)
- [Frontend README](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md)
- [MCP 协议规范](https://modelcontextprotocol.io/)
- [Claude Agent Skills 工程博客](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)

---

<a id='page-4'></a>

## Operations, Deployment & Troubleshooting

### 相关页面

相关主题：[Project Overview & Two-Package Architecture](#page-1), [Configuration, Skill Sources & Data Flow](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md)
- [packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md)
- [packages/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md)
- [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json)
- [packages/backend/src/claude_skills_mcp_backend/config.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/config.py)
- [packages/backend/src/claude_skills_mcp_backend/http_server.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/http_server.py)
- [packages/backend/src/claude_skills_mcp_backend/update_checker.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/update_checker.py)
- [packages/frontend/src/claude_skills_mcp/mcp_proxy.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/mcp_proxy.py)
- [scripts/sync-version.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/scripts/sync-version.py)
- [packages/backend/src/claude_skills_mcp_backend/__init__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/__init__.py)
</details>

# Operations, Deployment & Troubleshooting

本页面向运维工程师、平台集成者以及希望自托管 Claude Skills MCP 的团队，介绍项目的部署拓扑、运行时配置、版本管理与常见故障排查要点。文档基于仓库 `v1.0.6` 版本源码整理 资料来源：[packages/backend/src/claude_skills_mcp_backend/__init__.py:1-1]()。

## 一、部署架构概览

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

```mermaid
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]()：

```bash
uvx claude-skills-mcp
```

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

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

### 2.2 远程 / 自托管后端

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

```bash
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]()：

```bash
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]()。下表列出关键配置项。

| 配置键 | 默认值 | 作用 |
| --- | --- | --- |
| `skill_sources` | anthropics/skills、K-Dense AI、本地 `~/.claude/skills` | 技能加载源列表 |
| `embedding_model` | `all-MiniLM-L6-v2` | sentence-transformers 模型 |
| `default_top_k` | `3` | `find_helpful_skills` 默认返回条数 |
| `max_skill_content_chars` | `null` | 技能内容截断上限，`null` 为不限制 |
| `load_skill_documents` | `true` | 是否加载脚本/参考/资源等附加文件 |
| `max_image_size_bytes` | `5242880` | 图片大小阈值，超过则只返回 URL |
| `auto_update_enabled` | `true` | 是否启用每小时自动更新技能源 |
| `auto_update_interval_minutes` | `60` | 自动更新检查周期 |
| `github_api_token` | `null` | 提供后提升至 5000 次/小时 |

更新检测逻辑由 `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](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md)
- 后端独立部署与 Docker：[packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md)
- 前端代理行为：[packages/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md)
- 配置项参考：[packages/backend/src/claude_skills_mcp_backend/config.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/config.py)
- 版本发布流程：[scripts/sync-version.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/scripts/sync-version.py)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: k-dense-ai/claude-skills-mcp; human_manual_source: deepwiki_human_wiki -->