wp-devdocs-mcp 1.1.1

package/src/server/tools/list-docs.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { listDocs, getDocCategoryCounts } from '../../db/sqlite.js';
+
+export const listDocsSchema = {
+  name: 'list_docs',
+  description: 'List available WordPress documentation pages, optionally filtered by type, category, or source. Returns titles and slugs grouped by category. Use search_docs for full-text search or get_doc to read a specific page. Tip: filter by category for complete listings — unfiltered results may be truncated.',
+  inputSchema: {
+    doc_type: z.enum(['guide', 'tutorial', 'reference', 'api', 'howto', 'faq', 'general']).optional().describe('Filter by document type'),
+    category: z.enum(['block-editor', 'plugins', 'rest-api', 'wp-cli', 'admin']).optional().describe('Filter by documentation category'),
+    source: z.string().optional().describe('Filter by source name'),
+    limit: z.number().min(1).max(200).optional().describe('Max results (default 50)'),
+  },
+};
+
+export function handleListDocs(args) {
+  try {
+    const limit = args.limit || 50;
+    const results = listDocs({
+      doc_type: args.doc_type,
+      category: args.category,
+      source: args.source,
+      limit,
+    });
+
+    if (results.length === 0) {
+      return {
+        content: [{ type: 'text', text: 'No documentation pages found. Check that doc sources are indexed.' }],
+      };
+    }
+
+    // Group by category
+    const grouped = {};
+    for (const doc of results) {
+      const cat = doc.category || 'general';
+      if (!grouped[cat]) grouped[cat] = [];
+      grouped[cat].push(doc);
+    }
+
+    const sections = [];
+    for (const [category, docs] of Object.entries(grouped)) {
+      const lines = docs.map(d => {
+        const parts = [`- **${d.title}** (${d.doc_type})`];
+        parts.push(`  Slug: \`${d.slug}\` | Source: ${d.source_name}`);
+        if (d.description) parts.push(`  ${d.description.slice(0, 120)}${d.description.length > 120 ? '...' : ''}`);
+        return parts.join('\n');
+      });
+      sections.push(`## ${category} (${docs.length})\n${lines.join('\n')}`);
+    }
+
+    let text = `${results.length} documentation page(s):\n\n${sections.join('\n\n')}`;
+
+    // If results hit the limit and no category filter, show full category counts
+    if (results.length >= limit && !args.category) {
+      const counts = getDocCategoryCounts();
+      const total = counts.reduce((sum, c) => sum + c.count, 0);
+      const summary = counts.map(c => `  - ${c.category || 'general'}: ${c.count} pages`).join('\n');
+      text += `\n\n---\n**Results truncated** (showing ${results.length} of ${total} total). All categories:\n${summary}\n\nFilter by category for complete listings.`;
+    }
+
+    text += '\n\n_Use get_doc with a slug to read the full document._';
+
+    return {
+      content: [{ type: 'text', text }],
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error listing docs: ${err.message}` }],
+      isError: true,
+    };
+  }
+}

package/src/server/tools/search-block-apis.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { searchBlockApis } from '../../db/sqlite.js';
+
+export const searchBlockApisSchema = {
+  name: 'search_block_apis',
+  description: 'Search WordPress block registrations and JavaScript API usages (wp.blocks.*, wp.editor.*, wp.blockEditor.*, etc.) across all indexed sources.',
+  inputSchema: {
+    query: z.string().describe('Search query — block name, API call, namespace, or keyword'),
+    limit: z.number().min(1).max(100).optional().describe('Max results per category (default 20)'),
+  },
+};
+
+/**
+ * MCP tool handler — search block registrations and WP JS API usages.
+ * @param {object} args - { query, limit? }
+ * @returns {{ content: Array<{ type: string, text: string }>, isError?: boolean }}
+ */
+export function handleSearchBlockApis(args) {
+  try {
+    const { blocks, apis } = searchBlockApis(args.query, { limit: args.limit || 20 });
+
+    if (blocks.length === 0 && apis.length === 0) {
+      return {
+        content: [{ type: 'text', text: `No block registrations or API usages found matching "${args.query}".` }],
+      };
+    }
+
+    const sections = [];
+
+    if (blocks.length > 0) {
+      const blockLines = blocks.map((b, i) => {
+        const lines = [
+          `### ${i + 1}. ${b.block_name || 'unknown'}`,
+          `- **Source:** ${b.source_name} | **File:** ${b.file_path}:${b.line_number}`,
+        ];
+        if (b.block_title) lines.push(`- **Title:** ${b.block_title}`);
+        if (b.block_category) lines.push(`- **Category:** ${b.block_category}`);
+        if (b.code_context) {
+          lines.push(`- **Context:**\n\`\`\`js\n${b.code_context.slice(0, 500)}\n\`\`\``);
+        }
+        return lines.join('\n');
+      }).join('\n\n');
+
+      sections.push(`## Block Registrations (${blocks.length})\n\n${blockLines}`);
+    }
+
+    if (apis.length > 0) {
+      const apiLines = apis.map((a, i) => {
+        const lines = [
+          `### ${i + 1}. ${a.api_call}`,
+          `- **Source:** ${a.source_name} | **File:** ${a.file_path}:${a.line_number}`,
+          `- **Namespace:** ${a.namespace} | **Method:** ${a.method}`,
+        ];
+        if (a.code_context) {
+          lines.push(`- **Context:**\n\`\`\`js\n${a.code_context.slice(0, 300)}\n\`\`\``);
+        }
+        return lines.join('\n');
+      }).join('\n\n');
+
+      sections.push(`## API Usages (${apis.length})\n\n${apiLines}`);
+    }
+
+    return {
+      content: [{ type: 'text', text: sections.join('\n\n') }],
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error searching block APIs: ${err.message}` }],
+      isError: true,
+    };
+  }
+}

package/src/server/tools/search-docs.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { searchDocs } from '../../db/sqlite.js';
+
+export const searchDocsSchema = {
+  name: 'search_docs',
+  description: 'Search WordPress official documentation (handbooks, REST API docs, WP-CLI reference, block editor guides, etc.) using full-text search. Returns BM25-ranked results. Use get_doc to retrieve full content for a specific result.',
+  inputSchema: {
+    query: z.string().describe('Search query — topic, function name, concept, or keyword'),
+    doc_type: z.enum(['guide', 'tutorial', 'reference', 'api', 'howto', 'faq', 'general']).optional().describe('Filter by document type'),
+    category: z.enum(['block-editor', 'plugins', 'rest-api', 'wp-cli', 'admin']).optional().describe('Filter by documentation category'),
+    source: z.string().optional().describe('Filter by source name'),
+    limit: z.number().min(1).max(100).optional().describe('Max results (default 20)'),
+  },
+};
+
+export function handleSearchDocs(args) {
+  try {
+    const results = searchDocs(args.query, {
+      doc_type: args.doc_type,
+      category: args.category,
+      source: args.source,
+      limit: args.limit || 20,
+    });
+
+    if (results.length === 0) {
+      return {
+        content: [{ type: 'text', text: `No documentation found matching "${args.query}". Try broader terms or check that doc sources are indexed.` }],
+      };
+    }
+
+    const formatted = results.map((d, i) => {
+      const lines = [
+        `### ${i + 1}. ${d.title}`,
+        `- **Type:** ${d.doc_type} | **Category:** ${d.category || 'general'} | **Source:** ${d.source_name}`,
+        `- **Slug:** ${d.slug}`,
+      ];
+      if (d.subcategory) lines.push(`- **Subcategory:** ${d.subcategory}`);
+      if (d.description) lines.push(`- **Description:** ${d.description.slice(0, 200)}${d.description.length > 200 ? '...' : ''}`);
+      lines.push(`- **ID:** ${d.id}`);
+      return lines.join('\n');
+    }).join('\n\n');
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Found ${results.length} doc(s) matching "${args.query}":\n\n${formatted}\n\n_Use get_doc with an ID or slug to read the full document._`,
+      }],
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error searching docs: ${err.message}` }],
+      isError: true,
+    };
+  }
+}

package/src/server/tools/search-hooks.js

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { searchHooks } from '../../db/sqlite.js';
+
+export const searchHooksSchema = {
+  name: 'search_hooks',
+  description: 'Search WordPress hooks (actions/filters) across all indexed sources using full-text search. Returns BM25-ranked results with file locations, parameters, and descriptions.',
+  inputSchema: {
+    query: z.string().describe('Search query — hook name, keyword, or description fragment'),
+    type: z.enum(['action', 'filter', 'action_ref_array', 'filter_ref_array', 'js_action', 'js_filter']).optional().describe('Filter by hook type'),
+    source: z.string().optional().describe('Filter by source name'),
+    is_dynamic: z.boolean().optional().describe('Filter for dynamic hook names only'),
+    include_removed: z.boolean().optional().describe('Include soft-deleted hooks'),
+    limit: z.number().min(1).max(100).optional().describe('Max results (default 20)'),
+  },
+};
+
+/**
+ * MCP tool handler — search WordPress hooks using full-text search.
+ * @param {object} args - { query, type?, source?, is_dynamic?, include_removed?, limit? }
+ * @returns {{ content: Array<{ type: string, text: string }>, isError?: boolean }}
+ */
+export function handleSearchHooks(args) {
+  try {
+    const results = searchHooks(args.query, {
+      type: args.type,
+      source: args.source,
+      isDynamic: args.is_dynamic,
+      includeRemoved: args.include_removed,
+      limit: args.limit || 20,
+    });
+
+    if (results.length === 0) {
+      return {
+        content: [{ type: 'text', text: `No hooks found matching "${args.query}". Try broader search terms or check source indexing with the CLI.` }],
+      };
+    }
+
+    const formatted = results.map((h, i) => {
+      const lines = [
+        `### ${i + 1}. ${h.name}`,
+        `- **Type:** ${h.type} | **Source:** ${h.source_name}`,
+        `- **File:** ${h.file_path}:${h.line_number}`,
+      ];
+      if (h.is_dynamic) lines.push('- **Dynamic:** yes');
+      if (h.status === 'removed') lines.push('- **Status:** REMOVED');
+      if (h.php_function) lines.push(`- **Function:** ${h.php_function}()`);
+      if (h.class_name) lines.push(`- **Class:** ${h.class_name}`);
+      if (h.params) lines.push(`- **Params:** ${h.params}`);
+      if (h.inferred_description) lines.push(`- **Description:** ${h.inferred_description}`);
+      if (h.docblock) lines.push(`- **Docblock:** ${h.docblock.slice(0, 200)}${h.docblock.length > 200 ? '...' : ''}`);
+      lines.push(`- **ID:** ${h.id}`);
+      return lines.join('\n');
+    }).join('\n\n');
+
+    return {
+      content: [{ type: 'text', text: `Found ${results.length} hook(s) matching "${args.query}":\n\n${formatted}` }],
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error searching hooks: ${err.message}` }],
+      isError: true,
+    };
+  }
+}

package/src/server/tools/validate-hook.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { validateHook } from '../../db/sqlite.js';
+
+export const validateHookSchema = {
+  name: 'validate_hook',
+  description: 'Check if a WordPress hook name is valid (exists in indexed sources). Returns VALID, NOT_FOUND, or REMOVED status with similar suggestions when not found. Use this to prevent hook name hallucination.',
+  inputSchema: {
+    hook_name: z.string().describe('Exact hook name to validate'),
+  },
+};
+
+/**
+ * MCP tool handler — validate if a hook name exists in indexed sources.
+ * @param {object} args - { hook_name }
+ * @returns {{ content: Array<{ type: string, text: string }>, isError?: boolean }}
+ */
+export function handleValidateHook(args) {
+  try {
+    const result = validateHook(args.hook_name);
+
+    if (result.status === 'VALID') {
+      const locations = result.hooks.map(h =>
+        `  - ${h.source_name}: ${h.file_path}:${h.line_number} (${h.type})`
+      ).join('\n');
+
+      return {
+        content: [{
+          type: 'text',
+          text: `VALID — Hook "${args.hook_name}" exists in ${result.hooks.length} location(s):\n${locations}`,
+        }],
+      };
+    }
+
+    if (result.status === 'REMOVED') {
+      const locations = result.hooks.map(h =>
+        `  - ${h.source_name}: ${h.file_path}:${h.line_number} (removed ${h.removed_at || 'unknown'})`
+      ).join('\n');
+
+      return {
+        content: [{
+          type: 'text',
+          text: `REMOVED — Hook "${args.hook_name}" was found but has been removed:\n${locations}\n\nThis hook may have been deprecated or renamed.`,
+        }],
+      };
+    }
+
+    // NOT_FOUND
+    let text = `NOT FOUND — Hook "${args.hook_name}" does not exist in any indexed source.`;
+
+    if (result.similar.length > 0) {
+      const suggestions = result.similar.map(s =>
+        `  - ${s.name} (${s.type}) [${s.source_name}]`
+      ).join('\n');
+      text += `\n\nDid you mean one of these?\n${suggestions}`;
+    }
+
+    return {
+      content: [{ type: 'text', text }],
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error validating hook: ${err.message}` }],
+      isError: true,
+    };
+  }
+}