wp-devdocs-mcp 1.1.1

package/src/indexer/php-parser.js

@@ -0,0 +1,205 @@
+import {
+  getLineNumber,
+  extractCodeWindow,
+  generateContentHash,
+  inferDescription,
+  extractDocblock,
+  findEnclosingFunction,
+  findEnclosingClass,
+} from './parser-utils.js';
+
+// Matches do_action(), apply_filters(), do_action_ref_array(), apply_filters_ref_array()
+const HOOK_REGEX = /\b(do_action|apply_filters|do_action_ref_array|apply_filters_ref_array)\s*\(\s*/g;
+
+const TYPE_MAP = {
+  do_action: 'action',
+  apply_filters: 'filter',
+  do_action_ref_array: 'action_ref_array',
+  apply_filters_ref_array: 'filter_ref_array',
+};
+
+/**
+ * Parse a PHP file and extract all WordPress hooks.
+ * @param {string} content - File content
+ * @param {string} filePath - Relative file path
+ * @param {number} sourceId - Source ID
+ * @returns {Array} Array of hook data objects
+ */
+export function parsePhpFile(content, filePath, sourceId) {
+  const hooks = [];
+  const lines = content.split('\n');
+
+  let match;
+  HOOK_REGEX.lastIndex = 0;
+
+  while ((match = HOOK_REGEX.exec(content)) !== null) {
+    const funcName = match[1];
+    const type = TYPE_MAP[funcName];
+    const startOffset = match.index + match[0].length;
+
+    // Extract the arguments string (handle nested parentheses)
+    const argsStr = extractArguments(content, startOffset);
+    if (!argsStr) continue;
+
+    const args = splitArguments(argsStr);
+    if (args.length === 0) continue;
+
+    // First arg is the hook name
+    const rawName = args[0].trim();
+    const hookName = cleanHookName(rawName);
+    if (!hookName) continue;
+
+    const isDynamic = rawName.includes('$') || (rawName.includes('.') && !rawName.startsWith("'") && !rawName.startsWith('"'));
+
+    const lineNumber = getLineNumber(content, match.index);
+    const lineIndex = lineNumber - 1;
+
+    const params = args.slice(1).map(p => p.trim()).filter(Boolean);
+    const paramCount = params.length;
+
+    const docblock = extractDocblock(lines, lineIndex);
+    const { codeBefore, hookLine, codeAfter } = extractCodeWindow(lines, lineIndex);
+    const phpFunction = findEnclosingFunction(lines, lineIndex);
+    const className = findEnclosingClass(lines, lineIndex);
+
+    const hookData = {
+      source_id: sourceId,
+      file_path: filePath,
+      line_number: lineNumber,
+      name: hookName,
+      type,
+      php_function: phpFunction || null,
+      params: params.join(', ') || null,
+      param_count: paramCount,
+      docblock: docblock || null,
+      inferred_description: null,
+      function_context: phpFunction || null,
+      class_name: className || null,
+      code_before: codeBefore || null,
+      code_after: codeAfter || null,
+      hook_line: hookLine || null,
+      is_dynamic: isDynamic ? 1 : 0,
+      content_hash: null,
+    };
+
+    hookData.inferred_description = inferDescription(hookData);
+    hookData.content_hash = generateContentHash(hookData);
+
+    hooks.push(hookData);
+  }
+
+  return hooks;
+}
+
+/**
+ * Extract arguments string from content starting at the position after opening paren.
+ */
+function extractArguments(content, start) {
+  let depth = 1;
+  let i = start;
+  const max = Math.min(start + 2000, content.length); // Safety limit
+
+  while (i < max && depth > 0) {
+    const ch = content[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    else if (ch === "'" || ch === '"') {
+      // Skip string literals
+      i = skipString(content, i);
+    }
+    if (depth > 0) i++;
+  }
+
+  if (depth !== 0) return null;
+  return content.slice(start, i);
+}
+
+/**
+ * Skip a string literal starting at position i.
+ */
+function skipString(content, i) {
+  const quote = content[i];
+  i++;
+  while (i < content.length) {
+    if (content[i] === '\\') {
+      i += 2;
+      continue;
+    }
+    if (content[i] === quote) return i;
+    i++;
+  }
+  return i;
+}
+
+/**
+ * Split arguments by comma, respecting nesting and strings.
+ */
+function splitArguments(argsStr) {
+  const args = [];
+  let current = '';
+  let depth = 0;
+  let inString = false;
+  let stringChar = '';
+
+  for (let i = 0; i < argsStr.length; i++) {
+    const ch = argsStr[i];
+
+    if (inString) {
+      current += ch;
+      if (ch === '\\') {
+        i++;
+        if (i < argsStr.length) current += argsStr[i];
+        continue;
+      }
+      if (ch === stringChar) inString = false;
+      continue;
+    }
+
+    if (ch === "'" || ch === '"') {
+      inString = true;
+      stringChar = ch;
+      current += ch;
+    } else if (ch === '(' || ch === '[' || ch === '{') {
+      depth++;
+      current += ch;
+    } else if (ch === ')' || ch === ']' || ch === '}') {
+      depth--;
+      current += ch;
+    } else if (ch === ',' && depth === 0) {
+      args.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+
+  if (current.trim()) args.push(current);
+  return args;
+}
+
+/**
+ * Clean a hook name string — remove quotes, handle concatenation.
+ */
+function cleanHookName(raw) {
+  const trimmed = raw.trim();
+
+  // Simple quoted string: 'hook_name' or "hook_name"
+  const simpleMatch = trimmed.match(/^['"]([^'"]+)['"]$/);
+  if (simpleMatch) return simpleMatch[1];
+
+  // Concatenated string: 'prefix_' . $var . '_suffix' → prefix_{dynamic}_suffix
+  if (trimmed.includes('.') || trimmed.includes('$')) {
+    const parts = trimmed.split(/\s*\.\s*/);
+    const cleaned = parts.map(part => {
+      const qm = part.trim().match(/^['"]([^'"]*)['"]$/);
+      if (qm) return qm[1];
+      return '{dynamic}';
+    }).join('');
+    return cleaned || null;
+  }
+
+  // Variable only
+  if (trimmed.startsWith('$')) return '{dynamic}';
+
+  return null;
+}

package/src/indexer/sources/github-private.js

@@ -0,0 +1,57 @@
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import simpleGit from 'simple-git';
+import { CACHE_DIR } from '../../constants.js';
+
+/**
+ * Fetch a private GitHub repo using a token from an env var.
+ * Token is injected into the URL at clone time — never stored.
+ */
+export async function fetchGithubPrivate(source) {
+  const tokenEnvVar = source.token_env_var;
+  if (!tokenEnvVar) {
+    throw new Error(`Source "${source.name}" is type github-private but has no token_env_var configured`);
+  }
+
+  const token = process.env[tokenEnvVar];
+  if (!token) {
+    throw new Error(`Environment variable "${tokenEnvVar}" is not set. Required for private repo "${source.name}"`);
+  }
+
+  const repoName = source.repo_url.replace(/.*\/\/[^/]+\//, '').replace(/\.git$/, '').replace(/\//g, '--');
+  const cloneDir = join(CACHE_DIR, repoName);
+  mkdirSync(CACHE_DIR, { recursive: true });
+
+  // Inject token into URL: https://token@github.com/...
+  const authedUrl = source.repo_url.replace('https://', `https://${token}@`);
+
+  const git = simpleGit();
+
+  if (existsSync(join(cloneDir, '.git'))) {
+    const repoGit = simpleGit(cloneDir);
+    try {
+      // Set remote URL with token temporarily for fetch
+      await repoGit.remote(['set-url', 'origin', authedUrl]);
+      await repoGit.fetch('origin', source.branch || 'main', ['--depth=1']);
+      await repoGit.reset(['--hard', `origin/${source.branch || 'main'}`]);
+      // Remove token from stored remote
+      await repoGit.remote(['set-url', 'origin', source.repo_url]);
+    } catch (err) {
+      // Clean up token from remote even on error
+      try { await repoGit.remote(['set-url', 'origin', source.repo_url]); } catch (_) { /* token cleanup is best-effort */ }
+      console.error(`Warning: pull failed for ${source.name}: ${err.message}`);
+    }
+  } else {
+    await git.clone(authedUrl, cloneDir, [
+      '--depth=1',
+      '--branch', source.branch || 'main',
+      '--single-branch',
+    ]);
+    // Remove token from stored remote
+    const repoGit = simpleGit(cloneDir);
+    await repoGit.remote(['set-url', 'origin', source.repo_url]);
+  }
+
+  const localPath = source.subfolder ? join(cloneDir, source.subfolder) : cloneDir;
+  return localPath;
+}

package/src/indexer/sources/github-public.js

@@ -0,0 +1,38 @@
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import simpleGit from 'simple-git';
+import { CACHE_DIR } from '../../constants.js';
+import { mkdirSync } from 'node:fs';
+
+/**
+ * Fetch a public GitHub repo via shallow clone / pull.
+ * Returns the local path to the (optionally subfoldered) source.
+ */
+export async function fetchGithubPublic(source) {
+  const repoName = source.repo_url.replace(/.*\/\/[^/]+\//, '').replace(/\.git$/, '').replace(/\//g, '--');
+  const cloneDir = join(CACHE_DIR, repoName);
+  mkdirSync(CACHE_DIR, { recursive: true });
+
+  const git = simpleGit();
+
+  if (existsSync(join(cloneDir, '.git'))) {
+    // Pull latest
+    const repoGit = simpleGit(cloneDir);
+    try {
+      await repoGit.fetch('origin', source.branch || 'main', ['--depth=1']);
+      await repoGit.reset(['--hard', `origin/${source.branch || 'main'}`]);
+    } catch (err) {
+      console.error(`Warning: pull failed for ${source.name}, using cached version: ${err.message}`);
+    }
+  } else {
+    // Shallow clone
+    await git.clone(source.repo_url, cloneDir, [
+      '--depth=1',
+      '--branch', source.branch || 'main',
+      '--single-branch',
+    ]);
+  }
+
+  const localPath = source.subfolder ? join(cloneDir, source.subfolder) : cloneDir;
+  return localPath;
+}

package/src/indexer/sources/index.js

@@ -0,0 +1,19 @@
+import { fetchGithubPublic } from './github-public.js';
+import { fetchGithubPrivate } from './github-private.js';
+import { fetchLocalFolder } from './local-folder.js';
+
+/**
+ * Unified dispatcher — fetches/validates a source and returns the local path.
+ */
+export async function fetchSource(source) {
+  switch (source.type) {
+    case 'github-public':
+      return fetchGithubPublic(source);
+    case 'github-private':
+      return fetchGithubPrivate(source);
+    case 'local-folder':
+      return fetchLocalFolder(source);
+    default:
+      throw new Error(`Unknown source type: ${source.type}`);
+  }
+}

package/src/indexer/sources/local-folder.js

@@ -0,0 +1,17 @@
+import { existsSync } from 'node:fs';
+
+/**
+ * Validate and return a local folder path.
+ */
+export async function fetchLocalFolder(source) {
+  const localPath = source.local_path;
+  if (!localPath) {
+    throw new Error(`Source "${source.name}" is type local-folder but has no local_path configured`);
+  }
+
+  if (!existsSync(localPath)) {
+    throw new Error(`Local path does not exist: ${localPath}`);
+  }
+
+  return localPath;
+}

package/src/mcp-entry.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { searchHooksSchema, handleSearchHooks } from './server/tools/search-hooks.js';
+import { validateHookSchema, handleValidateHook } from './server/tools/validate-hook.js';
+import { getHookContextSchema, handleGetHookContext } from './server/tools/get-hook-context.js';
+import { searchBlockApisSchema, handleSearchBlockApis } from './server/tools/search-block-apis.js';
+import { searchDocsSchema, handleSearchDocs } from './server/tools/search-docs.js';
+import { getDocSchema, handleGetDoc } from './server/tools/get-doc.js';
+import { listDocsSchema, handleListDocs } from './server/tools/list-docs.js';
+
+// Initialize DB on import (side effect)
+import { getDb, getStaleSources } from './db/sqlite.js';
+import { indexSources } from './indexer/index-manager.js';
+
+const server = new McpServer({
+  name: 'wp-devdocs-mcp',
+  version: '1.1.0',
+});
+
+// Register tools
+server.tool(
+  searchHooksSchema.name,
+  searchHooksSchema.description,
+  searchHooksSchema.inputSchema,
+  handleSearchHooks,
+);
+
+server.tool(
+  validateHookSchema.name,
+  validateHookSchema.description,
+  validateHookSchema.inputSchema,
+  handleValidateHook,
+);
+
+server.tool(
+  getHookContextSchema.name,
+  getHookContextSchema.description,
+  getHookContextSchema.inputSchema,
+  handleGetHookContext,
+);
+
+server.tool(
+  searchBlockApisSchema.name,
+  searchBlockApisSchema.description,
+  searchBlockApisSchema.inputSchema,
+  handleSearchBlockApis,
+);
+
+server.tool(
+  searchDocsSchema.name,
+  searchDocsSchema.description,
+  searchDocsSchema.inputSchema,
+  handleSearchDocs,
+);
+
+server.tool(
+  getDocSchema.name,
+  getDocSchema.description,
+  getDocSchema.inputSchema,
+  handleGetDoc,
+);
+
+server.tool(
+  listDocsSchema.name,
+  listDocsSchema.description,
+  listDocsSchema.inputSchema,
+  handleListDocs,
+);
+
+// Ensure DB is ready
+try {
+  getDb();
+} catch (err) {
+  process.stderr.write(`Failed to initialize database: ${err.message}\n`);
+  process.exit(1);
+}
+
+// Start
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// Background auto-update of stale sources (fire-and-forget)
+async function autoUpdate() {
+  if (process.env.WP_MCP_AUTO_UPDATE === 'false') return;
+  try {
+    const staleSources = getStaleSources(24 * 60 * 60 * 1000);
+    if (staleSources.length === 0) return;
+
+    process.stderr.write(`Auto-updating ${staleSources.length} stale source(s)...\n`);
+
+    for (const source of staleSources) {
+      try {
+        await indexSources({ sourceName: source.name });
+        process.stderr.write(`  Updated: ${source.name}\n`);
+      } catch (err) {
+        process.stderr.write(`  Error updating ${source.name}: ${err.message}\n`);
+      }
+    }
+
+    process.stderr.write(`Auto-update complete.\n`);
+  } catch (err) {
+    process.stderr.write(`Auto-update failed: ${err.message}\n`);
+  }
+}
+
+autoUpdate();

package/src/presets.js

@@ -0,0 +1,68 @@
+export const PRESETS = {
+  'wp-core': {
+    name: 'wp-core',
+    type: 'github-public',
+    repo_url: 'https://github.com/WordPress/wordpress-develop.git',
+    branch: 'trunk',
+    content_type: 'source',
+  },
+  'gutenberg-source': {
+    name: 'gutenberg-source',
+    type: 'github-public',
+    repo_url: 'https://github.com/WordPress/gutenberg.git',
+    branch: 'trunk',
+    content_type: 'source',
+  },
+  'gutenberg-docs': {
+    name: 'gutenberg-docs',
+    type: 'github-public',
+    repo_url: 'https://github.com/WordPress/gutenberg.git',
+    subfolder: 'docs',
+    branch: 'trunk',
+    content_type: 'docs',
+  },
+  'plugin-handbook': {
+    name: 'plugin-handbook',
+    type: 'github-public',
+    repo_url: 'https://github.com/WordPress/developer-plugins-handbook.git',
+    branch: 'main',
+    content_type: 'docs',
+  },
+  'rest-api-handbook': {
+    name: 'rest-api-handbook',
+    type: 'github-public',
+    repo_url: 'https://github.com/WP-API/docs.git',
+    branch: 'master',
+    content_type: 'docs',
+  },
+  'wp-cli-handbook': {
+    name: 'wp-cli-handbook',
+    type: 'github-public',
+    repo_url: 'https://github.com/wp-cli/handbook.git',
+    branch: 'main',
+    content_type: 'docs',
+  },
+  'admin-handbook': {
+    name: 'admin-handbook',
+    type: 'github-public',
+    repo_url: 'https://github.com/WordPress/Advanced-administration-handbook.git',
+    branch: 'main',
+    content_type: 'docs',
+  },
+  'woocommerce': {
+    name: 'woocommerce',
+    type: 'github-public',
+    repo_url: 'https://github.com/woocommerce/woocommerce.git',
+    subfolder: 'plugins/woocommerce',
+    branch: 'trunk',
+    content_type: 'source',
+  },
+};
+
+export function getPreset(name) {
+  return PRESETS[name] || null;
+}
+
+export function listPresets() {
+  return Object.values(PRESETS);
+}

package/src/server/tools/get-doc.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { getDoc } from '../../db/sqlite.js';
+
+export const getDocSchema = {
+  name: 'get_doc',
+  description: 'Get the full content of a WordPress documentation page by its ID (numeric) or slug. Returns the complete markdown content along with metadata.',
+  inputSchema: {
+    doc: z.string().describe('Document ID (numeric) or slug string'),
+  },
+};
+
+export function handleGetDoc(args) {
+  try {
+    const doc = getDoc(args.doc);
+
+    if (!doc) {
+      return {
+        content: [{ type: 'text', text: `Document not found: "${args.doc}". Use search_docs to find documents first.` }],
+      };
+    }
+
+    const sections = [
+      `## ${doc.title}`,
+      `**Type:** ${doc.doc_type} | **Category:** ${doc.category || 'general'} | **Source:** ${doc.source_name}`,
+      `**File:** ${doc.file_path}`,
+      `**Slug:** ${doc.slug}`,
+    ];
+
+    if (doc.subcategory) sections.push(`**Subcategory:** ${doc.subcategory}`);
+    if (doc.status === 'removed') sections.push('**Status:** REMOVED');
+
+    if (doc.description) {
+      sections.push(`\n### Summary\n${doc.description}`);
+    }
+
+    sections.push(`\n### Content\n${doc.content}`);
+
+    if (doc.code_examples) {
+      try {
+        const examples = JSON.parse(doc.code_examples);
+        if (examples.length > 0) {
+          sections.push(`\n### Code Examples (${examples.length})`);
+          for (const ex of examples) {
+            sections.push(`\`\`\`${ex.language}\n${ex.code}\n\`\`\``);
+          }
+        }
+      } catch {
+        // Invalid JSON — skip
+      }
+    }
+
+    if (doc.metadata) {
+      try {
+        const meta = JSON.parse(doc.metadata);
+        const metaParts = [];
+        if (meta.endpoints) metaParts.push(`**Endpoints:** ${meta.endpoints.map(e => `${e.method} ${e.route}`).join(', ')}`);
+        if (meta.commands) metaParts.push(`**Commands:** ${meta.commands.join(', ')}`);
+        if (meta.package_refs) metaParts.push(`**Packages:** ${meta.package_refs.join(', ')}`);
+        if (meta.function_refs) metaParts.push(`**Functions:** ${meta.function_refs.join(', ')}`);
+        if (meta.hook_refs) metaParts.push(`**Hooks:** ${meta.hook_refs.join(', ')}`);
+        if (meta.config_defines) metaParts.push(`**Config defines:** ${meta.config_defines.join(', ')}`);
+        if (metaParts.length > 0) {
+          sections.push(`\n### Metadata\n${metaParts.join('\n')}`);
+        }
+      } catch {
+        // Invalid JSON — skip
+      }
+    }
+
+    return {
+      content: [{ type: 'text', text: sections.join('\n') }],
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error getting document: ${err.message}` }],
+      isError: true,
+    };
+  }
+}

package/src/server/tools/get-hook-context.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { getHookContext } from '../../db/sqlite.js';
+
+export const getHookContextSchema = {
+  name: 'get_hook_context',
+  description: 'Get full surrounding code context for a specific WordPress hook. Provide a hook ID (from search results) or exact hook name. Returns the code window around the hook, including the enclosing function, docblock, and parameters.',
+  inputSchema: {
+    hook: z.string().describe('Hook ID (numeric) or exact hook name'),
+  },
+};
+
+/**
+ * MCP tool handler — get full surrounding code context for a hook.
+ * @param {object} args - { hook } where hook is a numeric ID or exact name
+ * @returns {{ content: Array<{ type: string, text: string }>, isError?: boolean }}
+ */
+export function handleGetHookContext(args) {
+  try {
+    const hook = getHookContext(args.hook);
+
+    if (!hook) {
+      return {
+        content: [{ type: 'text', text: `Hook not found: "${args.hook}". Use search_hooks to find hooks first.` }],
+      };
+    }
+
+    const sections = [
+      `## ${hook.name}`,
+      `**Type:** ${hook.type} | **Source:** ${hook.source_name}`,
+      `**File:** ${hook.file_path}:${hook.line_number}`,
+    ];
+
+    if (hook.status === 'removed') sections.push('**Status:** REMOVED');
+    if (hook.class_name) sections.push(`**Class:** ${hook.class_name}`);
+    if (hook.php_function) sections.push(`**Function:** ${hook.php_function}()`);
+    if (hook.params) sections.push(`**Parameters:** ${hook.params}`);
+    if (hook.is_dynamic) sections.push('**Dynamic name:** yes');
+
+    if (hook.docblock) {
+      sections.push(`\n### Docblock\n\`\`\`\n${hook.docblock}\n\`\`\``);
+    }
+
+    if (hook.inferred_description) {
+      sections.push(`\n### Description\n${hook.inferred_description}`);
+    }
+
+    // Code context
+    const codeLines = [];
+    if (hook.code_before) codeLines.push(hook.code_before);
+    if (hook.hook_line) codeLines.push(`>>> ${hook.hook_line}`);
+    if (hook.code_after) codeLines.push(hook.code_after);
+
+    if (codeLines.length > 0) {
+      const lang = hook.type.startsWith('js_') ? 'js' : 'php';
+      sections.push(`\n### Code Context\n\`\`\`${lang}\n${codeLines.join('\n')}\n\`\`\``);
+    }
+
+    return {
+      content: [{ type: 'text', text: sections.join('\n') }],
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error getting hook context: ${err.message}` }],
+      isError: true,
+    };
+  }
+}