codemap_group_search

Search and list code groups. Empty name lists all groups with summaries. Specific name shows full details including all members and notations.

groupssearchlist

Parameters

Name	Type	Required	Description
`name`	`string`	❌ Optional	Optional: group name to search for. Empty lists all groups. Specific name shows full details.

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_group_search",
  "arguments": {}
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "group": {
      "name": "auth-system",
      "description": "Authentication and authorization module - handles login, JWT tokens, and permissions",
      "members": [
        {
          "type": "file",
          "path": "src/auth/login.ts"
        },
        {
          "type": "file",
          "path": "src/auth/jwt-handler.ts"
        },
        {
          "type": "symbol",
          "path": "src/middleware/auth.ts$authMiddleware"
        }
      ],
      "notations": [
        {
          "text": "Authentication and authorization module - handles login, JWT tokens, and permissions",
          "timestamp": 1704067200000,
          "date": "2024-01-01T00:00:00.000Z"
        },
        {
          "text": "Added OAuth 2.0 support with Google and GitHub providers",
          "file": "src/auth/oauth.ts",
          "line": 45,
          "timestamp": 1712534400000,
          "date": "2024-04-08T00:00:00.000Z"
        }
      ],
      "memberCount": 3,
      "notationCount": 2,
      "createdAt": 1704067200000,
      "updatedAt": 1712534400000
    }
  }
}

ℹ️When to Use This Tool

codemap_group_search

Find groups by name or partial name match
Get detailed view of a specific group
List all groups in the project (when no name provided)
Discover groups related to specific features or modules
Verify group contents before operations
Explore group organization and architecture

💡Common Patterns

List All Groups

Get overview of all groups:
1. Call codemap_group_search()  // No name parameter
2. Returns all groups with summaries
3. Review group names and descriptions
4. Identify groups for detailed inspection

Get Specific Group Details

View full group information:
1. Call codemap_group_search({ name: "auth-system" })
2. Returns complete group with:
   - All members (files, directories, symbols)
   - All notations with timestamps
   - Member/notation counts
   - Created/updated timestamps

Search by Pattern

Find groups matching a query:
1. codemap_group_search({ name: "api" })
2. Returns groups with "api" in the name
3. Shows matching groups with summaries
4. Useful for discovering related groups

💡Pro Tips

Empty name lists all groups: Omit name parameter to see all groups in project
Exact match shows full details: When name exactly matches a group, returns complete details with all members and notations
Partial match shows summaries: When name doesn't exactly match but finds similar groups, returns list of matching groups
First notation is always description: The group's description appears as the first notation
Stats included in list view: When listing all groups, response includes project-wide group statistics

✅Best Practices

Start with empty name to see all groups, then search for specific ones
Use exact group names when you know them for full details
Use partial names to discover related groups
Check memberCount before operations to understand group size
Review notations to understand group evolution and purpose
Verify group contents before adding/removing members or deleting

⚠️Common Mistakes

❌ Mistake: Expecting search to find groups by member path

codemap_group_search({ name: "src/auth/login.ts" })
// Searches for group named "src/auth/login.ts", not groups containing this file

✅ Instead: Use label search for finding groups by members

// To find which groups contain a file, list all groups and filter:
const all = codemap_group_search();
const containingGroups = all.data.groups.filter(g => 
  g.members.some(m => m.path.includes("src/auth/login.ts"))
);

---

❌ Mistake: Confusing search with list tool

// Thinking these are the same
codemap_group_search()
codemap_group_list()

✅ Instead: Understand the differences

// search: Returns all groups OR specific group details OR matching groups
codemap_group_search()                    // All groups with stats
codemap_group_search({ name: "api" })     // Full details OR matching summaries

// list: Paginated list with optional filters
codemap_group_list({ page: 1, pageSize: 20 })  // Paginated view
codemap_group_list({ name: "api" })             // Specific group details

---

❌ Mistake: Not checking if exact match or partial match

const result = codemap_group_search({ name: "api" });
// Assuming it's always a single group
const group = result.data.group;  // May be undefined

✅ Instead: Check response structure

const result = codemap_group_search({ name: "api" });

if (result.data.group) {
  // Exact match - single group details
  console.log(Found group: ${result.data.group.name});
} else if (result.data.groups) {
  // Partial matches - list of groups
  console.log(Found ${result.data.groups.length} matching groups);
}

---

❌ Mistake: Using search when you need member details

// Want to know if file is in group
const result = codemap_group_search({ name: "auth" });
// Have to manually check members array

✅ Instead: Get full group details for member inspection

const result = codemap_group_search({ name: "auth-system" });
const hasFile = result.data.group.members.some(
  m => m.path === "src/auth/login.ts"
);

---

❌ Mistake: Assuming group exists without checking

const result = codemap_group_search({ name: "nonexistent" });
const members = result.data.group.members;  // Error: undefined

✅ Instead: Always check response structure

const result = codemap_group_search({ name: "api-layer" });

if (!result.success) {
  console.error("Search failed:", result.error.message);
} else if (result.data.group) {
  // Process single group
  const members = result.data.group.members;
} else if (result.data.groups) {
  // Process matching groups
  console.log(Found ${result.data.groups.length} matches);
} else {
  console.log("No groups found");
}