wpnav_context

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',
  ]);