mcp-efficiency

name	mcp-efficiency
description	Token-efficient codebase exploration using MCP servers (Serena, Context7, JetBrains, Claude-mem). Reduces token usage by 80-90% through structured queries. Use ALWAYS before reading files to minimize context window usage.

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:

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

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

---

Sources

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