codemap_search_annotations

Search @codemap annotations by query string.

annotationssearch

Parameters

Name	Type	Required	Description
`query`	`string`	✅ Required	Search query string
`type`	`string`systempolicy \| policy \| warning \| note \| gate \| contract	❌ Optional	Filter by annotation type
`severity`	`string`error \| warning \| info	❌ Optional	Filter by severity
`maxResults`	`number`	❌ Optional	Maximum results to return (default: 50)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_search_annotations",
  "arguments": {
    "query": "author"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "query": "author",
    "matches": [
      {
        "file": "src/utils/helpers.ts",
        "line": 1,
        "category": "note",
        "path": "",
        "value": "Jane Smith",
        "raw": "@codemap.note [info] author: Jane Smith"
      },
      {
        "file": "src/core/Engine.ts",
        "line": 1,
        "category": "note",
        "path": "",
        "value": "Engineering Team",
        "raw": "@codemap.note [info] author: Engineering Team"
      }
    ],
    "matchCount": 2,
    "truncated": false
  }
}

ℹ️When to Use This Tool

codemap_search_annotations

Audit metadata coverage - Find which files have specific annotations like 'owner' or 'reviewed'
Track workflow status - Identify all files in a particular stage (experimental, beta, production)
Find documentation gaps - Search for files missing 'docs' annotations
Migration tracking - Monitor progress of migrations by searching for status annotations
Review planning - Find files that haven't been reviewed recently
Version inventory - List all files with version annotations to plan updates
Ownership mapping - Identify files owned by specific teams or individuals

💡Common Patterns

Workflow Status Tracking

// Find all files by development stage
const stages = ['planning', 'development', 'review', 'testing', 'production'];

for (const stage of stages) {
  const results = await codemap.annotations.search({ query: status: ${stage} });
  console.log(${stage}: ${results.matchCount} files);
}

Team Ownership Audit

// Find files owned by each team
const teams = ['frontend', 'backend', 'infra', 'security'];

for (const team of teams) {
  const owned = await codemap.annotations.search({ query: team: ${team} });
  console.log(${team} owns ${owned.matchCount} files);
}

Documentation Coverage

// Check documentation coverage
const allFiles = await codemap.search({ query: '*.ts', mode: 'text' });
const documented = await codemap.annotations.search({ query: 'docs:' });

const coverage = (documented.matchCount / allFiles.files.length) * 100;
console.log(Documentation coverage: ${coverage.toFixed(1)}%);

Review Status Dashboard

// Generate review status report
const reviewed = await codemap.annotations.search({ query: 'reviewed:' });
const pending = await codemap.annotations.search({ query: 'needs-review' });

console.log('Review Dashboard:');
console.log(  Reviewed: ${reviewed.matchCount});
console.log(  Pending: ${pending.matchCount});

💡Pro Tips

Use specific queries - Search for "owner: john" instead of just "john" to avoid false positives from code comments.

Combine with other tools - Use search_annotations to find files, then use codemap_get_annotations to see all metadata for specific files.

Track temporal data - Search for date-based annotations like 'reviewed: 2026' to find files reviewed in a specific time period.

Monitor migration progress - Regularly search for migration status annotations to track completion percentage.

Audit before bulk operations - Before bulk-editing or removing annotations, search first to preview what will be affected.

Use maxResults wisely - Start with default limits, increase only if you need comprehensive results. Large result sets can be slow.

✅Best Practices

Establish naming conventions - Use consistent annotation keys across your team so searches are predictable (e.g., always 'owner' not 'author' or 'maintainer').

Search before removing - Always search for an annotation key before bulk removal to understand the impact.

Regular audits - Schedule periodic searches to identify annotation drift or obsolete metadata.

Document search patterns - Save common search queries in team documentation or scripts for reusable audits.

Combine searches - Run multiple searches with different queries to build comprehensive reports.

Filter by type when possible - If you know the annotation type, filter by it to narrow results and improve performance.

⚠️Common Mistakes

❌ Mistake: Searching for values without the key

// Ambiguous - could match in code or comments
await codemap.annotations.search({ query: 'experimental' });

✅ Instead: Include the key for precision

await codemap.annotations.search({ query: 'status: experimental' });

---

❌ Mistake: Not handling truncated results

const results = await codemap.annotations.search({ query: 'version' });
console.log(Found all ${results.matchCount} versions);
// Might be truncated!

✅ Instead: Check truncation flag

const results = await codemap.annotations.search({ query: 'version' });
if (results.truncated) {
  console.warn('Results truncated - use higher maxResults');
  console.log(Showing ${results.matchCount} of possibly more matches);
} else {
  console.log(Found all ${results.matchCount} matches);
}

---

❌ Mistake: Assuming search is case-sensitive

// Might not find "Author: John" if you search "author"
await codemap.annotations.search({ query: 'author: john' });

✅ Instead: Remember search is case-insensitive

// This will find "Author", "AUTHOR", and "author"
await codemap.annotations.search({ query: 'author' });
// But be aware values are also case-insensitive matched

---

❌ Mistake: Not filtering results in application code

// Gets all 'status' annotations including irrelevant ones
const results = await codemap.annotations.search({ query: 'status' });
// Then manually filtering in code
const experimental = results.matches.filter(m => m.value === 'experimental');

✅ Instead: Search for the specific value

// More efficient - search does the filtering
const experimental = await codemap.annotations.search({ 
  query: 'status: experimental' 
});

---

❌ Mistake: Searching without understanding the data structure

// Expecting structured data
const results = await codemap.annotations.search({ query: 'config' });
// But annotations are simple key-value pairs

✅ Instead: Use appropriate annotation structure

// Annotations are flat key-value pairs
// For nested config, use multiple annotations:
// config-port: 3000
// config-host: localhost
const portResults = await codemap.annotations.search({ query: 'config-port' });
const hostResults = await codemap.annotations.search({ query: 'config-host' });