claude-code-ultimate-guide-mcp 1.0.0

package/README.md

@@ -0,0 +1,230 @@
+# claude-code-ultimate-guide-mcp
+
+MCP server for the [Claude Code Ultimate Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide) — search, read, and explore 20,000+ lines of documentation directly from Claude Code or any MCP-compatible client.
+
+No need to clone the repo. The guide's structured index is bundled in the package (~130KB compressed), and file content is fetched from GitHub on demand with 24h local cache.
+
+## Installation
+
+### Quick start (npx)
+
+Add to `~/.claude.json` (user-level, all projects):
+
+```json
+{
+  "mcpServers": {
+    "claude-code-guide": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "claude-code-ultimate-guide-mcp"]
+    }
+  }
+}
+```
+
+### Global install
+
+```bash
+npm install -g claude-code-ultimate-guide-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "claude-code-guide": {
+      "type": "stdio",
+      "command": "claude-code-guide-mcp"
+    }
+  }
+}
+```
+
+### Per-project
+
+Add to `.claude/settings.json` at your repo root.
+
+## Tools
+
+### Search & Navigation
+
+| Tool | Signature | Description |
+|------|-----------|-------------|
+| `search_guide` | `(query, limit?)` | Search by keyword or question across 882 indexed entries. Returns ranked results with GitHub links. |
+| `read_section` | `(path, offset?, limit?)` | Read a file section with pagination (500 lines max per call). Returns GitHub + guide site links. |
+| `list_topics` | `()` | Browse all 25 topic categories in the guide with entry counts. |
+
+### Templates & Examples
+
+| Tool | Signature | Description |
+|------|-----------|-------------|
+| `get_example` | `(name)` | Fetch a production-ready template by exact name (agents, hooks, commands, skills). |
+| `list_examples` | `(category?)` | List all templates by category with GitHub links. Categories: `agents`, `commands`, `hooks`, `skills`, `scripts`. |
+| `search_examples` | `(query, limit?)` | Semantic search across all templates by intent (e.g. `"hook lint"`, `"agent code review"`). |
+
+### What's New
+
+| Tool | Signature | Description |
+|------|-----------|-------------|
+| `get_changelog` | `(count?)` | Last N entries from the guide CHANGELOG (default 5, max 20). |
+| `get_digest` | `(period)` | Combined digest of guide changes + Claude Code CLI releases. Period: `day`, `week`, `month`. |
+| `get_release` | `(version?, count?)` | Claude Code CLI release details. Pass a version (e.g. `"2.1.59"`) or omit for latest + recent N. |
+| `compare_versions` | `(from, to?)` | Diff between two Claude Code versions: aggregated highlights and breaking changes for all releases in range. |
+
+### Security Intelligence
+
+| Tool | Signature | Description |
+|------|-----------|-------------|
+| `get_threat` | `(id)` | Look up a CVE (e.g. `"CVE-2025-53109"`) or attack technique (e.g. `"T001"`) from the threat database. |
+| `list_threats` | `(category?)` | Browse the threat database. Without category: global summary with counts. With category: full section list. Categories: `cves`, `authors`, `skills`, `techniques`, `mitigations`, `sources`. |
+
+### Quick Reference
+
+| Tool | Signature | Description |
+|------|-----------|-------------|
+| `get_cheatsheet` | `(section?)` | Full cheatsheet or filtered to a specific section (e.g. `"hooks"`, `"agents"`, `"mcp"`). |
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `claude-code-guide://reference` | Full structured index (94KB YAML, ~900 entries) — use as fallback when search isn't enough |
+| `claude-code-guide://releases` | Claude Code official releases history (YAML) |
+| `claude-code-guide://llms` | Guide identity/navigation file (llms.txt) |
+
+## Prompts
+
+| Prompt | Args | Description |
+|--------|------|-------------|
+| `claude-code-expert` | `question?` | Activates expert mode with optimal workflow: search → read → example → YAML fallback |
+
+## Onboarding (first run)
+
+After installing the MCP server, run this in any Claude Code session for a personalized guided tour:
+
+```bash
+claude "Use the claude-code-guide MCP server. Activate the claude-code-expert prompt, then run a personalized onboarding: ask me 3 questions about my goal, experience level, and preferred tone — then build a custom learning path using search_guide and read_section to navigate the guide with live source links."
+```
+
+This replaces the static URL-fetch approach with live search across 900+ indexed entries, always up to date, with GitHub + guide site links on every result.
+
+## Usage examples
+
+```
+# Search
+search_guide("hooks")
+search_guide("cost optimization")
+search_guide("custom agents")
+
+# Read content
+read_section("guide/ultimate-guide.md", 8077)
+read_section("guide/cheatsheet.md")
+
+# Templates
+get_example("code-reviewer")
+get_example("pre-commit hook")
+list_examples("agents")
+list_examples("hooks")
+search_examples("hook lint")
+search_examples("agent code review")
+
+# What's new
+get_digest("week")
+get_digest("month")
+get_changelog(10)
+get_release()
+get_release("2.1.59")
+compare_versions("2.1.50", "2.1.59")
+compare_versions("2.0.0")
+
+# Security
+get_threat("CVE-2025-53109")
+get_threat("T001")
+list_threats()
+list_threats("cves")
+list_threats("techniques")
+
+# Quick reference
+get_cheatsheet()
+get_cheatsheet("hooks")
+list_topics()
+```
+
+## Slash command shortcuts
+
+Install the companion slash commands for one-keystroke access in Claude Code. They live in `.claude/commands/ccguide/` of the guide repo — copy or symlink to `~/.claude/commands/ccguide/` for global availability.
+
+```bash
+# From the guide repo root
+cp -r .claude/commands/ccguide ~/.claude/commands/ccguide
+```
+
+Once installed, these commands are available in any Claude Code session:
+
+| Command | Example | What it does |
+|---------|---------|--------------|
+| `/ccguide:search <query>` | `/ccguide:search hooks` | Search + auto-read top results |
+| `/ccguide:cheatsheet [section]` | `/ccguide:cheatsheet hooks` | Full cheatsheet or filtered |
+| `/ccguide:digest <period>` | `/ccguide:digest week` | Guide + CC releases digest |
+| `/ccguide:example <name>` | `/ccguide:example code-reviewer` | Fetch a template |
+| `/ccguide:examples [category]` | `/ccguide:examples agents` | List templates by category |
+| `/ccguide:release [version]` | `/ccguide:release 2.1.59` | CC CLI release details |
+| `/ccguide:changelog [count]` | `/ccguide:changelog 10` | Recent guide CHANGELOG |
+| `/ccguide:topics` | `/ccguide:topics` | Browse all 25 categories |
+
+## Custom agent
+
+A `claude-code-guide` agent is included in `.claude/agents/claude-code-guide.md`. It uses Haiku (fast, cheap) and searches the guide automatically before answering Claude Code questions.
+
+Copy to your `~/.claude/agents/` to use it globally:
+
+```bash
+cp .claude/agents/claude-code-guide.md ~/.claude/agents/claude-code-guide.md
+```
+
+Then invoke with: `use claude-code-guide agent to answer: how do I configure hooks?`
+
+## Dev mode (local repo)
+
+If you've cloned the guide repo, set `GUIDE_ROOT` to read files locally instead of fetching from GitHub:
+
+```json
+{
+  "mcpServers": {
+    "claude-code-guide": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/claude-code-ultimate-guide/mcp-server/dist/index.js"],
+      "env": {
+        "GUIDE_ROOT": "/path/to/claude-code-ultimate-guide"
+      }
+    }
+  }
+}
+```
+
+With `GUIDE_ROOT` set:
+- YAML indexes loaded from the local repo (stays in sync with local changes)
+- File content read directly from disk (no GitHub fetch, no cache)
+
+## Bundled content
+
+The npm package includes (~130KB compressed total):
+- `content/reference.yaml` — 94KB structured index (~900 entries, ~882 indexed)
+- `content/claude-code-releases.yaml` — 27KB releases history (76 releases)
+- `content/llms.txt` — 8KB identity file
+
+Guide markdown files (3.5MB) are **not** bundled — they're fetched from GitHub on demand and cached at `~/.cache/claude-code-guide/{version}/`.
+
+## Cache
+
+File content is cached at `~/.cache/claude-code-guide/{package-version}/` with 24h TTL. If offline, stale cache is served as fallback. If no cache exists and offline, tools return inline summaries from the YAML index instead.
+
+## MCP Inspector
+
+Test locally with the official MCP Inspector:
+
+```bash
+cd mcp-server
+npm run build
+GUIDE_ROOT=.. npx @modelcontextprotocol/inspector node dist/index.js
+```