Agent skill

mcp-daemon-isolation

Context isolation for query-type MCP tools (LSP, search, database) via external CLI. Use when MCP query results consume too many context tokens.

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/chkim-su/forge-editor/tree/main/skills/mcp-daemon-isolation

SKILL.md

MCP Daemon Isolation for Query-Type MCPs

External CLI pattern for isolating query-type MCP tool results from main context.

Query-Type MCP Definition

Type Examples Characteristics
Query-type Serena (LSP), Database, Search Unpredictable result size, potentially thousands of tokens
Action-type File write, Git, Deploy Small results, success/failure focused

Identification criteria: Tools with find_*, search_*, get_*, list_* patterns

Problem

Claude Session
├── mcp__serena__find_symbol("UserService")
│   └── Result: 2,500 tokens (full JSON)    ← CONSUMED
└── Context budget: rapidly depleting

Daemon isolates tool definitions (~350 tokens × tools), but results still consume context.

Solution: External CLI + Structured Extraction

Claude Session
├── Bash: serena-query find_symbol UserService
│   └── stdout: "• UserService [Class] @ src/user.py:42"
│       (~50 tokens)                      ← MINIMAL
└── Full result stored: /tmp/serena-result.json

Key insight: Claude IS the LLM. Structured extraction provides 95%+ token savings.

Architecture

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│ Claude       │────▶│ serena-query     │────▶│ Serena       │
│ Session      │     │ (external CLI)   │     │ Daemon :8765 │
└──────────────┘     └──────────────────┘     └──────────────┘
     Bash (~50 tok)     SSE + MCP Protocol       29 tools

For protocol details: Read("references/mcp-sse-protocol.md")

Structured Extractors

Tool Full JSON Extracted Output Savings
list_dir ~800 📁 Dirs(12): hooks... 📄 Files(11) 95%
get_symbols_overview ~1,200 Class(2): Config... Function(5) 96%
find_symbol ~2,000 • UserService [Class] @ src/user.py:42-98 97%
search_for_pattern ~1,500 Matches(15) in 8 files 95%

For formatter code: Read("references/extractors-and-examples.md")

Usage

Output Modes

bash
serena-query find_symbol UserService                    # summary (default)
serena-query find_symbol UserService --mode location    # location only (for Read)
serena-query find_symbol UserService --mode full        # full JSON

Basic Commands

bash
serena-query list_dir .
serena-query get_symbols_overview src/main.py --depth 1
serena-query find_symbol UserService --path src/
serena-query search_for_pattern "class.*Service" --path src/
serena-query find_symbol UserService --output /tmp/result.json

Optimal Workflow: Explore-Locate-Read

1. Explore (--mode summary)   ~25 tokens  "What symbols exist?"
2. Locate (--mode location)   ~15 tokens  "Where exactly is it?"
3. Read (Read tool)           actual size  Only needed code
Scenario stdio approach daemon+Read Savings
Class analysis ~525 ~240 54%
11 function analysis ~4,300 ~665 85%
Large-scale search ~10,000+ ~500 95%

For detailed examples: Read("references/extractors-and-examples.md")

Installation

bash
pip install httpx
cp scripts/serena-query ~/.local/bin/
chmod +x ~/.local/bin/serena-query

Daemon Setup

bash
uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --transport sse --port 8765 --project-from-cwd

Decision: Structured vs LLM Summarization

Aspect LLM Summarization Structured Extraction
Latency +2-5 seconds ~0ms
Cost API call per query Zero
Consistency Variable Deterministic

Claude IS the LLM consuming the output - no need for additional summarization.

Isolation Strategy Guide

Scenario Recommended Reason
Single symbol edit stdio Immediate modification
Codebase exploration daemon Expect large results
Reference tracking daemon + location Only need locations
Refactoring planning daemon + full Full structure analysis

Common Issues

Symptom Cause Solution
"Received request before initialization" Missing handshake initialize → notifications/initialized → tools/call sequence
"Connection refused on 8765" Daemon not running systemctl --user start serena-daemon
"Empty result" Structure mismatch Save raw JSON with --output and verify

References

Implementation

  • serena-query CLI
  • Implementation Details
  • v2 Design

Protocol & Examples

  • MCP-SSE Protocol
  • Extractors & Examples
  • Integration Guide

Related

  • MCP Gateway Patterns

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

chkim-su/forge-editor

forge-analyzer

Analyze vague user ideas and recommend architecture based on actual needs, not predefined categories. Front-end for clarifying ambiguous requests before routing to appropriate skillmaker tools.

1 0
Explore
chkim-su/forge-editor

hook-system

Claude Code Hook system entry point. Guides you to the right skill based on your needs.

1 0
Explore
chkim-su/forge-editor

mcp-gateway-patterns

MCP Gateway design patterns for Agent Gateway, Subprocess, and Daemon isolation. Use when designing MCP integrations.

1 0
Explore
chkim-su/forge-editor

workflow-state-patterns

Hook-based state machine patterns for multi-phase workflows. Use when designing sequential workflows with quality gates.

1 0
Explore
chkim-su/forge-editor

critical-analysis-patterns

Philosophical/meta project analysis - critical analysis framework that asks "why?"

1 0
Explore
chkim-su/forge-editor

agent-tools-patterns

Patterns for configuring agent tools correctly

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results