From 63028fd5e905f653bbb3f55e1857b48efba6ba6d Mon Sep 17 00:00:00 2001 From: Matt Galligan Date: Mon, 2 Feb 2026 14:14:24 -0500 Subject: [PATCH] feat: add Claude Code plugin support with inline status check (#99) - Add marketplace.json for Claude Code plugin installation - Simplify skill status check to inline `qmd status` (portable across agents) - Update SKILL.md MCP section, reference mcp-setup.md for manual config - Clean up mcp-setup.md (remove redundant prerequisites) - Rename MCP-SETUP.md to mcp-setup.md Co-authored-by: Claude Opus 4.5 --- .claude-plugin/marketplace.json | 29 +++++++++++++ README.md | 9 +++- skills/qmd/SKILL.md | 41 ++++++++----------- .../references/{MCP-SETUP.md => mcp-setup.md} | 24 ++--------- 4 files changed, 57 insertions(+), 46 deletions(-) create mode 100644 .claude-plugin/marketplace.json rename skills/qmd/references/{MCP-SETUP.md => mcp-setup.md} (85%) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..00a7de8 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,29 @@ +{ + "name": "qmd", + "owner": { + "name": "tobi", + "email": "tobi@lutke.com" + }, + "plugins": [ + { + "name": "qmd", + "source": "./", + "description": "Search and retrieve documents from local markdown files.", + "version": "0.1.0", + "author": { + "name": "tobi", + "email": "tobi@lutke.com" + }, + "repository": "https://github.com/tobi/qmd", + "license": "MIT", + "keywords": ["markdown", "search", "qmd"], + "skills": ["./skills/"], + "mcpServers": { + "qmd": { + "command": "qmd", + "args": ["mcp"] + } + } + } + ] +} diff --git a/README.md b/README.md index 1ad2269..4ff6138 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,14 @@ Although the tool works perfectly fine when you just tell your agent to use it o } ``` -**Claude Code configuration** (`~/.claude/settings.json`): +**Claude Code** — Install the plugin (recommended): + +```bash +claude marketplace add tobi/qmd +claude plugin add qmd@qmd +``` + +Or configure MCP manually in `~/.claude/settings.json`: ```json { diff --git a/skills/qmd/SKILL.md b/skills/qmd/SKILL.md index 988bab9..398aa27 100644 --- a/skills/qmd/SKILL.md +++ b/skills/qmd/SKILL.md @@ -1,18 +1,22 @@ --- name: qmd -description: Search personal markdown knowledge bases, notes, meeting transcripts, and documentation using QMD - a local hybrid search engine. Combines BM25 keyword search, vector semantic search, and LLM re-ranking. Use when users ask to search notes, find documents, look up information in their knowledge base, retrieve meeting notes, or search documentation. Triggers on "search my notes", "find in docs", "look up", "what did I write about", "meeting notes about". +description: Search personal markdown knowledge bases, notes, meeting transcripts, and documentation using QMD - a local hybrid search engine. Combines BM25 keyword search, vector semantic search, and LLM re-ranking. Use when users ask to search notes, find documents, look up information in their knowledge base, retrieve meeting notes, or search documentation. Triggers on "search markdown files", "search my notes", "find in docs", "look up", "what did I write about", "meeting notes about". license: MIT -compatibility: Requires qmd installed via `bun install -g https://github.com/tobi/qmd`. Works with Claude Code CLI and MCP-compatible agents. +compatibility: Requires qmd CLI or MCP server. Install via `bun install -g https://github.com/tobi/qmd`. metadata: author: tobi - version: "1.0" -allowed-tools: Bash(qmd:*) + version: "1.1.1" +allowed-tools: Bash(qmd:*), mcp__qmd__* --- # QMD - Quick Markdown Search QMD is a local, on-device search engine for markdown content. It indexes your notes, meeting transcripts, documentation, and knowledge bases for fast retrieval. +## QMD Status + +!`qmd status 2>/dev/null || echo "Not installed. Run: bun install -g https://github.com/tobi/qmd"` + ## When to Use This Skill - User asks to search their notes, documents, or knowledge base @@ -32,7 +36,7 @@ Choose the right search mode for the task: | `qmd vsearch` | Keywords aren't working, need conceptual matches | Medium | | `qmd query` | Best results needed, speed not critical | Slower | -```sh +```bash # Fast keyword search (BM25) qmd search "your query" @@ -45,7 +49,7 @@ qmd query "your query" ## Common Options -```sh +```bash -n # Number of results (default: 5) -c, --collection # Restrict to specific collection --all # Return all matches @@ -58,7 +62,7 @@ qmd query "your query" ## Document Retrieval -```sh +```bash # Get document by path qmd get "collection/path/to/doc.md" @@ -77,7 +81,7 @@ qmd multi-get "doc1.md, doc2.md, #abc123" ## Index Management -```sh +```bash # Check index status and available collections qmd status @@ -110,7 +114,7 @@ qmd update ## Example: Finding Meeting Notes -```sh +```bash # Search for meetings about a topic qmd search "quarterly review" -c meetings -n 5 @@ -123,7 +127,7 @@ qmd get "#abc123" --full ## Example: Research Across All Notes -```sh +```bash # Hybrid search for best results qmd query "authentication implementation" --min-score 0.3 --json @@ -133,7 +137,7 @@ qmd query "auth flow" --all --files --min-score 0.4 ## MCP Server Integration -QMD also works as an MCP server, providing these tools directly: +This plugin configures the qmd MCP server automatically. When available, prefer MCP tools over Bash for tighter integration: | MCP Tool | Equivalent CLI | Purpose | |----------|---------------|---------| @@ -144,17 +148,4 @@ QMD also works as an MCP server, providing these tools directly: | `qmd_multi_get` | `qmd multi-get` | Retrieve multiple documents | | `qmd_status` | `qmd status` | Index health and collection info | -To enable MCP tools, add to `~/.claude/settings.json`: - -```json -{ - "mcpServers": { - "qmd": { - "command": "qmd", - "args": ["mcp"] - } - } -} -``` - -When MCP is configured, prefer using the `qmd_*` tools directly instead of Bash commands for better integration. +For manual MCP setup without the plugin, see [references/mcp-setup.md](references/mcp-setup.md). diff --git a/skills/qmd/references/MCP-SETUP.md b/skills/qmd/references/mcp-setup.md similarity index 85% rename from skills/qmd/references/MCP-SETUP.md rename to skills/qmd/references/mcp-setup.md index 86c1371..8614d8f 100644 --- a/skills/qmd/references/MCP-SETUP.md +++ b/skills/qmd/references/mcp-setup.md @@ -1,26 +1,10 @@ # QMD MCP Server Setup -Detailed instructions for configuring QMD as an MCP (Model Context Protocol) server. +Manual MCP configuration for use without the qmd plugin. -## Prerequisites +> **Note**: If using the qmd plugin, MCP configuration is included automatically. This is only needed for manual setup. -1. Install qmd globally: - ```sh - bun install -g https://github.com/tobi/qmd - ``` - -2. Verify installation: - ```sh - qmd --help - ``` - -3. Set up at least one collection: - ```sh - qmd collection add ~/Documents/notes --name notes - qmd embed # Generate vector embeddings - ``` - -## Claude Code Configuration +## Claude Code Add to `~/.claude/settings.json`: @@ -35,7 +19,7 @@ Add to `~/.claude/settings.json`: } ``` -## Claude Desktop Configuration +## Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: