# https://github.com/K-Dense-AI/claude-skills-mcp Project Manual

Generated at: 2026-06-09 10:29:22 UTC

## Table of Contents

- [Overview & Two-Package Architecture](#page-1)
- [Skill Loading, Vector Search & Auto-Update](#page-2)
- [MCP Tools, Configuration & Frontend Proxy](#page-3)
- [Deployment, Client Compatibility & Troubleshooting](#page-4)

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

## Overview & Two-Package Architecture

### Related Pages

Related topics: [Skill Loading, Vector Search & Auto-Update](#page-2), [MCP Tools, Configuration & Frontend Proxy](#page-3), [Deployment, Client Compatibility & Troubleshooting](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [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)
- [scripts/sync-version.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/scripts/sync-version.py)
</details>

# Overview & Two-Package Architecture

## Purpose & High-Level Role

`claude-skills-mcp` is a Model Context Protocol (MCP) server that exposes Anthropic's Agent Skills framework to **any** MCP-compatible AI client — Cursor, Codex, Windsurf, GPT-5, Gemini, and others — not just Claude Code ([README.md:7-9](README.md)). Its primary job is *discovery*: given a natural-language task description, the server returns the most relevant Claude Skill (a packaged bundle of instructions, scripts, references, and assets) along with step-by-step guidance and best practices ([README.md:11-13](README.md)).

The project implements the same **progressive disclosure** pattern Anthropic describes in its Agent Skills engineering blog: skill metadata is cheap to load, but full document content is fetched on demand only after a skill has been selected. This is realised through vector-based semantic search powered by sentence-transformers embeddings, and through MCP tools such as `find_helpful_skills`, `read_skill_document`, and `list_skills` ([packages/backend/src/claude_skills_mcp_backend/http_server.py:15-44](packages/backend/src/claude_skills_mcp_backend/http_server.py)).

Out of the box, the server indexes roughly 90 skills from two curated sources: the official `anthropics/skills` repository (≈15 diverse examples for documents, presentations, and web artifacts) and `K-Dense-AI/claude-scientific-skills` (≈78+ specialised skills for bioinformatics, cheminformatics, and scientific analysis) ([README.md:41-46](README.md)). A user-defined local directory (`~/.claude/skills` by default) is also supported and does not need to exist ([config.example.json:11-14](config.example.json)).

## Two-Package Monorepo Architecture

The project is a Python monorepo with **two independently versioned PyPI packages**, introduced in the v1.0.0 release ([v1.0.0 release notes](https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.0)). The split exists because the heavy ML backend would otherwise impose a 250 MB download and a 60–120 s cold start on every MCP client — exceeding typical Cursor/Codex launch timeouts ([packages/frontend/README.md:9-15](packages/frontend/README.md)).

```mermaid
flowchart LR
    A[MCP Client<br/>Cursor, Codex, Windsurf, ...] -->|stdio JSON-RPC| B[claude-skills-mcp<br/>frontend proxy]
    B -->|auto-download on first use| C[uvx / uv tool install]
    C --> D[claude-skills-mcp-backend<br/>HTTP server :8765]
    D -->|Streamable HTTP MCP| B
    B -->|tool results| A
    D --> E[(Skill corpus<br/>GitHub + local)]
    D --> F[(Vector index<br/>sentence-transformers)]
```

### Package 1 — Frontend (`claude-skills-mcp`)

The frontend is a **lightweight stdio MCP proxy** (~15 MB) that starts in under 5 seconds ([packages/frontend/README.md:7-15](packages/frontend/README.md)). Its responsibilities are:

1. **Present MCP tool schemas immediately** to the host client, so the IDE satisfies its startup timeout before the backend is ready ([packages/frontend/src/claude_skills_mcp/mcp_proxy.py:39-72](packages/frontend/src/claude_skills_mcp/mcp_proxy.py)).
2. **Forward CLI arguments** (including `--config`, `--port`, `--host`, `--verbose`) to the backend ([packages/frontend/README.md:43-52](packages/frontend/README.md)).
3. **Trigger backend installation** on first tool invocation, then proxy subsequent calls over Streamable HTTP to `http://localhost:8765/mcp`.

This split keeps the IDE happy: the user always sees the tools listed, even during the one-time backend download ([packages/frontend/README.md:31-39](packages/frontend/README.md)).

### Package 2 — Backend (`claude-skills-mcp-backend`)

The backend is the **heavy workhorse** that performs the actual skill indexing and semantic search ([packages/backend/README.md:5-13](packages/backend/README.md)). It depends on PyTorch (~150–200 MB CPU-only), sentence-transformers (~50 MB), and FastAPI/Uvicorn/httpx/numpy (~30 MB) ([packages/backend/README.md:79-86](packages/backend/README.md)). Its components include:

- `http_server.py` — FastAPI app exposing `/mcp` (Streamable HTTP MCP) and `/health` ([packages/backend/README.md:61-66](packages/backend/README.md), [packages/backend/src/claude_skills_mcp_backend/http_server.py](packages/backend/src/claude_skills_mcp_backend/http_server.py)).
- `mcp_handlers.py` — Implements the three tools (`find_helpful_skills`, `read_skill_document`, `list_skills`) including glob pattern matching for document paths and base64 image encoding ([packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py:42-90](packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py)).
- `skill_loader.py` — Parses GitHub repositories and local directories, extracts `SKILL.md`, indexes text/image assets, and supports on-demand document fetching with an in-memory cache ([packages/backend/src/claude_skills_mcp_backend/skill_loader.py:14-72](packages/backend/src/claude_skills_mcp_backend/skill_loader.py)).
- `config.py` — Centralised default configuration including the `all-MiniLM-L6-v2` embedding model, `default_top_k=3`, the 5 MB image cap, and hourly auto-update behaviour ([packages/backend/src/claude_skills_mcp_backend/config.py:8-46](packages/backend/src/claude_skills_mcp_backend/config.py)).
- `update_checker.py` — Tracks GitHub commit SHAs to detect upstream changes, with API-call throttling (60 req/hr anonymous, 5000 req/hr with token) ([packages/backend/src/claude_skills_mcp_backend/update_checker.py:42-72](packages/backend/src/claude_skills_mcp_backend/update_checker.py)).

A monorepo-wide **centralised versioning** system ensures both packages always ship identical version strings: a single `VERSION` file at the repo root is propagated by `scripts/sync-version.py` into both `pyproject.toml` files, both `__init__.py` files, the backend health endpoint, the integration tests, and the GitHub release workflows ([scripts/sync-version.py:18-77](scripts/sync-version.py)).

## Configuration & Startup Flow

A single JSON configuration file (obtainable via `--example-config`) controls both packages because the frontend forwards all CLI flags to the backend ([packages/frontend/README.md:43-52](packages/frontend/README.md)). The key fields are:

| Field | Default | Purpose |
| --- | --- | --- |
| `skill_sources` | `anthropics/skills`, `claude-scientific-skills`, `~/.claude/skills` | List of GitHub URLs and local paths to index |
| `embedding_model` | `all-MiniLM-L6-v2` | sentence-transformers model used for vector search |
| `default_top_k` | `3` | Default number of skills returned by `find_helpful_skills` |
| `max_skill_content_chars` | `null` | Truncate SKILL.md content; `null` = unlimited |
| `load_skill_documents` | `true` | Pre-load text/image assets alongside metadata |
| `max_image_size_bytes` | `5 242 880` (5 MB) | Images above this size are stored as URL only |
| `auto_update_enabled` | `true` | Hourly check for upstream skill changes |
| `github_api_token` | `null` | Optional PAT for higher GitHub rate limits |

Source: [config.example.json:1-29](config.example.json), [packages/backend/src/claude_skills_mcp_backend/config.py:8-46](packages/backend/src/claude_skills_mcp_backend/config.py).

## Known Limitations & Community-Reported Issues

The split-package design has surfaced several real-world friction points reported by the community:

- **Windows timeouts (issue #4)** — On Windows 10 the backend fails to load both through Claude Desktop and `uvx claude-skills-mcp`, because the heavy dependency set cannot complete installation within the IDE's startup window. This is the exact problem the frontend proxy was designed to mitigate, but Windows-specific installer behaviour still trips it up ([issue #4](https://github.com/K-Dense-AI/claude-skills-mcp/issues/4)).
- **macOS x86_64 / Intel failures (issue #13)** — PyTorch publishes wheels primarily for arm64 macOS; Intel Macs hit installation errors when the resolver cannot find a compatible build ([issue #13](https://github.com/K-Dense-AI/claude-skills-mcp/issues/13)).
- **Port conflicts (issue #12)** — The backend binds to TCP `8765` by default; concurrent sessions or custom `--port` flags in some MCP clients can collide, producing `address already in use` errors ([issue #12](https://github.com/K-Dense-AI/claude-skills-mcp/issues/12)).
- **MCP-client compatibility gaps (issues #11, #5)** — Codex's MCP panel occasionally reports `No MCP tools available` even though `list_skills` is callable (a discovery/registration mismatch), and Windsurf integration has been validated only experimentally ([issue #11](https://github.com/K-Dense-AI/claude-skills-mcp/issues/11), [issue #5](https://github.com/K-Dense-AI/claude-skills-mcp/issues/5)).

These issues are part of the active roadmap; users on affected platforms are pointed at the hosted MCP service as a workaround while native fixes are tracked on GitHub.

## See Also

- [Claude Scientific Skills repository](https://github.com/K-Dense-AI/claude-scientific-skills) — the 78+ skills indexed by default
- [Anthropic Agent Skills documentation](https://docs.claude.com/en/docs/claude-code/skills) — the Skills format this server implements
- [Model Context Protocol](https://modelcontextprotocol.io/) — the transport protocol used by both packages

---

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

## Skill Loading, Vector Search & Auto-Update

### Related Pages

Related topics: [Overview & Two-Package Architecture](#page-1), [MCP Tools, Configuration & Frontend Proxy](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [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/search_engine.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/search_engine.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/blob/main/packages/backend/src/claude_skills_mcp_backend/state_manager.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/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/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)
- [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json)
</details>

# Skill Loading, Vector Search & Auto-Update

## Overview

The backend package (`claude-skills-mcp-backend`, v1.0.6) implements a three-stage pipeline that turns a curated catalog of Anthropic Agent Skills into a searchable MCP resource. The pipeline (1) **loads** skills from GitHub and local sources, (2) indexes them with a **vector search engine** built on `sentence-transformers`, and (3) keeps the catalog fresh through an **auto-update** worker that polls upstream repositories for new commits. The pipeline runs lazily: the embedding model is only instantiated on first query, and downloads happen in the background so the frontend MCP proxy can advertise tool schemas immediately [Source: [packages/backend/src/claude_skills_mcp_backend/search_engine.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/search_engine.py)].

The frontend (`claude-skills-mcp`) is a thin stdio proxy that returns the same tool schemas synchronously and triggers the backend on first use, so MCP clients such as Cursor do not hit their startup-timeout window while the heavy RAG stack downloads [Source: [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)].

## Skill Loading Pipeline

Loading is driven by `skill_loader.py` and configured via `config.py`. The default `skill_sources` list is:

| Source | Type | URL/Path |
|---|---|---|
| Anthropic Official Skills | github | `https://github.com/anthropics/skills` |
| K-Dense Scientific Skills | github | `https://github.com/K-Dense-AI/claude-scientific-skills` |
| User custom skills | local | `~/.claude/skills` (optional) |

Source: [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)

The `Skill` dataclass encapsulates a parsed skill with `name`, `description`, full `content` (the `SKILL.md` body), `source`, and a `documents` map of additional files (scripts, references, assets) keyed by relative path. Document retrieval is on-demand through `Skill.get_document`, which caches fetched blobs in memory to avoid repeated I/O [Source: [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)].

Files are filtered through configurable extension allow-lists: `text_file_extensions` (e.g. `.md`, `.py`, `.ipynb`) are loaded inline, while `allowed_image_extensions` are kept as URLs unless they fall under `max_image_size_bytes` (default 5 MB) [Source: [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json)].

## Vector Search Engine

The `SkillSearchEngine` is the centerpiece of retrieval. It is constructed with a `model_name` (default `all-MiniLM-L6-v2`) and stores skills plus their embedding matrix. The transformer is **lazy-loaded** inside `_ensure_model_loaded`, so importing the module never pulls PyTorch weights. A `threading.Lock` guards mutations to the skill/embedding arrays, allowing the HTTP server to refresh them while a query is in flight [Source: [packages/backend/src/claude_skills_mcp_backend/search_engine.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/search_engine.py)].

The MCP tool `find_helpful_skills` calls into the search engine via `handle_search_skills`. The handler embeds the `task_description`, computes cosine similarity against the matrix, returns the top-`k` (default 3, max 20) matches, and optionally includes a manifest of available documents for each result [Source: [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)]. A companion tool, `read_skill_document`, then pulls a specific file (or a glob like `scripts/*.py`) without executing any code, with images returned either as base64 or as a URL [Source: [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)].

```mermaid
flowchart LR
    A[MCP Client] -->|task_description| B[find_helpful_skills]
    B --> C[SentenceTransformer<br/>all-MiniLM-L6-v2]
    C --> D[Cosine Similarity<br/>vs indexed embeddings]
    D --> E[Top-k Skills +<br/>document manifest]
    A -->|skill_name + path| F[read_skill_document]
    F --> G[Skill.get_document<br/>on-demand fetch + cache]
    G --> H[Text content or<br/>image URL / base64]
```

## Auto-Update Mechanism

To keep the index current, the backend runs a periodic update worker. The `GitHubSourceTracker` (in `update_checker.py`) persists the latest seen commit SHA per repository via `StateManager("github_tracker")` and exposes an `UpdateResult` describing which sources changed, how many GitHub API calls were made, and any errors encountered [Source: [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)]. State persistence is handled by `StateManager`, which writes tracker files keyed by namespace so restarts pick up where the previous run left off [Source: [packages/backend/src/claude_skills_mcp_backend/state_manager.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/state_manager.py)].

Two configuration knobs control behavior: `auto_update_enabled` (default `true`) and `auto_update_interval_minutes` (default `60`). An optional `github_api_token` raises the unauthenticated quota from 60 to 5 000 requests/hour [Source: [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)]. When the tracker reports a changed source, the loader re-clones only that repository into a temporary directory, re-parses the `SKILL.md` files, and atomically swaps the new embeddings into the `SkillSearchEngine` under the engine's lock.

## Community-Reported Failure Modes

Several open issues trace back to this pipeline. Issue #4 reports the backend "fails to load" on Windows with a timeout — the heavy download (~250 MB) exceeds the default Claude Desktop startup window, motivating the frontend's lazy "return schemas first" pattern [Source: [issue #4](https://github.com/K-Dense-AI/claude-skills-mcp/issues/4)]. Issue #13 documents that on Intel macOS the PyTorch dependency has no compatible wheel, so `claude-skills-mcp-backend` cannot even install — the search engine cannot start without `torch` [Source: [issue #13](https://github.com/K-Dense-AI/claude-skills-mcp/issues/13)]. Issue #12 highlights port collisions (8765/8766) when multiple MCP clients launch the backend concurrently; the `default_top_k` and `--port` arguments must be coordinated across clients [Source: [issue #12](https://github.com/K-Dense-AI/claude-skills-mcp/issues/12)]. Issue #11 notes that Codex can call `list_skills` even when its UI shows "No MCP tools available," suggesting the discovery handshake over stdio differs from how the search engine actually answers [Source: [issue #11](https://github.com/K-Dense-AI/claude-skills-mcp/issues/11)]. Finally, issue #15 explores a self-hosted registry (skillnote) exposing an MCP endpoint so the `find_helpful_skills` tool can index catalogs beyond the default two GitHub sources [Source: [issue #15](https://github.com/K-Dense-AI/claude-skills-mcp/issues/15)].

## See Also

- [Architecture Guide](docs/architecture.md) — frontend/backend split and request flow
- [Getting Started](docs/getting-started.md) — installation, Cursor/Codex/Windsurf setup
- [Model Context Protocol](https://modelcontextprotocol.io/) — the transport used by the HTTP server
- [Anthropic Skills Engineering Blog](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — design rationale for progressive disclosure

---

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

## MCP Tools, Configuration & Frontend Proxy

### Related Pages

Related topics: [Overview & Two-Package Architecture](#page-1), [Skill Loading, Vector Search & Auto-Update](#page-2), [Deployment, Client Compatibility & Troubleshooting](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [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/__main__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/__main__.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/__init__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/__init__.py)
- [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json)
- [packages/frontend/src/claude_skills_mcp/__main__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/__main__.py)
- [packages/frontend/src/claude_skills_mcp/__init__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/__init__.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/frontend/src/claude_skills_mcp/backend_manager.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/backend_manager.py)
- [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)
- [README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md)
- [scripts/sync-version.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/scripts/sync-version.py)
</details>

# MCP Tools, Configuration & Frontend Proxy

## Overview

The `claude-skills-mcp` project exposes Anthropic's [Agent Skills](https://www.anthropic.com/news/skills) framework to any MCP-compatible client through a two-package architecture. The **frontend** (`claude-skills-mcp`, v1.0.6) is a lightweight stdio proxy that boots in seconds, while the **backend** (`claude-skills-mcp-backend`, v1.0.6) is a heavy HTTP server that performs vector search using PyTorch and `sentence-transformers`. Together they register three MCP tools — `find_helpful_skills`, `read_skill_document`, and `list_skills` — and expose a configurable skill index sourced from GitHub repositories and local directories. Source: [README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md), [packages/frontend/src/claude_skills_mcp/__init__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/__init__.py).

The split exists specifically to avoid MCP-client startup timeouts: the proxy returns tool schemas immediately and downloads the backend in the background. Source: [packages/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md).

## Architecture and Data Flow

```mermaid
flowchart LR
    Client[MCP Client<br/>Cursor / Codex / Claude Desktop] -- stdio --> Frontend
    subgraph Frontend["claude-skills-mcp (proxy)"]
        Proxy[MCPProxy] -- HTTP/SSE --> BM[BackendManager]
    end
    BM -- "uvx claude-skills-mcp-backend" --> Backend
    subgraph Backend["claude-skills-mcp-backend (port 8765)"]
        HTTP[FastMCP HTTP Server]
        Engine[Search Engine + Sentence-Transformers]
        Loader[Background Skill Loader]
    end
    Loader -- GitHub API / local FS --> Sources[(skill_sources)]
    HTTP -- /mcp, /health --> Proxy
```

The proxy is the only component most users run directly; the backend is auto-managed. Source: [packages/frontend/src/claude_skills_mcp/__main__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/__main__.py).

## MCP Tools

Three tools are registered by the backend and forwarded by the proxy. Each is decorated with an explicit `name`, `title`, and human-readable `description` that prompts the model to use it proactively.

| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `find_helpful_skills` | Semantic search over the indexed skill library | `task_description: str`, `top_k: int = default_top_k`, `list_documents: bool = True` |
| `read_skill_document` | Retrieve scripts/references/assets from a chosen skill (glob patterns supported) | `skill_*` arguments identifying the skill and a path/pattern |
| `list_skills` | Enumerate all indexed skills | (no required arguments) |

The `find_helpful_skills` tool description explicitly instructs the model: *"Always call this tool FIRST whenever the question requires any domain-specific knowledge…"*. Source: [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). `read_skill_document` is described as a follow-up: *"Use after finding a relevant skill to retrieve specific documents… Supports pattern matching (e.g., 'scripts/*.py') to fetch multiple files. Returns text content or URLs and never executes code."* Source: [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).

Tool registration is centralized in `register_mcp_tools`; the actual request logic lives in `mcp_handlers.py` (handlers: `handle_search_skills`, `read_skill_document`, `handle_list_skills`). Source: [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).

### Endpoints

When the backend is launched standalone, it exposes:

- **Streamable HTTP MCP**: `http://localhost:8765/mcp`
- **Health check**: `http://localhost:8765/health` (custom Route prepended to FastMCP's ASGI app)

Source: [packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md), [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).

## Configuration

All runtime behavior is controlled by a single JSON file loaded by the backend (or by the frontend and forwarded to the backend). The defaults are defined in `DEFAULT_CONFIG` and printed to stdout via `claude-skills-mcp-backend --example-config`. Source: [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), [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json).

### Key Configuration Options

| Option | Default | Effect |
|--------|---------|--------|
| `skill_sources` | `anthropics/skills`, `K-Dense-AI/claude-scientific-skills`, `~/.claude/skills` | Mixed list of `type: github` and `type: local` sources |
| `embedding_model` | `all-MiniLM-L6-v2` | Sentence-transformer model used for vector search |
| `default_top_k` | `3` | Default number of results returned by `find_helpful_skills` |
| `max_skill_content_chars` | `null` | Truncate skill content (`null` = unlimited) |
| `load_skill_documents` | `true` | Index supplementary files (scripts, references, assets) |
| `max_image_size_bytes` | `5242880` (5 MB) | Images larger than this store URL only |
| `allowed_image_extensions` | `.png .jpg .jpeg .gif .svg .webp` | Image MIME filter |
| `text_file_extensions` | `.md .py .txt .json .yaml .yml .sh .r .ipynb .xml` | Files treated as text content |
| `auto_update_enabled` | `true` | Poll GitHub for new commits |
| `auto_update_interval_minutes` | `60` | Update-check interval |
| `github_api_token` | `null` | Raises rate limit from 60 to 5000 req/hr |

Source: [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), [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json).

Update detection uses `GitHubSourceTracker`, which stores commit SHAs in a `StateManager("github_tracker")` and falls back to anonymous 60 req/hr when no token is configured. Source: [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).

### CLI Surface

The backend CLI accepts `--port` (default `8765`), `--host` (default `127.0.0.1`; use `0.0.0.0` for remote access), `--config`, `--verbose`, and `--example-config`. The frontend CLI accepts a **superset** of backend args and forwards them unchanged, plus a `--remote URL` option to point at a hosted backend instead of installing one locally. Source: [packages/backend/src/claude_skills_mcp_backend/__main__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/__main__.py), [packages/frontend/src/claude_skills_mcp/__main__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/__main__.py).

## Frontend Proxy Behavior

On first invocation, `MCPProxy` returns tool schemas in under 5 seconds and triggers `BackendManager` to install the backend via `uvx`/`pip` in the background. A `loader_thread` is started in the backend that calls `load_skills_in_batches` and feeds each batch into the search engine via an `on_batch_loaded` callback, updating `loading_state_global` so tools can report progress. Source: [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).

The recommended Cursor configuration is the single-line `uvx claude-skills-mcp` entry shown in the [README](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md); no Python environment setup is required. Source: [packages/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md).

## Known Limitations and Community Issues

Several issues reported by users map directly onto this page's scope:

- **Windows backend timeout** — the backend fails to load on Windows 10 (issue #4); the frontend's 5-second boot is what makes the proxy the recommended path there. Source: [issue #4](https://github.com/K-Dense-AI/claude-skills-mcp/issues/4).
- **macOS x86_64 install failure** — PyTorch lacks compatible wheels for Intel Macs, so `claude-skills-mcp-backend` cannot start (issue #13). The frontend itself is unaffected; users should prefer the hosted remote backend in this environment.
- **Port conflicts on `--port`** — custom frontend port settings may not consistently prevent backend binding collisions on 8765/8766 (issue #12). When changing ports, set both frontend and backend args explicitly.
- **Codex "No MCP tools available"** — Codex's MCP panel sometimes shows no tools even when `list_skills` is callable (issue #11); this is a client-side discovery gap, not a server bug.
- **Windsurf** — community confirms the same `uvx claude-skills-mcp` config works in Windsurf (issue #5).
- **Authentication** — the maintainers have not added an auth layer; issue #16 (proposing one) was closed as out of scope. Teams needing it must run the backend behind a reverse proxy.

Source: [GitHub issues](https://github.com/K-Dense-AI/claude-skills-mcp/issues) for #4, #5, #11, #12, #13, #16.

## See Also

- [Architecture Guide](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/docs/architecture.md) — full design rationale for the two-package split
- [Getting Started](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/docs/getting-started.md) — installation, Cursor setup, and troubleshooting
- [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json) — annotated reference for every option
- [scripts/sync-version.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/scripts/sync-version.py) — keeps the two `__version__` strings, wheel names, and CI test fixtures in lockstep

---

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

## Deployment, Client Compatibility & Troubleshooting

### Related Pages

Related topics: [Overview & Two-Package Architecture](#page-1), [MCP Tools, Configuration & Frontend Proxy](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [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/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md)
- [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)
- [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/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/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/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md)
- [packages/frontend/src/claude_skills_mcp/__init__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/__init__.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)
</details>

# Deployment, Client Compatibility & Troubleshooting

## Overview

Claude Skills MCP is distributed as two complementary PyPI packages that together form a two-tier deployment: a lightweight `claude-skills-mcp` frontend (stdio MCP) and a heavy `claude-skills-mcp-backend` (Streamable HTTP MCP) wrapping a sentence-transformers vector index. The frontend is the unit most clients install (typically via `uvx`); it auto-fetches the backend on first tool use so the MCP handshake completes in seconds even though the full RAG stack is ~250 MB. Source: [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).

This page covers the deployment topology, known client integration patterns, the build/release pipeline, and the failure modes users most commonly report (Windows timeouts, Intel macOS PyTorch wheel gaps, port conflicts, and MCP client discovery quirks).

## Deployment Architecture

The runtime is split deliberately to keep cold-start latency under typical MCP client timeouts (e.g. Cursor's 60 s handshake). On a `uvx claude-skills-mcp` invocation the frontend process begins serving `tools/list` and `tools/call` over stdio in roughly 5 seconds, while the backend is downloaded and booted in the background. Source: [packages/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md).

```mermaid
flowchart LR
    A[MCP Client<br/>Cursor / Windsurf / Claude Desktop / Codex] -- stdio MCP --> B[claude-skills-mcp<br/>frontend proxy]
    B -- auto-download on first call --> C[claude-skills-mcp-backend<br/>HTTP server :8765/mcp]
    C -- sentence-transformers --> D[(all-MiniLM-L6-v2<br/>vector index)]
    C -- GitHub / local --> E[Skill sources<br/>anthropics/skills<br/>claude-scientific-skills<br/>~/.claude/skills]
    B -. tools/list served instantly .-> A
```

The backend exposes two HTTP endpoints once ready: `http://localhost:8765/mcp` (Streamable HTTP MCP transport) and `http://localhost:8765/health` for liveness checks. The frontend proxies tool invocations to that endpoint. Source: [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).

### Standalone / Remote Backend

The backend can be deployed independently for shared/team use, inside Docker, or behind a reverse proxy. The CLI accepts `--host`, `--port`, `--config`, and `--verbose` flags; the default port is 8765. Source: [packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md).

```bash
# Local
claude-skills-mcp-backend --port 8080

# Remote
claude-skills-mcp-backend --host 0.0.0.0 --port 8080
```

A `Dockerfile` is shipped under `packages/backend/` and exposes the same port. The image inherits the same ~250 MB dependency footprint (PyTorch CPU, sentence-transformers, fastapi/uvicorn, httpx, numpy); the first pull can take 60–180 seconds, so remote deployments should pre-warm the image. Source: [packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md).

### Build & Release Pipeline

The monorepo uses a centralized `VERSION` file at the repo root. `scripts/sync-version.py` rewrites version strings across both `pyproject.toml` files, both `__init__.py` modules, the backend `/health` endpoint payload, the integration test wheel filenames, and the GitHub Actions workflow that publishes the wheels. `scripts/build-all.sh` invokes the syncer before building. Source: [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/http_server.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/http_server.py).

Current published artifacts are at version 1.0.6 for both `claude_skills_mcp` and `claude_skills_mcp_backend`. Source: [packages/frontend/src/claude_skills_mcp/__init__.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/src/claude_skills_mcp/__init__.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).

## Client Compatibility

| Client | Configuration | Status / Notes |
|---|---|---|
| Cursor | Add to `~/.cursor/mcp.json` with `uvx claude-skills-mcp` (also discoverable via the [Cursor Directory entry](https://cursor.directory/mcp/claude-skills-mcp)) | Officially supported; first run triggers one-time backend download |
| Claude Desktop | Configure stdio MCP server entry pointing to `uvx`/`claude-skills-mcp` | Windows users report backend startup timeouts — see Troubleshooting |
| Windsurf | Any MCP client should work the same way per maintainer; testing ongoing | Open issue [#5](https://github.com/K-Dense-AI/claude-skills-mcp/issues/5) — tool calls work, integration details still being verified |
| Codex | Add `claude-skills-mcp` to MCP config | Open issue [#11](https://github.com/K-Dense-AI/claude-skills-mcp/issues/11) — UI may show `No MCP tools available` while tool calls (e.g. `list_skills`) actually succeed; appears to be a client-side discovery quirk, not a server bug |
| ai-agent-skills (companion installer) | `npx ai-agent-skills install <skill> --agent cursor` | Composable: this MCP provides discovery, the npm package provides installation — see issue [#7](https://github.com/K-Dense-AI/claude-skills-mcp/issues/7) |
| CodeGuilds registry | Listed package page at `codeguilds.dev/packages/claude-skills-mcp` | Discovery channel — see issue [#17](https://github.com/K-Dense-AI/claude-skills-mcp/issues/17) |

The same three MCP tools — `find_helpful_skills`, `read_skill_document`, `list_skills` — are advertised by both the frontend proxy and the standalone backend. Their JSON schemas are defined in the FastMCP decorators and the frontend's static `Tool` list. Source: [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).

## Configuration

A configuration file is generated with `--example-config` and merged on top of defaults. The defaults load the two curated GitHub repositories plus `~/.claude/skills` if present. Source: [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), [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json).

| Key | Default | Purpose |
|---|---|---|
| `skill_sources` | Anthropic + K-Dense scientific GitHub repos, `~/.claude/skills` | Where to load skills from (`type: github` or `type: local`) |
| `embedding_model` | `all-MiniLM-L6-v2` | sentence-transformers model used for vector search |
| `default_top_k` | `3` | Result count returned by `find_helpful_skills` |
| `max_skill_content_chars` | `null` | Truncate SKILL.md content; `null` = unlimited |
| `load_skill_documents` | `true` | Eager-load supporting files (scripts, references, assets) |
| `max_image_size_bytes` | `5242880` (5 MB) | Images larger than this store URL only, not base64 |
| `text_file_extensions` | `.md .py .txt .json .yaml .yml .sh .r .ipynb .xml` | Treated as inlined text documents |
| `auto_update_enabled` | `true` | Poll GitHub sources for new commits |
| `auto_update_interval_minutes` | `60` | Update-check cadence |
| `github_api_token` | `null` | Optional PAT; 5000 req/hr authenticated vs. 60 req/hr anonymous |

The update checker tracks GitHub commit SHAs via `GitHubSourceTracker` and the `StateManager` persistence layer, exposing `api_calls_made` and `errors` on its `UpdateResult` dataclass. Source: [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).

## Troubleshooting & Known Failure Modes

The following issues appear repeatedly in community reports and are documented against the relevant code paths.

### Windows backend startup timeout (issue #4)

On Windows 10 the backend fails to load both through Claude Desktop and via `uvx claude-skills-mcp`. The maintainers have acknowledged the bug and the symptom is the frontend's stdio handshake expiring before the heavy backend finishes downloading. Workarounds until fixed: pre-install the backend with `uv tool install claude-skills-mcp-backend` so the first frontend call has nothing to download, and increase the client-side MCP startup timeout if the host IDE allows it. Source: [packages/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md), issue [#4](https://github.com/K-Dense-AI/claude-skills-mcp/issues/4).

### macOS x86_64 (Intel) PyTorch wheel gap (issue #13)

The backend's PyTorch dependency does not ship compatible wheels for Intel Macs on Python 3.12 in some PyPI mirrors, so the backend install fails entirely. Affected users should pin to a Python/build combination where `torch` provides an x86_64 wheel, or use an Apple Silicon / Linux host for the backend and point the frontend at it via the remote deployment path. Source: issue [#13](https://github.com/K-Dense-AI/claude-skills-mcp/issues/13).

### Port conflicts on `--port` (issue #12)

The backend's default port is 8765; custom `--port` values passed through the frontend are forwarded, but some MCP client wrappers do not propagate the flag cleanly, leading to `address already in use` errors. Mitigation: confirm only one backend instance is alive (`lsof -i :8765`), or run the backend on a different port and configure the frontend to point at it. Source: [packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md), issue [#12](https://github.com/K-Dense-AI/claude-skills-mcp/issues/12).

### Codex UI shows "No MCP tools available" (issue #11)

In Codex, the MCP panel may show `No MCP tools available` and `Tools: (none)` even though the server is reachable and `list_skills` calls succeed. The maintainers have not modified the server to address this — it appears to be a client-side discovery issue, so a workaround is to invoke tools by name through direct chat rather than relying on the UI. Source: issue [#11](https://github.com/K-Dense-AI/claude-skills-mcp/issues/11).

### Skills are not refreshed after upstream changes

If GitHub-hosted skills appear stale, verify `auto_update_enabled` and `auto_update_interval_minutes` in your config; the update checker compares commit SHAs via `GitHubSourceTracker` and only re-clones when the SHA changes. Anonymous clients are rate-limited to 60 requests/hour, so setting `github_api_token` to a PAT raises the ceiling to 5000/hour. Source: [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/update_checker.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/src/claude_skills_mcp_backend/update_checker.py).

### `find_helpful_skills` returns no matches

Confirm that your `task_description` is concrete and that the configured `skill_sources` are reachable. For local sources, the directory must exist and contain `SKILL.md` files parsed by `Skill` objects. For GitHub sources, network access (and possibly a token) is required. Source: [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).

## See Also

- [README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/README.md) — Project overview and quickstart
- [packages/frontend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/frontend/README.md) — Frontend proxy details and first-run behavior
- [packages/backend/README.md](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md) — Backend endpoints, Docker deployment, and dependency footprint
- [scripts/sync-version.py](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/scripts/sync-version.py) — Centralized version management
- [config.example.json](https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/config.example.json) — Annotated configuration template
- GitHub issues: [#4 Windows](https://github.com/K-Dense-AI/claude-skills-mcp/issues/4), [#5 Windsurf](https://github.com/K-Dense-AI/claude-skills-mcp/issues/5), [#11 Codex](https://github.com/K-Dense-AI/claude-skills-mcp/issues/11), [#12 port conflicts](https://github.com/K-Dense-AI/claude-skills-mcp/issues/12), [#13 macOS Intel](https://github.com/K-Dense-AI/claude-skills-mcp/issues/13), [#17 CodeGuilds](https://github.com/K-Dense-AI/claude-skills-mcp/issues/17)

---

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

---

## Pitfall Log

Project: k-dense-ai/claude-skills-mcp

Summary: Found 30 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_89d42546abe14de4920a1710883f0c21 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/4

## 2. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_b675c30cf1f247968d5423dc667787d8 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/7

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: 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
- User impact: Developers may fail before the first successful local run: Backend fails to install on macOS x86_64 (Intel) — PyTorch has no compatible wheels
- Suggested check: 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
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_db8b3d22ee0758dad0bf51ec4c8896a9 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/13

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Integration with ai-agent-skills
- User impact: Developers may fail before the first successful local run: Integration with ai-agent-skills
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Integration with ai-agent-skills. Context: Observed when using node
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_002c29655ab3908a3ee515b54df2ce0b | https://github.com/K-Dense-AI/claude-skills-mcp/issues/7

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_10247512c34842958321501a9c716683 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/13

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_85a8d45a7a1c48248e5c29b0d1d10337 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/17

## 7. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.host_targets | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme

## 8. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Codex shows 'No MCP tools available' while claude-skills tools are callable
- User impact: Developers may misconfigure credentials, environment, or host setup: Codex shows 'No MCP tools available' while claude-skills tools are callable
- Suggested check: 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
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_9c0155406f689e1323dda4ddef20ea06 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/11

## 9. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: 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
- User impact: Developers may misconfigure credentials, environment, or host setup: Port conflict on startup (address already in use) with custom frontend --port in MCP clients
- Suggested check: 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
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_d7242c7ea6c8b750e59ca7cd18464f49 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/12

## 10. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Question about auth approach
- User impact: Developers may misconfigure credentials, environment, or host setup: Question about auth approach
- Suggested check: 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_63c4fc984cbeb30d50abef9502dd3aea | https://github.com/K-Dense-AI/claude-skills-mcp/issues/16

## 11. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_0ca57a9e8e754554b9ae966c4a2c0dec | https://github.com/K-Dense-AI/claude-skills-mcp/issues/12

## 12. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme

## 13. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: Add Windows Support (timeout as of now)
- User impact: Developers may hit a documented source-backed failure mode: Add Windows Support (timeout as of now)
- Suggested check: 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
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_ff4e435ee429aad947d25a62410876cb | https://github.com/K-Dense-AI/claude-skills-mcp/issues/4

## 14. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme

## 15. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme

## 16. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme

## 17. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_cbafe3bac49247aa8900be1a6e34c3eb | https://github.com/K-Dense-AI/claude-skills-mcp/issues/11

## 18. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_6267b73e491e42e69f90275aa253bda6 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/16

## 19. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Windsurf support
- User impact: Developers may hit a documented source-backed failure mode: Windsurf support
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Windsurf support. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_ed97ee5ef96f0f27d7bb2d0f54c4e616 | https://github.com/K-Dense-AI/claude-skills-mcp/issues/5

## 20. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Your project is now listed on CodeGuilds
- User impact: Developers may hit a documented source-backed failure mode: Your project is now listed on CodeGuilds
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Your project is now listed on CodeGuilds. Context: Observed when using node
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_71175af6da91fe6c1176b8001cab641f | https://github.com/K-Dense-AI/claude-skills-mcp/issues/17

## 21. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme

## 22. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme

## 23. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.1.1
- User impact: Upgrade or migration may change expected behavior: v0.1.1
- Suggested check: 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_4d307b2134a9a0ea9555454484cc48ac | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v0.1.1

## 24. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.1.2
- User impact: Upgrade or migration may change expected behavior: v0.1.2
- Suggested check: 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_35d0e8f219646a00a0a1bdd7ad1e3d91 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v0.1.2

## 25. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.0.0
- User impact: Upgrade or migration may change expected behavior: v1.0.0
- Suggested check: 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_fa8597f9b9050af664a3c68d881633da | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.0

## 26. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.0.1
- User impact: Upgrade or migration may change expected behavior: v1.0.1
- Suggested check: 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_215164d49601bf6aef9bd77c7d07235f | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.1

## 27. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.0.3
- User impact: Upgrade or migration may change expected behavior: v1.0.3
- Suggested check: 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_20cfef5f8d0b08f066632c50a4dd9509 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.3

## 28. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.0.4
- User impact: Upgrade or migration may change expected behavior: v1.0.4
- Suggested check: 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_336feaca823117608f5da5dfd3535d63 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.4

## 29. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.0.5
- User impact: Upgrade or migration may change expected behavior: v1.0.5
- Suggested check: 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_5947dd5ffe9055bc7e33bf96e8603142 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.5

## 30. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.0.6
- User impact: Upgrade or migration may change expected behavior: v1.0.6
- Suggested check: 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_ff9001a368987158a758726da568c572 | https://github.com/K-Dense-AI/claude-skills-mcp/releases/tag/v1.0.6

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