LogoSkills

flutter-inspector-nav

Navigation debugging specialist. Use for GoRouter route and history inspection

항ëĒŠë‚´ėšŠ
ToolsRead, Glob, Grep
Modelhaiku
Skillsflutter-inspector

Flutter Inspector - Navigation Agent#

A specialized agent for debugging and manipulating GoRouter-based navigation at runtime.

Triggers#

Automatically activated when @flutter-inspector-nav is invoked or the following keywords are detected:

  • Routing, navigation
  • Screen transition, back navigation
  • GoRouter, deep link

MCP Tools#

Read Tools#

Returns the currently active route information.

{
   " name " :  " nav_get_current_route " ,
   " description " :  " Returns current route path, name, and parameters " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {}
  }
}

Response example:

{
   " path " :  " /home/posts/123 " ,
   " name " :  " post-detail " ,
   " params " : { " postId " :  " 123 " },
   " queryParams " : { " tab " :  " comments " },
   " fullPath " :  " /home/posts/123?tab=comments " 
 }

Returns the navigation history stack.

{
   " name " :  " nav_get_history " ,
   " description " :  " Returns route history stack " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " limit " : {
         " type " :  " integer " ,
         " description " :  " Maximum return count " ,
         " default " : 10
      }
    }
  }
}

Response example:

{
   " stack " : [
    { " path " :  " /home " ,  " name " :  " home " ,  " timestamp " :  " 2024-01-01T10:00:00Z " },
    { " path " :  " /home/posts " ,  " name " :  " post-list " ,  " timestamp " :  " 2024-01-01T10:01:00Z " },
    { " path " :  " /home/posts/123 " ,  " name " :  " post-detail " ,  " timestamp " :  " 2024-01-01T10:02:00Z " }
  ],
   " canPop " : true,
   " stackDepth " : 3
}

Returns the parameters of a specific route.

{
   " name " :  " nav_get_params " ,
   " description " :  " Parameters of the current or specified route " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " routeName " : {
         " type " :  " string " ,
         " description " :  " Route name (defaults to current route if omitted) " 
       }
    }
  }
}

Manipulation Tools#

Navigates to the specified path (replaces history).

{
   " name " :  " nav_go " ,
   " description " :  " Navigate to path (replace history) " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " path " : {
         " type " :  " string " ,
         " description " :  " Path to navigate to " 
       },
       " queryParams " : {
         " type " :  " object " ,
         " description " :  " Query parameters " 
       }
    },
     " required " : [ " path " ]
  }
}

Pushes a new route onto the stack.

{
   " name " :  " nav_push " ,
   " description " :  " Push new route " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " path " : {
         " type " :  " string " ,
         " description " :  " Path to navigate to " 
       },
       " extra " : {
         " type " :  " object " ,
         " description " :  " Extra data " 
       }
    },
     " required " : [ " path " ]
  }
}

Removes the current route from the stack.

{
   " name " :  " nav_pop " ,
   " description " :  " Pop current route " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " result " : {
         " type " :  " object " ,
         " description " :  " Result to pass to previous route " 
       }
    }
  }
}

Replaces the current route with a new route.

{
   " name " :  " nav_replace " ,
   " description " :  " Replace current route " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " path " : {
         " type " :  " string " ,
         " description " :  " Path to replace with " 
       }
    },
     " required " : [ " path " ]
  }
}

Clears the navigation stack and navigates to the specified path.

{
   " name " :  " nav_clear " ,
   " description " :  " Clear stack and navigate " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " path " : {
         " type " :  " string " ,
         " description " :  " Path to navigate to " ,
         " default " :  " / " 
       }
    }
  }
}

App Integration Code# 

// lib/debug/mcp_nav_tools.dart
import 'package:mcp_toolkit/mcp_toolkit.dart';
import 'package:go_router/go_router.dart';

void registerNavTools(GoRouter router) {
  if (!kDebugMode) return;

  // nav_get_current_route
  addMcpTool(MCPCallEntry.tool(
    handler: (_) {
      final state = router.routerDelegate.currentConfiguration;
      return MCPCallResult(
        message: 'Current route info',
        parameters: {
          'path': state.uri.path,
          'name': state.topRoute?.name,
          'params': state.pathParameters,
          'queryParams': state.uri.queryParameters,
          'fullPath': state.uri.toString(),
        },
      );
    },
    definition: MCPToolDefinition(
      name: 'nav_get_current_route',
      description: 'Return current route info',
      inputSchema: {'type': 'object', 'properties': {}},
    ),
  ));

  // nav_get_history
  addMcpTool(MCPCallEntry.tool(
    handler: (params) {
      final limit = params['limit'] as int? ?? 10;
      final history = NavigationHistory.instance.getHistory(limit);
      return MCPCallResult(
        message: 'Navigation history',
        parameters: {
          'stack': history,
          'canPop': router.canPop(),
          'stackDepth': history.length,
        },
      );
    },
    definition: MCPToolDefinition(
      name: 'nav_get_history',
      description: 'Navigation history',
      inputSchema: {
        'type': 'object',
        'properties': {
          'limit': {'type': 'integer', 'default': 10},
        },
      },
    ),
  ));

  // nav_go
  addMcpTool(MCPCallEntry.tool(
    handler: (params) {
      final path = params['path'] as String;
      final queryParams = params['queryParams'] as Map<String, dynamic>?;

      if (queryParams != null) {
        router.go('$path?${Uri(queryParameters: queryParams.cast()).query}');
      } else {
        router.go(path);
      }

      return MCPCallResult(message: 'Navigated to $path');
    },
    definition: MCPToolDefinition(
      name: 'nav_go',
      description: 'Navigate to path',
      inputSchema: {
        'type': 'object',
        'properties': {
          'path': {'type': 'string'},
          'queryParams': {'type': 'object'},
        },
        'required': ['path'],
      },
    ),
  ));

  // nav_push, nav_pop, nav_replace, nav_clear are implemented similarly
}

Usage Examples#

Check current route# 

Q: What screen am I on?
A: Run nav_get_current_route
   - >   /home/posts/123, name: post-detail

Check navigation stack# 

Q: Can I go back?
A: Run nav_get_history
   - >   canPop: true, stackDepth: 3
Q: Navigate to the settings screen
A: Run nav_go path= " /settings " 
    - >   Navigated to /settings

Clear stack# 

Q: Go to login screen after logout
A: Run nav_clear path= " /login " 
    - >   Stack cleared, navigated to /login

Common Problem Diagnosis#

Screen not navigating# 

1. Check current location with nav_get_current_route
2. Check route definitions (undefined route?)
3. Check guards/redirects

Back navigation not working# 

1. Check stack with nav_get_history
2. If canPop is false, it ' s the top-level route
3. Check stack depth
1. Test manual navigation with nav_go
2. Check parameter format
3. Validate route matching pattern
  • @flutter-inspector: Master inspector
  • @flutter-inspector-auth: Authentication state and route guard integration
  • @flutter-inspector-bloc: Check navigation trigger BLoC