codemap_group_notate

Add a notation/comment to an existing group. Optionally reference a specific file and line number.

groupsnotationcomments

Parameters

Name	Type	Required	Description
`name`	`string`	✅ Required	Group name
`text`	`string`	✅ Required	Notation text/comment to add to the group
`file`	`string`	❌ Optional	Optional: file reference for the notation
`line`	`number`	❌ Optional	Optional: line number in the file

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_group_notate",
  "arguments": {
    "name": "api-routes",
    "text": "Added rate limiting middleware to all endpoints"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "group": "auth-system",
    "notation": {
      "text": "Added OAuth 2.0 support with Google and GitHub providers",
      "file": "src/auth/oauth.ts",
      "line": 45,
      "timestamp": 1712534400000
    },
    "totalNotations": 4
  }
}

ℹ️When to Use This Tool

codemap_group_notate

Document group evolution and changes over time
Add context about why files belong together
Record architectural decisions related to the group
Link group documentation to specific code locations
Create audit trail of group-related discoveries
Add implementation notes that span multiple files

💡Common Patterns

Document Group Evolution

Track changes as group develops:
1. Initial: "User authentication module"
2. Add notation: codemap_group_notate({ 
     name: "auth-system",
     text: "Added OAuth 2.0 support - Google and GitHub providers"
   })
3. Later: "Migrated from JWT to sessions for mobile clients"

File-Specific Context

Link notation to specific implementation:
codemap_group_notate({
  name: "payment-gateway",
  text: "Stripe webhook handler - processes subscription events",
  file: "src/webhooks/stripe.ts",
  line: 127
})

Architectural Decision Records

Document why files are grouped:
codemap_group_notate({
  name: "api-layer",
  text: "Separated from service layer per clean architecture - API handles HTTP, services contain business logic"
})

💡Pro Tips

Notations are timestamped: Each notation includes automatic timestamp for chronological tracking
File/line references are optional: Use when notation relates to specific code location
First notation is the description: When group is created, description becomes first notation
Notations accumulate: Each call adds a new notation - they build up over time
View all notations: Use codemap_group_search({ name: "group" }) to see full notation history

✅Best Practices

Add notations when discovering patterns or making architectural observations
Include file/line references when notation explains specific implementation
Use clear, descriptive text that will be useful months later
Document decisions and rationale, not just implementation details
Add notations during code reviews to capture team insights
Create notation when refactoring to explain changes to future developers

⚠️Common Mistakes

❌ Mistake: Adding notations to non-existent groups

codemap_group_notate({ 
  name: "api-v2",  // Group doesn't exist
  text: "New REST endpoints"
})
// Error: Group "api-v2" not found

✅ Instead: Create group first, then add notations

codemap_group_add({ 
  name: "api-v2",
  description: "Version 2 REST API",
  members: ["src/api/v2/**/*"]
})
codemap_group_notate({ 
  name: "api-v2",
  text: "New REST endpoints follow OpenAPI 3.1 spec"
})

---

❌ Mistake: Using notations like TODO comments

codemap_group_notate({ 
  name: "auth",
  text: "TODO: Fix password reset bug"
})

✅ Instead: Use issue tracker for TODOs, notations for context

codemap_group_notate({ 
  name: "auth",
  text: "Password reset uses time-limited tokens (15min expiry) per security req SR-2024-03"
})

---

❌ Mistake: Providing line number without file

codemap_group_notate({ 
  name: "utils",
  text: "Critical validation function",
  line: 45  // Line in which file?
})

✅ Instead: Always provide file when using line reference

codemap_group_notate({ 
  name: "utils",
  text: "Critical email validation - used across all user inputs",
  file: "src/utils/validators.ts",
  line: 45
})

---

❌ Mistake: Empty or vague notation text

codemap_group_notate({ 
  name: "api",
  text: "Updated"  // What was updated? Why?
})

✅ Instead: Be specific and informative

codemap_group_notate({ 
  name: "api",
  text: "Migrated from Express to Fastify for 2x better throughput - maintained API compatibility"
})

---

❌ Mistake: Duplicating information from code comments

// In code: "Handles user login"
codemap_group_notate({ 
  name: "auth",
  text: "Handles user login"  // Redundant
})

✅ Instead: Add group-level context code comments don't provide

codemap_group_notate({ 
  name: "auth",
  text: "Authentication system uses session-based auth for web, JWT for mobile - sharing common validation logic in auth/core"
})