MCP Efficiency

Master MCP tools to reduce token usage while improving code understanding.

CRITICAL: search_for_pattern Token Limits

WARNING: Improper use of search_for_pattern causes 20k+ token responses!

MANDATORY Parameters for search_for_pattern

| Parameter | REQUIRED | Default Danger | |-----------|----------|----------------| | relative_path | ALWAYS set | Full codebase = 50k+ tokens | | context_lines_after | 0-2 max | High values = exponential growth | | max_answer_chars | 3000-5000 | No limit = unbounded output |

Quick Examples

# BAD - Will return 20k+ tokens:
search_for_pattern(substring_pattern=r"import.*Dto")
search_for_pattern(substring_pattern=r".*Mapper\.kt")  # Wrong tool!

# GOOD - Scoped and limited:
search_for_pattern(
    substring_pattern=r"@Service",
    relative_path="module-core-domain/",
    context_lines_after=1,
    max_answer_chars=3000
)

Use Correct Tool

| Need | WRONG | CORRECT | |------|-------|---------| | Find files | search_for_pattern(r".*\.kt") | find_file(file_mask="*.kt") | | Signatures | search_for_pattern | find_symbol(include_body=False) | | Structure | search_for_pattern | get_symbols_overview |

Serena Infrastructure (Project-Specific)

Cache Structure

.serena/
├── cache/
│   ├── documents/              # Document index for token-efficient search
│   │   └── document_index.json # Indexed docs with tag/title/content search
│   ├── kotlin/                 # Kotlin symbol cache (basecamp-server)
│   ├── python/                 # Python symbol cache (parser, connect, cli)
│   │   ├── document_symbols.pkl
│   │   └── raw_document_symbols.pkl
│   └── typescript/             # TypeScript symbol cache (basecamp-ui)
├── memories/                   # Project patterns and knowledge
│   ├── server_patterns.md      # Spring Boot/Kotlin patterns
│   ├── ui_patterns.md          # React/TypeScript patterns
│   ├── cli_patterns.md         # Python CLI patterns
│   ├── cli_test_patterns.md    # pytest/fixture patterns
│   ├── parser_patterns.md      # Flask/SQLglot patterns
│   └── connect_patterns.md     # Integration patterns
└── project.yml                 # Project configuration

Make Commands (Cache Sync)

| Command | Purpose | |---------|---------| | make serena-server | Update basecamp-server symbols, docs & memories | | make serena-ui | Update basecamp-ui symbols, docs & memories | | make serena-parser | Update basecamp-parser symbols, docs & memories | | make serena-connect | Update basecamp-connect symbols, docs & memories | | make serena-cli | Update interface-cli symbols, docs & memories | | make serena-update-all | Force update all projects | | make serena-status | Check cache status | | make doc-search q="query" | Search documentation index (94% savings) |

Post-Implementation Cache Sync

After making significant changes, sync the Serena cache:

# After server changes
make serena-server

# After UI changes
make serena-ui

# After CLI changes
make serena-cli

# Check cache status
make serena-status

Why This Matters

| Approach | Tokens | Use Case | |----------|--------|----------| | Read full file | 5000+ | Rarely needed | | Serena overview | 200-500 | Structure understanding | | Serena find_symbol | 100-300 | Specific signatures | | Context7 docs | 500-1000 | Framework patterns |

Rule: Never read a file until MCP tools fail to answer the question.

Document Search (NEW - Priority 0)

BEFORE using Serena symbol queries, search project documentation for patterns/context:

Quick Search (CLI)

# Search indexed documentation
python3 scripts/serena/document_indexer.py --search "hexagonal architecture" --max-results 5

Token Comparison

| Documentation Need | Old Way | New Way | Savings | |-------------------|---------|---------|---------| | Find architecture pattern | Read PATTERNS.md (5000 tokens) | Doc search (300 tokens) | 94% | | Check entity rules | Read README.md (3000 tokens) | Doc search (400 tokens) | 87% | | API reference | Read multiple docs (8000 tokens) | Doc search (500 tokens) | 94% |

Document Search Workflow

# Step 1: Search document index FIRST
# CLI: python3 scripts/serena/document_indexer.py --search "repository pattern"

# Step 2: Read only relevant section (from search results)
# If result shows: line_start=45, line_end=80
Read(file_path="project-basecamp-server/docs/PATTERNS.md", offset=45, limit=35)

# Step 3: Then use Serena for code exploration
serena.get_symbols_overview("module-core-domain/repository/")

When to Use Document Search

| Need | Use Document Search First? | |------|---------------------------| | Architecture patterns | YES - search tag:architecture | | Implementation guide | YES - search tag:implementation | | API endpoint info | YES - search tag:api | | Test patterns | YES - search tag:testing | | Specific code implementation | NO - use Serena directly | | Framework best practices | NO - use Context7 |

See doc-search skill for comprehensive guide.

MCP Server Reference

| Server | Purpose | Best For | |--------|---------|----------| | serena | Semantic code analysis | Symbol navigation, references, refactoring, memory | | context7 | Framework docs | Best practices, API usage | | jetbrains | IDE integration | Inspections, refactoring, run configurations | | claude-mem | Cross-session memory | Past decisions, timeline, batch queries |

Server Strengths

Serena (30+ languages via LSP):

Symbol-level code understanding (not just text search)
Project memory for patterns and decisions
Semantic editing (insert_after_symbol, replace_symbol_body)

JetBrains (IDE 2025.2+):

IntelliJ inspections (errors, warnings, code smells)
Rename refactoring (understands code structure)
Run configurations and terminal commands

claude-mem (Cross-session):

Search past work across all sessions
Timeline context around decisions
Batch fetch for efficiency

Serena Workflow (Primary)

Step 1: Understand Structure

# Get file overview (no body content)
serena.get_symbols_overview(relative_path="src/services/")

# Result: Lists classes, functions with signatures only
# Token cost: ~200-500 (vs 5000+ for full file)

Step 2: Find Specific Symbols

# Find by name pattern
serena.find_symbol(
    name_path_pattern="UserService",
    depth=1,                    # Include immediate children
    include_body=False          # Signatures only
)

# Find with body (when needed)
serena.find_symbol(
    name_path_pattern="UserService/createUser",
    include_body=True           # Get implementation
)

Step 3: Trace Dependencies

# Who calls this method?
serena.find_referencing_symbols(
    name_path="createUser",
    relative_path="src/services/UserService.kt"
)

# Result: All callers with file:line references

Step 4: Pattern Search (TOKEN CRITICAL)

WARNING: search_for_pattern can easily return 20k+ tokens with wrong settings!

# BAD: Returns 20k+ tokens (all controller bodies)
serena.search_for_pattern(
    substring_pattern=r"@RequestMapping.*",
    context_lines_after=10  # NEVER use high context!
)

# GOOD: Minimal output (~500 tokens)
serena.search_for_pattern(
    substring_pattern=r"@Transactional",
    restrict_search_to_code_files=True,
    context_lines_before=0,   # Default: 0
    context_lines_after=1,    # Just the class/method signature
    relative_path="module-core-domain/",  # ALWAYS scope!
    max_answer_chars=3000     # Limit output size
)

Pattern Search Rules:

ALWAYS set context_lines_before=0 and context_lines_after<=2
ALWAYS specify relative_path to scope the search
ALWAYS use max_answer_chars to limit output
PREFER find_symbol over search_for_pattern when looking for code structure

Step 5: Memory Management

# Read project-specific patterns (ALWAYS do this first!)
serena.read_memory(memory_file_name="cli_patterns")
serena.read_memory(memory_file_name="server_patterns")

# List all available memories
serena.list_memories()

# Write new patterns/decisions for future reference
serena.write_memory(
    memory_file_name="new_feature_patterns",
    content="# Feature Patterns\n..."
)

# Edit existing memory
serena.edit_memory(
    memory_file_name="cli_patterns",
    needle="old_pattern",
    repl="new_pattern",
    mode="literal"  # or "regex"
)

Step 6: Semantic Editing

# Replace entire symbol body (method, class, function)
serena.replace_symbol_body(
    name_path="UserService/createUser",
    relative_path="src/services/user.py",
    body="def createUser(self, data: dict) -> User:\n    ..."
)

# Insert code after a symbol
serena.insert_after_symbol(
    name_path="UserService",
    relative_path="src/services/user.py",
    body="\n\ndef new_helper_function():\n    pass"
)

# Insert code before a symbol
serena.insert_before_symbol(
    name_path="UserService",
    relative_path="src/services/user.py",
    body="# New import\nfrom typing import Optional\n"
)

# Rename symbol across codebase
serena.rename_symbol(
    name_path="createUser",
    relative_path="src/services/user.py",
    new_name="create_user"
)

Step 7: Think Tools (Self-Reflection)

# Use after gathering information
serena.think_about_collected_information()

# Use before making code changes
serena.think_about_task_adherence()

# Use when believing task is complete
serena.think_about_whether_you_are_done()

Context7 Workflow (Framework Docs)

Resolve Library First

# Step 1: Get library ID
context7.resolve-library-id(
    query="How to configure transactions in Spring Boot",
    libraryName="spring-boot"
)
# Returns: /spring/spring-boot

Query Documentation

# Step 2: Get specific docs
context7.query-docs(
    libraryId="/spring/spring-boot",
    query="transaction propagation and isolation levels"
)

Common Library IDs

| Library | ID | |---------|-----| | Spring Boot | /spring/spring-boot | | React | /facebook/react | | TanStack Query | /tanstack/query | | Typer | /tiangolo/typer | | pytest | /pytest-dev/pytest |

JetBrains Integration

Text & Regex Search

# Text search (fast, index-based)
jetbrains.search_in_files_by_text(
    searchText="@Repository",
    fileMask="*.kt",
    directoryToSearch="src/"
)

# Regex search (pattern matching)
jetbrains.search_in_files_by_regex(
    regexPattern=r"class\s+\w+Service",
    fileMask="*.kt",
    directoryToSearch="src/",
    caseSensitive=True
)

Code Inspection & Problems

# Get errors/warnings using IntelliJ inspections
jetbrains.get_file_problems(
    filePath="src/services/UserService.kt",
    errorsOnly=False,  # Include warnings
    timeout=5000       # ms
)
# Returns: severity, description, line/column for each issue

Symbol Info & Quick Docs

# Get symbol documentation at position
jetbrains.get_symbol_info(
    filePath="src/services/UserService.kt",
    line=42,
    column=15
)
# Returns: name, signature, type, documentation

Refactoring

# Context-aware rename (updates ALL references)
jetbrains.rename_refactoring(
    pathInProject="src/services/UserService.kt",
    symbolName="createUser",
    newName="createNewUser"
)
# Much smarter than search-replace - understands code structure!

# Reformat file with IDE rules
jetbrains.reformat_file(path="src/services/UserService.kt")

Run Configurations

# List available run configs
jetbrains.get_run_configurations()
# Returns: config names, command lines, env vars

# Execute a run configuration
jetbrains.execute_run_configuration(
    configurationName="Run Tests",
    timeout=60000,  # ms
    maxLinesCount=500
)

Terminal Integration

# Execute shell command in IDE terminal
jetbrains.execute_terminal_command(
    command="./gradlew test",
    timeout=120000,
    maxLinesCount=1000,
    executeInShell=True  # Use user's shell env
)

File Operations

# Find files by glob pattern
jetbrains.find_files_by_glob(
    globPattern="**/test_*.py",
    subDirectoryRelativePath="tests/"
)

# Fast file name search (index-based)
jetbrains.find_files_by_name_keyword(
    nameKeyword="Service",
    fileCountLimit=50
)

# Create file with content
jetbrains.create_new_file(
    pathInProject="src/new_feature/service.py",
    text="# New service\n...",
    overwrite=False
)

# Get directory tree
jetbrains.list_directory_tree(
    directoryPath="src/",
    maxDepth=3
)

Project Info

# Get project dependencies
jetbrains.get_project_dependencies()

# Get project modules
jetbrains.get_project_modules()

# Get VCS roots (multi-repo support)
jetbrains.get_repositories()

# Get open files in editor
jetbrains.get_all_open_file_paths()

Claude-mem (Cross-Session Memory)

Search Past Work

# Search all past sessions
claude-mem.search(
    query="authentication decision",
    project="dataops-platform",  # Required
    limit=20,
    type="observations"  # observations, sessions, prompts
)

# Filter by observation type
claude-mem.search(
    query="bug",
    obs_type="bugfix",  # bugfix, feature, decision, discovery, change
    project="dataops-platform",
    limit=20
)

# Date-filtered search
claude-mem.search(
    type="observations",
    dateStart="2025-12-01",
    dateEnd="2025-12-31",
    project="dataops-platform"
)

Timeline Context

# Get context around a specific observation
claude-mem.timeline(
    anchor=11131,        # Observation ID
    depth_before=3,      # Items before
    depth_after=3,       # Items after
    project="dataops-platform"
)

# Auto-find anchor from query
claude-mem.timeline(
    query="authentication",
    depth_before=5,
    depth_after=5,
    project="dataops-platform"
)

# Get context around observation ID
claude-mem.get_context_timeline(
    anchor=11131,
    depth_before=3,
    depth_after=3
)

Batch Fetching (10-100x Faster!)

# ALWAYS use for 2+ observations (single HTTP request)
claude-mem.get_observations(
    ids=[11131, 10942, 10855],
    orderBy="date_desc",
    project="dataops-platform"
)

# Single observation (only when exactly 1 needed)
claude-mem.get_observation(id=11131)

# Fetch session details
claude-mem.get_session(id=2005)

# Fetch prompt details
claude-mem.get_prompt(id=5421)

Recent Context

# Get most recent observations
claude-mem.get_recent_context(
    project="dataops-platform",
    limit=10
)

Workflow Pattern

1. Search → Get index of results with IDs
2. Timeline → Get context around top results
3. Review → Pick relevant IDs from titles/dates
4. Batch Fetch → Get full details only for needed IDs

Decision Tree

Need documentation/patterns? (FIRST!)
├── What's the project architecture?
│   └── doc-search "architecture" → read section
├── What implementation patterns exist?
│   └── doc-search "pattern" + project name → read section
├── How should I implement feature X?
│   └── doc-search "implementation guide" → read section
└── What are the testing conventions?
    └── doc-search "testing" → read section

Need to understand code?
├── What's in this file/directory?
│   └── serena.get_symbols_overview
├── How is X implemented?
│   └── serena.find_symbol(include_body=True)
├── Who uses X?
│   └── serena.find_referencing_symbols
├── Where is pattern X used?
│   └── serena.search_for_pattern OR jetbrains.search_in_files_by_regex
├── What's the best practice for X?
│   └── context7.query-docs
├── What did we decide before?
│   └── claude-mem.search → timeline → get_observations
└── Is there a problem in this file?
    └── jetbrains.get_file_problems

Need to edit code?
├── Rename a symbol everywhere?
│   ├── serena.rename_symbol (LSP-based)
│   └── jetbrains.rename_refactoring (IDE-based)
├── Replace entire method/class?
│   └── serena.replace_symbol_body
├── Add new code after existing symbol?
│   └── serena.insert_after_symbol
└── Reformat file?
    └── jetbrains.reformat_file

Need project info?
├── What memories exist for this project?
│   └── serena.list_memories → read_memory
├── What run configurations are available?
│   └── jetbrains.get_run_configurations
├── What are the project dependencies?
│   └── jetbrains.get_project_dependencies
└── What happened in past sessions?
    └── claude-mem.get_recent_context

Progressive Disclosure Pattern

Always start narrow, expand only if needed:

# Level 1: Structure only (cheapest)
serena.get_symbols_overview(relative_path="src/services/")

# Level 2: Signatures (if class identified)
serena.find_symbol("UserService", depth=1, include_body=False)

# Level 3: Specific method body (if needed)
serena.find_symbol("UserService/createUser", include_body=True)

# Level 4: Full file read (last resort)
Read(file_path="src/services/UserService.kt")

Common Mistakes

| Mistake | Token Cost | Better Approach | |---------|------------|-----------------| | Read file first | High | Use serena.get_symbols_overview | | Read all files in directory | Very High | Use serena.find_symbol with pattern | | Multiple full file reads | Extreme | Use serena.find_referencing_symbols | | Google for framework docs | Time waste | Use context7.query-docs | | Ask user about past decision | Slow | Use claude-mem.search |

search_for_pattern Token Cost Examples

| Query | Context | Scope | Est. Tokens | |-------|---------|-------|-------------| | @RequestMapping | 0/0 | controller/ | ~800 | | @RequestMapping | 0/1 | controller/ | ~1,500 | | @RequestMapping | 2/10 | controller/ | ~21,000 | | @RequestMapping | 2/10 | (none) | ~50,000+ | | @Service | 0/0 | service/ | ~400 | | @Service | 0/0 | (none) | ~2,000 |

Rule of Thumb: Every +1 to context_lines_after = ~2x token cost

MCP-First Checklist

Before reading ANY file, ask:

[ ] Can get_symbols_overview answer this?
[ ] Can find_symbol with signatures answer this?
[ ] Do I need the full body, or just the signature?
[ ] Is this a framework question? (use context7)
[ ] Did we discuss this before? (use claude-mem)

Token Savings Examples

| Task | Without MCP | With MCP | Savings | |------|-------------|----------|---------| | Find class structure | 5000 tokens | 300 tokens | 94% | | Find all usages | 15000 tokens | 800 tokens | 95% | | Understand API pattern | 3000 tokens | 500 tokens | 83% | | Check framework docs | N/A | 600 tokens | Faster | | Search past decisions | N/A | 200 tokens | Instant | | Run IDE inspections | Manual | 100 tokens | Automatic |

Quick Reference: All MCP Tools

Serena (Semantic Code Analysis)

| Tool | Purpose | |------|---------| | get_symbols_overview | File/directory structure overview | | find_symbol | Search symbols by name/pattern | | find_referencing_symbols | Find all references to a symbol | | search_for_pattern | Regex search across codebase | | replace_symbol_body | Replace entire symbol definition | | insert_before_symbol | Insert code before a symbol | | insert_after_symbol | Insert code after a symbol | | rename_symbol | Refactor symbol name globally | | read_memory | Load project-specific patterns | | write_memory | Save patterns for future | | edit_memory | Update existing memory | | list_memories | List available memories | | list_dir | Directory listing | | find_file | Find files by mask | | think_about_* | Self-reflection tools |

JetBrains (IDE Integration)

| Tool | Purpose | |------|---------| | search_in_files_by_text | Fast text search (indexed) | | search_in_files_by_regex | Pattern-based search | | get_file_problems | IntelliJ inspections (errors/warnings) | | get_symbol_info | Quick docs at position | | rename_refactoring | Context-aware rename | | reformat_file | Apply IDE formatting | | get_run_configurations | List run configs | | execute_run_configuration | Run a configuration | | execute_terminal_command | Run shell command | | find_files_by_glob | Glob pattern file search | | find_files_by_name_keyword | Keyword file search | | list_directory_tree | Directory tree view | | create_new_file | Create file with content | | get_project_dependencies | List dependencies | | get_project_modules | List modules | | get_repositories | List VCS roots |

Claude-mem (Cross-Session Memory)

| Tool | Purpose | |------|---------| | search | Search past work (required: project) | | timeline | Context around observation | | get_observations | Batch fetch (10-100x faster) | | get_observation | Single observation | | get_session | Session details | | get_prompt | Prompt details | | get_recent_context | Recent observations | | get_context_timeline | Timeline around ID |

Context7 (Framework Docs)

| Tool | Purpose | |------|---------| | resolve-library-id | Get library ID for docs | | query-docs | Query framework documentation |

mcp-efficiency

MCP Efficiency

CRITICAL: search_for_pattern Token Limits

MANDATORY Parameters for search_for_pattern

Quick Examples

Use Correct Tool

Serena Infrastructure (Project-Specific)

Cache Structure

Make Commands (Cache Sync)

Post-Implementation Cache Sync

Why This Matters

Document Search (NEW - Priority 0)

Quick Search (CLI)

Token Comparison

Document Search Workflow

When to Use Document Search

MCP Server Reference

Server Strengths

Serena Workflow (Primary)

Step 1: Understand Structure

Step 2: Find Specific Symbols

Step 3: Trace Dependencies

Step 4: Pattern Search (TOKEN CRITICAL)

Step 5: Memory Management

Step 6: Semantic Editing

Step 7: Think Tools (Self-Reflection)

Context7 Workflow (Framework Docs)

Resolve Library First

Query Documentation

Common Library IDs

JetBrains Integration

Text & Regex Search

Code Inspection & Problems

Symbol Info & Quick Docs

Refactoring

Run Configurations

Terminal Integration

File Operations

Project Info

Claude-mem (Cross-Session Memory)

Search Past Work

Timeline Context

Batch Fetching (10-100x Faster!)

Recent Context

Workflow Pattern

Decision Tree

Progressive Disclosure Pattern

Common Mistakes

search_for_pattern Token Cost Examples

MCP-First Checklist

Token Savings Examples

Quick Reference: All MCP Tools

Serena (Semantic Code Analysis)

JetBrains (IDE Integration)

Claude-mem (Cross-Session Memory)

Context7 (Framework Docs)

Sources