Related Pages

Related topics: Skill Loading, Vector Search & Auto-Update, MCP Tools, Configuration & Frontend Proxy, Deployment, Client Compatibility & Troubleshooting

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). 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).

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).

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). A user-defined local directory (~/.claude/skills by default) is also supported and does not need to exist (config.example.json:11-14).

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). 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).

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). 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).
2. Forward CLI arguments (including --config, --port, --host, --verbose) to the backend (packages/frontend/README.md:43-52).
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).

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). 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). Its components include:

• http_server.py — FastAPI app exposing /mcp (Streamable HTTP MCP) and /health (packages/backend/README.md:61-66, 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).
• 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).
• 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).
• 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).

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).

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). The key fields are:

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

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).
• 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).
• 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).
• 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, issue #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 — the 78+ skills indexed by default
• Anthropic Agent Skills documentation — the Skills format this server implements
• Model Context Protocol — the transport protocol used by both packages

Related Pages

Related topics: Overview & Two-Package Architecture, MCP Tools, Configuration & Frontend Proxy

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].

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].

Skill Loading Pipeline

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

Source: 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].

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].

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].

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]. 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].

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]. 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].

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]. 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]. 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]. 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]. 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]. 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].

See Also

• Architecture Guide — frontend/backend split and request flow
• Getting Started — installation, Cursor/Codex/Windsurf setup
• Model Context Protocol — the transport used by the HTTP server
• Anthropic Skills Engineering Blog — design rationale for progressive disclosure

Related Pages

Related topics: Overview & Two-Package Architecture, Skill Loading, Vector Search & Auto-Update, Deployment, Client Compatibility & Troubleshooting

MCP Tools, Configuration & Frontend Proxy

Overview

The claude-skills-mcp project exposes Anthropic's Agent 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, 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.

Architecture and Data Flow

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.

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.

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. 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.

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.

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, 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, config.example.json.

Key Configuration Options

Source: packages/backend/src/claude_skills_mcp_backend/config.py, 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.

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, 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.

The recommended Cursor configuration is the single-line uvx claude-skills-mcp entry shown in the README; no Python environment setup is required. Source: 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.
• 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 for #4, #5, #11, #12, #13, #16.

See Also

• Architecture Guide — full design rationale for the two-package split
• Getting Started — installation, Cursor setup, and troubleshooting
• config.example.json — annotated reference for every option
• scripts/sync-version.py — keeps the two __version__ strings, wheel names, and CI test fixtures in lockstep

Related Pages

Related topics: Overview & Two-Package Architecture, MCP Tools, Configuration & Frontend Proxy

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, 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.

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, 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.

# 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.

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, 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, packages/backend/src/claude_skills_mcp_backend/__init__.py.

Client Compatibility

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, packages/backend/src/claude_skills_mcp_backend/mcp_handlers.py, 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, config.example.json.

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.

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, issue #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.

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, issue #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.

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, 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.

See Also

• README.md — Project overview and quickstart
• packages/frontend/README.md — Frontend proxy details and first-run behavior
• packages/backend/README.md — Backend endpoints, Docker deployment, and dependency footprint
• scripts/sync-version.py — Centralized version management
• config.example.json — Annotated configuration template
• GitHub issues: #4 Windows, #5 Windsurf, #11 Codex, #12 port conflicts, #13 macOS Intel, #17 CodeGuilds

Doramagic Pitfall Log

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
• 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.
• Recommended 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
• 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.
• Recommended 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
• 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
• Recommended 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
• 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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Integration with ai-agent-skills. Context: Observed when using node
• 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
• 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.
• Recommended 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
• 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.
• Recommended 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
• 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.
• Recommended 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
• 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
• Recommended 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
• 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
• 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
• Recommended 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
• 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
• 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
• Recommended 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.
• 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
• 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.
• Recommended 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
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended 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

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using claude-skills-mcp with real data or production workflows.

• Your project is now listed on CodeGuilds - github / github_issue
• Question about auth approach - github / github_issue
• Backend fails to install on macOS x86_64 (Intel) — PyTorch has no compat - github / github_issue
• Port conflict on startup (address already in use) with custom frontend - - github / github_issue
• Codex shows 'No MCP tools available' while claude-skills tools are calla - github / github_issue
• Integration with ai-agent-skills - github / github_issue
• Windsurf support - github / github_issue
• Add Windows Support (timeout as of now) - github / github_issue
• v1.0.6 - github / github_release
• v1.0.5 - github / github_release
• v1.0.4 - github / github_release
• v1.0.3 - github / github_release