Syncause Debug Daemon

The Syncause Project Debug Daemon (MCP Daemon) provides high-performance RPC services for runtime data collection, analysis, and debugging.

🚀 Core Features

$3

- Local Mode: Supports Windows named pipes and Unix domain sockets, providing ultra-low latency local communication.
- REMOTE Mode: Supports standard HTTP protocol, facilitating cross-network or inter-container communication.

$3

- Lightweight RPC Framework: Based on JSON-RPC 2.0 protocol, supports request/response mode with built-in message framing.
- Multi-user Isolation: Achieves multi-client isolation through apiKey, independently maintaining collection status and data storage.
- Smart Caching: In-memory caching mechanism reduces disk I/O by 90%+, with batch writing optimization.
- Concurrency Safety: Operation lock mechanism ensures safe concurrent writing, preventing data races.

$3

- LLM Integration: Intelligent analysis and summary generation for runtime data.
- Dual-mode Search: Supports Vector Embedding and Fuzzy Match.
- Automatic Polling: Global polling mechanism synchronizes application runtime data in real-time.

$3

- Graceful Shutdown: Comprehensive signal handling automatically cleans up resources and persists data.
- Auto Shutdown: Intelligently monitors activity status, automatically shutting down after idle time to save resources.
- Structured Logging: Tiered logging support with file rotation.
- Configuration Management: Unified environment variable configuration, supporting runtime tuning.

📦 Quick Start

$3

- Node.js 20.x or higher
- npm or yarn

$3

``bash
npm install
`

$3

`bash

TypeScript compilation

npm run build

Or use esbuild for high-speed bundling

npm run bundle
`

$3

`bash
npm install -g .
`

$3

Development Mode (PowerShell):
`powershell
$env:MODE = "local"
$env:LOG_TO_CONSOLE = "true"
$env:LOG_LEVEL = "debug"
npx tsx src/index.ts
`

Development Mode (Bash):
`bash
MODE=local LOG_TO_CONSOLE=true LOG_LEVEL=debug npx tsx src/index.ts
`

Production Mode:
`bash
node dist/index.js
`

Run after Global Installation:
`bash
syncause-debug-daemon
`

⚙️ Configuration Guide

All configuration items can be customized via environment variables or command-line arguments.
Priority: Command Line Arguments > Environment Variables > Defaults.

Command-line arguments support --KEY=VALUE or --key value formats (case-insensitive).
For example, HTTP_PORT can be specified via --HTTP_PORT=9090 or --http_port 9090.

$3

| Variable Name | Description | Default | Note |
| :--- | :--- | :--- | :--- |
| MODE | Server running mode | local | local or remote |
| AUTO_SHUTDOWN_MINUTES | Idle auto-shutdown time | 5 | Unit: minutes. Automatically shuts down if no request (including ping) is received within this time. Set to 0 to disable. |
| HTTP_PORT | HTTP mode listening port | 8080 | Valid only in HTTP mode |

$3

| Variable Name | Description | Default | Options |
| :--- | :--- | :--- | :--- |
| LOG_LEVEL | Log level | info | debug, info, warn, error |
| LOG_TO_CONSOLE | Console output | false | true, false |

$3

| Variable Name | Description | Default | Note |
| :--- | :--- | :--- | :--- |
| STORAGE_PERSIST_INTERVAL | Persistence check interval | 5000 | Unit: milliseconds |
| STORAGE_MAX_TRACES_PER_APP | Max traces per app | 250 | Retains latest records if exceeded |

$3

| Variable Name | Description | Default | Note |
| :--- | :--- | :--- | :--- |
| SERVICE_PROXY_URL | API proxy URL | https://api.syn-cause.com/codeproxy | Used to retrieve app and trace data |
| SERVICE_POLLING_INTERVAL | Polling interval | 10000 | Unit: milliseconds |

$3

#### Via Environment Variables

`powershell


Windows PowerShell


$env:MODE = "local"
$env:LOG_TO_CONSOLE = "true"
$env:LOG_LEVEL = "debug"
$env:SERVICE_PROXY_URL = "http://192.168.1.6:32220"
npx tsx src/index.ts
`

`bash


Linux/macOS Bash


MODE=local LOG_TO_CONSOLE=true LOG_LEVEL=debug \
SERVICE_PROXY_URL=http://192.168.1.6:32220 \
npx tsx src/index.ts
`

#### Via Command Line Arguments

`bash


Cross-platform


npx tsx src/index.ts \
--mode local \
--log_to_console true \
--log_level debug \
--service_proxy_url http://192.168.1.6:32220
`

📂 Project Structure

`text
src/
├── common/ # Common protocols and utilities
│ ├── common.ts # Common constants and utility functions
│ ├── framing.ts # Message framing processing
│ ├── protocol.ts # RPC protocol definitions
│ └── version.ts # Version information
├── config/ # Unified configuration management
│ └── index.ts # Configuration loading and management
├── core/ # Core business logic layer
│ ├── api/ # External service integration (LLM, Embedding)
│ ├── logger/ # Structured logging system
│ ├── services/ # Business services (Multi-user management, data collection)
│ ├── storage/ # Storage persistence (Disk I/O, cache management)
│ └── utils/ # Utility classes (Tree building, similarity calculation, search strategies)
├── rpc/ # RPC protocol implementation
│ ├── handler/ # RPC method handlers
│ ├── server.ts # RPC core server
│ └── utils/ # RPC utility functions
└── transport/ # Transport layer implementation
└── server/ # Local and HTTP server implementations
├── baseServer.ts # Base server abstract class
├── http.ts # HTTP server implementation
└── local.ts # Local server implementation (Named pipes/Domain sockets)
`

📡 RPC Interfaces

$3

#### ping
Client heartbeat detection and registration.
- Parameters:
- meta.apiKey - User identifier

#### get_runtime_facts
Query application runtime data.
- Parameters:
- meta.apiKey - User identifier
- projectId - Project ID
- searchText - Search keywords (optional)
- matchMode - Match mode: embedding or fuzzy

#### search_debug_traces
AI intelligent troubleshooting.
- Parameters:
- meta.apiKey - User identifier
- projectId - Project ID
- query - Problem description
- limit - Number of results to return

$3

#### get_trace_insight
Get complete request lifecycle report.
- Parameters:
- meta.apiKey - User identifier
- projectId - Project ID
- traceId - Trace ID

#### inspect_method_snapshot
Method-level deep analysis.
- Parameters:
- meta.apiKey - User identifier
- projectId - Project ID
- traceId - Trace ID
- className - Class name
- methodName - Method name
- includeSubCalls - Whether to include sub-calls

#### diff_trace_execution
Comparative analysis of two request executions.
- Parameters:
- meta.apiKey - User identifier
- projectId - Project ID
- baseTraceId - Trace ID for the failure case
- compareTraceId - Trace ID for the reference case (optional)

🛡️ Operations Guide

$3

When receiving Ctrl+C (SIGINT) or SIGTERM signals, the daemon will:

1. Stop global polling timers.
2. Persist all cached data to disk.
3. Close all active connections.
4. Flush log buffers.
5. Initiate a 10-second timeout protection to ensure process termination.

$3

Log files are named by PID and stored in:

- Windows: %APPDATA%\syncause-debug\logs\
- Linux: ~/.local/share/syncause-debug/logs/
- macOS: ~/Library/Application Support/syncause-debug/logs/

$3

Main dependencies:
- openai: OpenAI API client for LLM integration.
- winston: Structured logging system.
- uuid: Unique identifier generation.
- p-limit: Concurrency control.

Development dependencies:
- typescript: TypeScript compiler.
- esbuild: High-speed bundling tool.
- tsx: TypeScript execution tool.
- @types/*`: TypeScript type definitions.