wpnav_introspect

Instructions

Implementation Reference

• src/tools/core/index.ts:78-160 (handler)

  Full registration and handler implementation for the wpnav_introspect tool. Fetches data from the WPNav introspect endpoint, active plugins, current user capabilities, discovers available cookbooks and roles based on active plugins, determines recommended role, and returns a comprehensive JSON response with API capabilities, policies, and environment hints.

  toolRegistry.register({
    definition: {
      name: 'wpnav_introspect',
      description:
        'Get WP Navigator Pro API capabilities, policy configuration, and environment hints. Call this first to understand what the API can do.',
      inputSchema: {
        type: 'object',
        properties: {},
        required: [],
      },
    },
    handler: async (args, context) => {
      const { wpRequest, config } = context;
  
      // Fetch introspect, active plugins, and current user in parallel
      const [introspectData, wpPlugins, currentUser] = await Promise.all([
        wpRequest(config.wpnavIntrospect),
        wpRequest('/wp/v2/plugins?status=active').catch(() => []),
        wpRequest('/wp/v2/users/me').catch(() => null),
      ]);
  
      // Discover available cookbooks and roles
      const { cookbooks } = discoverCookbooks();
      const { roles: rolesMap } = discoverRoles();
  
      // Extract active plugin slugs from WordPress response
      // WordPress plugin slugs are in format "plugin-dir/plugin-file.php"
      const pluginArray = Array.isArray(wpPlugins) ? wpPlugins : [];
      const activePluginSlugs = new Set(
        pluginArray.map((p: { plugin?: string }) => {
          const pluginFile = p.plugin || '';
          return pluginFile.split('/')[0] || pluginFile;
        })
      );
  
      // Build available_cookbooks array
      const availableCookbooks = Array.from(cookbooks.entries()).map(([slug, cookbook]) => {
        const skillCookbook = cookbook as LoadedSkillCookbook;
        return {
          slug,
          description: skillCookbook.skillFrontmatter?.description || null,
          detected: activePluginSlugs.has(slug),
        };
      });
  
      // Build available_roles array and determine recommended role
      const availableRoles = Array.from(rolesMap.keys()).sort();
  
      // Determine recommended role based on WordPress user capabilities
      const userRoles: string[] = (currentUser as any)?.roles || [];
      let recommendedRole = 'content-editor'; // Safe default
  
      if (userRoles.includes('administrator')) {
        recommendedRole = 'site-admin';
      } else if (userRoles.includes('editor')) {
        recommendedRole = 'content-editor';
      } else if (userRoles.includes('author') || userRoles.includes('contributor')) {
        recommendedRole = 'content-editor';
      }
      // For subscriber or unknown roles, default to content-editor (already set)
  
      // Augment response with cookbook and role discovery
      const response = {
        ...(introspectData as object),
        available_cookbooks: availableCookbooks,
        roles: {
          available: availableRoles,
          recommended: recommendedRole,
          count: availableRoles.length,
        },
      };
  
      return {
        content: [
          {
            type: 'text',
            text: context.clampText(JSON.stringify(response, null, 2)),
          },
        ],
      };
    },
    category: ToolCategory.CORE,
  });

• src/mcp-server.ts:71-77 (registration)

  Registers wpnav_introspect as a core meta-tool that is directly exposed via the MCP ListTools response and can be called directly via CallToolRequest, unlike other tools which require wpnav_execute.

  const META_TOOLS = new Set([
    'wpnav_introspect',
    'wpnav_search_tools',
    'wpnav_describe_tools',
    'wpnav_execute',
    'wpnav_context',
  ]);

• src/tools.ts:36-45 (schema)

  Static schema definition for the wpnav_introspect tool, matching the runtime definition used in registration.

  {
    name: 'wpnav_introspect',
    description:
      'Get WP Navigator Pro API capabilities, policy configuration, and environment hints. Call this first to understand what the API can do.',
    inputSchema: {
      type: 'object' as const,
      properties: {},
      required: [],
    },
  },

• src/tools/index.ts:36-37 (registration)

  Calls registerCoreTools() which includes registration of wpnav_introspect during server startup.

  export function registerAllTools() {
    registerCoreTools();