WP Navigator MCP

Instructions

Implementation Reference

• src/tools/core/context.ts:324-369 (handler)

  Handler for the wpnav_context tool. Calls buildContextOutput to generate site context and returns it as JSON, with error handling.
  /** * Handler for wpnav_context * * Returns context dump for AI agent initialization. */ export async function contextToolHandler( args: { compact?: boolean; include_snapshot?: boolean }, context: ToolExecutionContext ): Promise<ToolResult> { const { compact = true, include_snapshot = false } = args; try { const contextOutput = await buildContextOutput(context, { compact, includeSnapshot: include_snapshot, }); return { content: [ { type: 'text', text: JSON.stringify(contextOutput, null, 2), }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: 'text', text: JSON.stringify( { error: 'CONTEXT_FAILED', message: `Failed to gather context: ${errorMessage}`, hint: 'Ensure WordPress site is reachable and WP Navigator plugin is active', }, null, 2 ), }, ], }; } }
• src/tools/core/context.ts:295-318 (schema)

  Tool definition object for wpnav_context, including name, description, and inputSchema with optional compact and include_snapshot parameters.
  /** * Tool definition for wpnav_context */ export const contextToolDefinition = { name: 'wpnav_context', description: 'Get a compact context dump of the WordPress site including focus mode, available tools, active role, cookbooks, site info, and safety settings. Designed for AI agent initialization.', inputSchema: { type: 'object' as const, properties: { compact: { type: 'boolean', description: 'If true, returns minimal context (~200-300 tokens). If false, includes full tool list and role context.', default: true, }, include_snapshot: { type: 'boolean', description: 'If true, includes a summary of pages and posts. Increases token usage.', default: false, }, }, }, };
• src/tools/core/context.ts:375-384 (registration)

  Registers the wpnav_context tool definition and handler with the central toolRegistry.
  /** * Register the context tool */ export function registerContextTool(): void { toolRegistry.register({ definition: contextToolDefinition, handler: contextToolHandler, category: ToolCategory.CORE, }); }
• src/tools/core/context.ts:172-289 (helper)

  Core helper function that orchestrates gathering of all context data: introspect WP site, load manifest, get focus mode/tools/role/cookbooks/safety/AI settings, and builds the ContextOutput object.
  export async function buildContextOutput( context: ToolExecutionContext, options: { compact?: boolean; includeSnapshot?: boolean } = {} ): Promise<ContextOutput> { // 1. Fetch introspect data from WordPress const introspect = (await context.wpRequest('/wpnav/v1/introspect')) as Record<string, unknown>; // 2. Load manifest const manifestResult = loadManifest(); const manifest = manifestResult.found && manifestResult.manifest && isManifestV2(manifestResult.manifest) ? manifestResult.manifest : null; // 3. Get focus mode const focusMode = manifest ? getFocusMode(manifest) : 'content-editing'; const focusModePreset = getFocusModePreset(focusMode); // 4. Get enabled tools const allTools = toolRegistry.getAllDefinitions(); const enabledTools = allTools.filter((t) => toolRegistry.isEnabled(t.name)); const toolsByCategory = groupToolsByCategory(enabledTools); // 5. Get active role const activeRoleSlug = runtimeRoleState.getRole(); let activeRole: LoadedRole | null = null; if (activeRoleSlug) { activeRole = getRole(activeRoleSlug) || null; } // 6. Get cookbooks const { cookbooks: availableCookbooks } = discoverCookbooks(); const loadedCookbooks: string[] = []; const recommendedCookbooks: string[] = []; // Check for detected plugins that have matching cookbooks const detectedPlugins = detectPlugins(introspect); for (const cookbook of availableCookbooks.values()) { const cookbookSlug = cookbook.plugin.slug.toLowerCase(); const cookbookPluginName = cookbook.plugin.name.toLowerCase(); for (const plugin of detectedPlugins) { const pluginLower = plugin.toLowerCase(); if ( pluginLower.includes(cookbookSlug) || cookbookSlug.includes(pluginLower) || pluginLower.includes(cookbookPluginName) || cookbookPluginName.includes(pluginLower) ) { recommendedCookbooks.push(cookbook.plugin.name); break; } } } // 7. Get safety settings const safety = manifest ? getManifestSafetyV2(manifest) : null; const safetyMode = safety?.mode || 'normal'; const safetyOps = getSafetyOperations(safetyMode); // 8. Get AI settings const ai = manifest ? getManifestAI(manifest) : null; // 9. Determine environment const environment = 'production'; // Build context output const contextOutput: ContextOutput = { focus_mode: { name: focusMode, description: focusModePreset.description, token_estimate: focusModePreset.tokenEstimate, }, tools: { total_available: allTools.length, enabled: enabledTools.length, by_category: toolsByCategory, // Include tool list only if not compact mode ...(!options.compact ? { list: enabledTools.map((t) => t.name) } : {}), }, role: activeRole ? { active: activeRoleSlug, name: activeRole.name, context: !options.compact ? activeRole.context : null, focus_areas: activeRole.focus_areas || [], tools_allowed: activeRole.tools?.allowed || [], tools_denied: activeRole.tools?.denied || [], } : null, cookbooks: { loaded: loadedCookbooks, available: Array.from(availableCookbooks.keys()), recommended: recommendedCookbooks, }, site: { name: (introspect.site_name as string) || null, url: context.config.baseUrl, plugin_version: (introspect.plugin_version as string) || (introspect.version as string) || null, plugin_edition: (introspect.edition as string) || null, detected_plugins: detectedPlugins, page_builder: (introspect.page_builder as string) || null, }, safety: { mode: safetyMode, enable_writes: context.config.toggles.enableWrites, allowed_operations: safetyOps.allowed, blocked_operations: safetyOps.blocked, }, ai: { instructions: ai?.instructions || null, prompts_path: ai?.prompts_path || null, }, environment, }; return contextOutput; }
• src/mcp-server.ts:71-77 (registration)

  wpnav_context is listed in META_TOOLS, enabling direct execution via the MCP server's CallTool handler (bypassing the general wpnav_execute requirement).
  const META_TOOLS = new Set([ 'wpnav_introspect', 'wpnav_search_tools', 'wpnav_describe_tools', 'wpnav_execute', 'wpnav_context', ]);