MCP, Router & Hooks

MCP (Model Context Protocol)#

MCP enables integration with external AI tools via a standardized JSON-RPC 2.0 protocol.

Transports#

Type	Description
stdio	Process: launched via command/args, communicates via stdin/stdout
http	Network: HTTP connection to a remote server

Configuration#

mcp:
  servers:
    - name: "my-server"
      transport: stdio
      command: "/path/to/mcp-server"
      args: ["--mode", "production"]
      env:
        CUSTOM_VAR: "${HOME}/config"
      auto_connect: true
      timeout: 15s

Auto-Healing#

Background check every 30 seconds
Tracks consecutive errors (threshold: 3)
Up to 10 reconnection attempts with exponential backoff (100ms → 30s)
Automatic reset on successful connection

Security#

StdioTransport sanitizes the environment: only whitelisted variables (PATH, HOME, PYTHONPATH, etc.) are passed to child processes.

Integration#

MCP tools are automatically wrapped in MCPTool and added to the tool registry with an optional prefix.

Semantic Search#

Similarity search using embeddings.

Architecture#

Component	Purpose
Indexer	File chunking, embedding generation, caching
Embedder	Gemini embedding API (batch up to 20)
Code Graph	Dependency graphs, circular dependency detection
Pattern Matcher	Regex detection of patterns and anti-patterns
Chunker	Splitting by functions/classes with overlap

Features#

Dual caching: in-memory + disk, hash-based keys
Cosine similarity on embedding vectors
Respects .gitignore
Skips: node_modules, vendor, .git, __pycache__, target
Supports 40+ file extensions
Max file size: 10MB (default 100KB)

Code Graph#

GetDependencies(nodeID) — transitive dependencies
GetDependents(nodeID) — reverse dependencies
FindCircularDeps() — DFS cycle detection

semantic:
  enabled: true
  model: text-embedding-004
  top_k: 10
  cache_ttl: 24h

Smart Router#

Routes tasks to the optimal handler based on complexity analysis.

Routing Strategies#

Strategy	Score	Description
Direct	≤ 2	Simple questions, direct answer
SingleTool	—	Expects a single tool call
Executor	3–6	Standard multi-turn cycle
SubAgent	7+	Complex tasks, launch typed agents

Complexity Analysis#

TaskComplexity {
    Score     int      // 1-10
    Type      TaskType // question, exploration, refactoring...
    Strategy  ExecutionStrategy
    Reasoning string
}

Cost-Aware Routing#

For simple tasks (Direct) suggests a fast model (e.g., gemini-2.0-flash)
Dynamic thinking budget assignment: 0 for Direct, 1024–4096 for complex

Routing Learning#

Stores the last 100 routing decisions
Records success/failure per strategy
Automatically upgrades strategy at <30% success rate

Sub-Agent Selection#

Task Type	Agent
Exploration	explore (read-only)
Background	bash (execution)
Refactoring	general (write access)
Complex	general (full access)

Hooks#

Execute shell commands at lifecycle stages.

Hook Types#

Type	Trigger	Example
pre_tool	Before tool execution	Argument validation
post_tool	After successful execution	Logging
on_error	On tool error	Cleanup
on_start	Application start	Initialization
on_exit	Application exit	Save state

Configuration#

hooks:
  - name: "lint_before_commit"
    type: pre_tool
    tool_name: git_commit
    command: "golint ./..."
    enabled: true
    condition: always       # always, if_previous_success, if_previous_failure
    fail_on_error: true
    depends_on: ""          # Hook chaining

Capabilities#

Variable substitution: ${TOOL_NAME}, ${RESULT}, ${ERROR}, ${WORK_DIR}
Chaining: depends_on for sequential execution
Output capture: CapturedOutput from previous hook
Timeout: default 30s, SIGTERM → SIGKILL

File Watcher#

File system monitoring with debouncing.

Events#

Event	Description
OpCreate	New file/directory
OpModify	Content change
OpDelete	File deletion

Implementation#

Debouncing: groups changes, emits after stable period (500ms)
.gitignore integration
Auto-adds new directories
Skips temporary files (. prefix, ~ suffix)
Max watches: 1000

watcher:
  enabled: true
  debounce_ms: 500
  max_watches: 1000

Rate Limiting#

Dual-bucket API request limiting system.

Buckets#

Bucket	Default	Description
Request	60/min	Request count limit
Token	1M/min	Token count limit

Wait Modes#

Method	Behavior
`Acquire()`	Blocking, infinite wait
`TryAcquire()`	Non-blocking, false if limited
`AcquireWithTimeout()`	Blocking with deadline
`AcquireWithContext()`	With context cancellation

Token Bucket#

Exponential refill (per-second from per-minute limits)
Burst capacity = 10% of per-minute limit

rate_limit:
  enabled: true
  requests_per_minute: 60
  tokens_per_minute: 1000000
  burst_size: 10

Caching#

Multi-layer LRU cache with TTL.

Implementation#

Generic LRU: LRUCache[K, V] with generics
TTL: checked on read + background cleanup every 5 min
LRU eviction: removes oldest entry on overflow
Thread-safe: RWMutex on all operations
Bulk removal: Remove(predicate) for filtered deletion

Usage#

Tool results — search result cache by hash
File metadata — Stat() with TTL 5min
Semantic embeddings — by key "filepath:linestart"

cache:
  enabled: true
  capacity: 100
  ttl: 5m

Circuit Breaker#

Fast failure when downstream services are unavailable.

States#

Closed (normal) → Open (error threshold) → HalfOpen (probe) → Closed (success)
                                           ↖ HalfOpen (fail) ↙

State	Transition Condition
Closed → Open	5 consecutive errors
Open → HalfOpen	30s timeout expired
HalfOpen → Closed	Probe succeeded
HalfOpen → Open	Probe failed

Used for MCP clients and API calls.

Reliability Manager#

Manages degraded mode after multiple failures.

Tracks error patterns
Transitions to degraded mode after 3 consecutive errors
Automatic recovery on stabilization
Circuit breaker integration

Provider Failover#

On primary provider error:

Try primary provider
On error — next in fallback_providers
Reset on success
Providers sorted by health score

model:
  fallback_providers:
    - deepseek
    - gemini
    - ollama

Health Score: from -20 to +8, stored in ~/.config/gokin/provider_health.json.

Self-Update#

Update system with atomic replacement and rollback.

Process#

CheckForUpdate → Download → VerifyChecksum → CreateBackup → Atomic Replace

Features#

ETag caching: skips redundant downloads
SHA256 verification: before installation
Atomic replacement: temp file → rename (no partial updates)
3 backups (by default)
Rollback: gokin update rollback [backup-id]

update:
  enabled: true
  check_interval: 24h
  auto_update: false
  max_backups: 3