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:

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

Install Skill

SKILL.md

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