codemap_get_annotations
Get @codemap annotations for a file or scoped to a specific symbol. Symbol targeting (relativePath$symbolName) filters annotations to only those within that symbol's line range, excluding file-level meta/domain annotations.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
target | string | ✅ Required | Relative path to the file, or symbol reference (relativePath$symbolName) to filter annotations to that symbol's scope |
type | string | ❌ Optional | Filter by annotation type: systempolicy|policy|warning|note|gate|contract |
severity | string | ❌ Optional | Filter by severity: error|warning|info |
Usage Examples
MCP Usage (for AI Agents like Claude)
json
{
"name": "codemap_get_annotations",
"arguments": {
"target": "src/auth/middleware.ts"
}
}Example Output
JSON Response
json
{
"success": true,
"data": {
"file": "src/middleware/auth.ts",
"annotations": [
{
"category": "policy",
"text": "Must validate JWT before proceeding",
"severity": "warning",
"line": 10,
"source": "inline"
},
{
"category": "note",
"text": "Consider rate limiting",
"severity": "info",
"line": 25,
"source": "inline"
}
],
"annotationCount": 2
}
}When to Use This Tool
-
Use
- Check for policy violations or warnings
- Review code documentation notes
- Find security or architectural gates
- Audit contract annotations
codemap_get_annotations when you need to:
Common Patterns
Pre-Commit Check
Documentation Generation
Policy Enforcement
1. Get annotations with severity=error
2. If any found, block commit
3. Display issues to developerDocumentation Generation
1. Get annotations with type=note
2. Extract documentation
3. Generate README sectionsPolicy Enforcement
1. Get policy annotations
2. Verify compliance
3. Report violationsPro Tips
- Filter by severity for quality gates: Use severity=error to find blocking issues
- Check type=policy for governance: Policy annotations enforce architectural rules
- Combine with peek for context: Annotations plus symbols gives complete picture
- Use in CI/CD pipelines: Automated annotation checks prevent policy violations
Best Practices
- Filter by severity in quality gates
- Use type=policy for architectural enforcement
- Check annotations before deployments
- Document annotations clearly in code
- Review error-level annotations immediately
Common Mistakes
❌ Mistake: Ignoring error-severity annotations
✅ Instead: Treat error-level annotations as blocking issues
❌ Mistake: Not filtering when you only need specific types
✅ Instead: Use type and severity filters for focused results
❌ Mistake: Expecting annotations to exist in all files
✅ Instead: Handle empty results gracefully
✅ Instead: Treat error-level annotations as blocking issues
❌ Mistake: Not filtering when you only need specific types
✅ Instead: Use type and severity filters for focused results
❌ Mistake: Expecting annotations to exist in all files
✅ Instead: Handle empty results gracefully