clawskills-mcp 0.5.0 → 0.6.0

package/README.md

@@ -49,6 +49,9 @@ docker run --rm -i clawskills-mcp
 | `list_playbooks` | List all available cross-tool workflow playbooks |
 | `get_playbook` | Fetch a full playbook by slug |
 | `search_playbooks` | Full-text search across all workflow playbooks |
+| `search_clawskills` | Unified search across both skills and playbooks |
+
+For most user queries, start with `search_clawskills`. It biases toward playbooks for workflow-shaped searches like `closed won onboarding`, `zendesk jira escalation`, or `lead sync`.
 
 ### `list_skills`
 
@@ -92,6 +95,14 @@ No arguments. Returns all available playbooks.
 
 Returns matching excerpts (±3 lines of context) grouped by playbook, capped at 5 matches per playbook.
 
+### `search_clawskills`
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `query` | string | yes | Search string, e.g. `"closed won onboarding"`, `"zendesk jira escalation"`, `"lead sync"` |
+
+Returns combined results across skills and playbooks. Workflow-oriented queries rank playbooks ahead of generic skill matches.
+
 ---
 
 ## Configuration

package/dist/index.js

@@ -148,9 +148,55 @@ function findSkill(skills, name) {
 function findPlaybook(playbooks, name) {
     return findSkill(playbooks, name);
 }
+function parseFrontmatter(content) {
+    if (!content.startsWith("---\n"))
+        return {};
+    const end = content.indexOf("\n---\n", 4);
+    if (end === -1)
+        return {};
+    const block = content.slice(4, end);
+    const metadata = {};
+    let currentKey = null;
+    for (const rawLine of block.split("\n")) {
+        const line = rawLine.trimEnd();
+        const keyMatch = line.match(/^([a-zA-Z0-9_]+):\s*(.*)$/);
+        if (keyMatch) {
+            const [, key, value] = keyMatch;
+            if (value === "") {
+                metadata[key] = [];
+                currentKey = key;
+            }
+            else {
+                metadata[key] = value.trim();
+                currentKey = null;
+            }
+            continue;
+        }
+        const listMatch = line.match(/^\s*-\s+(.*)$/);
+        if (listMatch && currentKey) {
+            const current = metadata[currentKey];
+            if (Array.isArray(current)) {
+                current.push(listMatch[1].trim());
+            }
+        }
+    }
+    return metadata;
+}
+function getPlaybookMetadata(content) {
+    const frontmatter = parseFrontmatter(content);
+    const systems = Array.isArray(frontmatter.systems) ? frontmatter.systems : [];
+    const tags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
+    return {
+        title: typeof frontmatter.title === "string" ? frontmatter.title : undefined,
+        systems,
+        tags,
+        triggerType: typeof frontmatter.trigger_type === "string" ? frontmatter.trigger_type : undefined,
+    };
+}
 function searchDocuments(documents, query) {
     const results = [];
     const lowerQuery = query.toLowerCase();
+    const queryTerms = lowerQuery.split(/[^a-z0-9]+/).filter(Boolean);
     const CONTEXT_LINES = 3;
     const MAX_PER_SKILL = 5;
     for (const [name, content] of documents.entries()) {
@@ -158,7 +204,10 @@ function searchDocuments(documents, query) {
         const excerpts = [];
         const usedRanges = [];
         for (let i = 0; i < lines.length; i++) {
-            if (!lines[i].toLowerCase().includes(lowerQuery))
+            const lowerLine = lines[i].toLowerCase();
+            const matchesExact = lowerLine.includes(lowerQuery);
+            const matchesTerm = queryTerms.some((term) => lowerLine.includes(term));
+            if (!matchesExact && !matchesTerm)
                 continue;
             const start = Math.max(0, i - CONTEXT_LINES);
             const end = Math.min(lines.length - 1, i + CONTEXT_LINES);
@@ -184,6 +233,36 @@ function searchSkills(skills, query) {
 function searchPlaybooks(playbooks, query) {
     return searchDocuments(playbooks, query);
 }
+function searchClawskills(skills, playbooks, query) {
+    const normalizedQuery = query.toLowerCase();
+    const queryTerms = normalizedQuery.split(/[^a-z0-9]+/).filter(Boolean);
+    const workflowHints = new Set([
+        "sync", "onboarding", "closed", "won", "handoff", "escalate",
+        "escalation", "workflow", "playbook", "incident", "notify",
+    ]);
+    const workflowShaped = queryTerms.some((term) => workflowHints.has(term));
+    const skillResults = searchSkills(skills, query).map((result) => ({
+        ...result,
+        contentType: "skill",
+        score: result.excerpts.length * 10 + (workflowShaped ? 0 : 5),
+    }));
+    const playbookResults = searchPlaybooks(playbooks, query).map((result) => {
+        const metadata = getPlaybookMetadata(playbooks.get(result.name));
+        const metadataText = [metadata.title, ...metadata.systems, ...metadata.tags, metadata.triggerType]
+            .filter(Boolean)
+            .join(" ")
+            .toLowerCase();
+        const metadataMatches = queryTerms.filter((term) => metadataText.includes(term)).length;
+        return {
+            ...result,
+            contentType: "playbook",
+            score: result.excerpts.length * 10 + metadataMatches * 5 + (workflowShaped ? 15 : 0),
+        };
+    });
+    return [...playbookResults, ...skillResults]
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .slice(0, 12);
+}
 // ---------------------------------------------------------------------------
 // Skill summary (first meaningful line)
 // ---------------------------------------------------------------------------
@@ -198,7 +277,7 @@ function skillSummary(content) {
 // ---------------------------------------------------------------------------
 // Exports for testing
 // ---------------------------------------------------------------------------
-export { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, skillSummary, };
+export { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, searchClawskills, getPlaybookMetadata, skillSummary, };
 // ---------------------------------------------------------------------------
 // MCP Server setup
 // ---------------------------------------------------------------------------
@@ -269,6 +348,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["query"],
             },
         },
+        {
+            name: "search_clawskills",
+            description: "Search across both skills and playbooks. For workflow-shaped queries, playbooks are ranked ahead of generic skill matches.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search query, e.g. 'closed won onboarding', 'zendesk jira escalation', 'lead sync'" },
+                },
+                required: ["query"],
+            },
+        },
     ],
 }));
 // Call tools
@@ -276,6 +366,7 @@ const GetSkillSchema = z.object({ name: z.string(), section: z.string().optional
 const GetPlaybookSchema = z.object({ name: z.string() });
 const SearchSkillsSchema = z.object({ query: z.string() });
 const SearchPlaybooksSchema = z.object({ query: z.string() });
+const SearchClawskillsSchema = z.object({ query: z.string() });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     if (name === "list_skills") {
@@ -373,6 +464,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             .join("\n\n---\n\n");
         return { content: [{ type: "text", text: `Playbook search results for "${query}":\n\n${output}` }] };
     }
+    if (name === "search_clawskills") {
+        const parsed = SearchClawskillsSchema.safeParse(args);
+        if (!parsed.success) {
+            return { content: [{ type: "text", text: `Invalid arguments: ${parsed.error.message}` }], isError: true };
+        }
+        const { query } = parsed.data;
+        const results = searchClawskills(skills, playbooks, query);
+        if (results.length === 0) {
+            return { content: [{ type: "text", text: `No results found for "${query}".` }] };
+        }
+        const output = results
+            .map(({ name: itemName, contentType, excerpts }) => {
+            const blocks = excerpts.map((e, i) => `--- match ${i + 1} ---\n${e}`).join("\n\n");
+            return `### [${contentType}] ${itemName}\n\n${blocks}`;
+        })
+            .join("\n\n---\n\n");
+        return { content: [{ type: "text", text: `Unified search results for "${query}":\n\n${output}` }] };
+    }
     return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
 });
 // ---------------------------------------------------------------------------

package/dist/index.test.js

@@ -3,7 +3,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { fileURLToPath } from "url";
-import { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, skillSummary, } from "./index.js";
+import { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, searchClawskills, getPlaybookMetadata, skillSummary, } from "./index.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REAL_SKILLS_DIR = path.resolve(__dirname, "../../skills");
 const REAL_PLAYBOOKS_DIR = path.resolve(__dirname, "../../playbooks");
@@ -56,8 +56,8 @@ let tempPlaybooksDir;
 beforeAll(() => {
     tempDir = makeTempSkillsDir({ github: SAMPLE_CONTENT, salesforce: "# Salesforce\nCRM platform.\n## Overview\nSalesforce is a CRM." });
     tempPlaybooksDir = makeTempPlaybooksDir({
-        "zendesk-jira": "# Zendesk -> Jira\n\nEscalate bugs from support into engineering.\n\n## Idempotency\n\nUse zendesk:{ticket_id}.",
-        "hubspot-asana": "# HubSpot -> Asana\n\nCreate onboarding work from closed won deals.",
+        "zendesk-jira": "---\ntitle: Zendesk -> Jira\nsystems:\n  - zendesk\n  - jira\ntags:\n  - support\n  - escalation\ntrigger_type: webhook\n---\n# Zendesk -> Jira\n\nEscalate bugs from support into engineering.\n\n## Idempotency\n\nUse zendesk:{ticket_id}.",
+        "hubspot-asana": "---\ntitle: HubSpot -> Asana\nsystems:\n  - hubspot\n  - asana\ntags:\n  - onboarding\n  - handoff\ntrigger_type: webhook\n---\n# HubSpot -> Asana\n\nCreate onboarding work from closed won deals.",
     });
 });
 afterAll(() => {
@@ -229,6 +229,32 @@ describe("searchPlaybooks", () => {
         expect(results[0].name).toBe("zendesk-jira");
     });
 });
+describe("getPlaybookMetadata", () => {
+    it("parses frontmatter metadata from playbooks", () => {
+        const playbooks = loadPlaybooks(tempPlaybooksDir);
+        const metadata = getPlaybookMetadata(playbooks.get("zendesk-jira"));
+        expect(metadata.systems).toContain("zendesk");
+        expect(metadata.tags).toContain("escalation");
+        expect(metadata.triggerType).toBe("webhook");
+    });
+});
+describe("searchClawskills", () => {
+    it("prefers playbooks for workflow-shaped queries", () => {
+        const skills = new Map([["hubspot", "HubSpot CRM API.\nUse for contacts and deals."]]);
+        const playbooks = loadPlaybooks(tempPlaybooksDir);
+        const results = searchClawskills(skills, playbooks, "closed won onboarding");
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].contentType).toBe("playbook");
+        expect(results[0].name).toBe("hubspot-asana");
+    });
+    it("still returns skill hits for non-workflow queries", () => {
+        const skills = loadSkills(tempDir);
+        const playbooks = loadPlaybooks(tempPlaybooksDir);
+        const results = searchClawskills(skills, playbooks, "Personal Access Token");
+        expect(results.length).toBeGreaterThan(0);
+        expect(results.some((result) => result.contentType === "skill" && result.name === "github")).toBe(true);
+    });
+});
 // ---------------------------------------------------------------------------
 // skillSummary
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawskills-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server exposing ClawSkills API integration skill docs to AI agents",
   "license": "MIT",
   "author": "ClawSkills Contributors",

package/playbooks/hubspot-asana-onboarding.md

@@ -1,3 +1,17 @@
+---
+title: HubSpot Deal Won -> Asana Onboarding Kickoff
+systems:
+  - hubspot
+  - asana
+tags:
+  - crm
+  - onboarding
+  - handoff
+  - delivery
+  - revops
+trigger_type: webhook
+---
+
 # HubSpot Deal Won -> Asana Onboarding Kickoff
 
 ## Goal

package/playbooks/salesforce-hubspot-lead-sync.md

@@ -1,3 +1,17 @@
+---
+title: Salesforce Lead -> HubSpot Contact Sync
+systems:
+  - salesforce
+  - hubspot
+tags:
+  - crm
+  - sync
+  - marketing
+  - lead
+  - revops
+trigger_type: scheduled_sync
+---
+
 # Salesforce Lead -> HubSpot Contact Sync
 
 ## Goal

package/playbooks/zendesk-jira-bug-escalation.md

@@ -1,3 +1,17 @@
+---
+title: Zendesk Ticket -> Jira Bug Escalation
+systems:
+  - zendesk
+  - jira
+tags:
+  - support
+  - engineering
+  - escalation
+  - incident
+  - handoff
+trigger_type: webhook_or_incremental_sync
+---
+
 # Zendesk Ticket -> Jira Bug Escalation
 
 ## Goal

package/skills/ROADMAP.md

@@ -19,7 +19,7 @@ This skill set enables end-to-end automation and integration across the most com
 | Layer | Status |
 |-------|--------|
 | **14 skill docs** — Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, Linear | ✅ Live |
-| **MCP server** — `clawskills-mcp` v0.4.0 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
+| **MCP server** — `clawskills-mcp` v0.5.0 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
 | **CI pipeline** — build + test on every push/PR via `ci.yml` | ✅ Live |
 | **Release automation** — `release.yml` workflow_dispatch → bump, tag, npm publish via OIDC | ✅ Live |
 | **Test suite** — Vitest unit tests + real-skills validation (required sections, ≥5 KB, all 14 tools) | ✅ Live |
@@ -83,7 +83,7 @@ The repo now needs tighter alignment between the canonical `skills/` directory,
 | Channel | Status | Next action |
 |---------|--------|-------------|
 | GitHub (public) | Ready to flip | Make repo public |
-| npm (`clawskills-mcp`) | ✅ Live — v0.4.0 | Maintain via `release.yml` |
+| npm (`clawskills-mcp`) | ✅ Live — v0.5.0 | Maintain via `release.yml` |
 | MCP registry listings | Not submitted | Submit to glama.ai, mcp.so, smithery.ai after public launch |
 | Docs website | Planned | Mintlify — fastest path to SEO-friendly browsable docs |
 | Lane A vs B | TBD | Revisit after first traction signals from public launch |