mcp-efficiency
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.
When & Why to Use This Skill
This Claude skill optimizes codebase exploration and interaction by leveraging MCP (Model Context Protocol) servers like Serena, Context7, and JetBrains. It is specifically designed to reduce token consumption by 80-90% through structured, semantic queries instead of full-file reading. By prioritizing symbol overviews, documentation indexing, and cross-session memory, it allows for high-precision navigation of large-scale repositories while strictly minimizing context window usage.
Use Cases
- Case 1: Large-scale codebase exploration where reading full files would exceed token limits or degrade model performance.
- Case 2: Semantic symbol tracking and dependency analysis to understand how specific functions or classes are referenced across a project.
- Case 3: Efficient framework-specific documentation retrieval using Context7 to apply best practices without manual searching.
- Case 4: Cross-session knowledge management using Claude-mem to recall past architectural decisions and implementation patterns.
- Case 5: High-fidelity code refactoring and IDE-integrated inspections via JetBrains MCP to ensure code quality and structural integrity.
| 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.
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-searchskill 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=0andcontext_lines_after<=2 - ALWAYS specify
relative_pathto scope the search - ALWAYS use
max_answer_charsto limit output - PREFER
find_symboloversearch_for_patternwhen 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_overviewanswer this? - Can
find_symbolwith 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 |