MCP Efficiency

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

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

---

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)

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

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

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

See doc-search skill for comprehensive guide.

MCP Server Reference

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:

1. ALWAYS set context_lines_before=0 and context_lines_after<=2
2. ALWAYS specify relative_path to scope the search
3. ALWAYS use max_answer_chars to limit output
4. 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

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

search_for_pattern Token Cost Examples

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

---

Quick Reference: All MCP Tools

Serena (Semantic Code Analysis)

JetBrains (IDE Integration)

Claude-mem (Cross-Session Memory)

Context7 (Framework Docs)

---

Sources

• JetBrains MCP Server Documentation
• Serena GitHub Repository
• Serena Tools Documentation
• IntelliJ IDEA 2025.1 MCP Blog