---
name: mcpd
description: Manage MCP server lifecycle with mcpd daemon. Start, stop, monitor MCP servers, search and recommend tools using LLM-powered assistant.
triggers:
  - mcp server
  - mcpd
  - start mcp
  - mcp tools
  - mcp servers
  - find tool
  - tool assistant
  - mcp config
---

# mcpd - MCP Server Lifecycle Manager

## Overview

mcpd is a daemon that manages MCP (Model Context Protocol) server processes with:
- **Intelligent idle detection** - Auto-stop servers after inactivity
- **Auto-start on demand** - Servers restart when tools are invoked
- **Tool namespacing** - Use tools from multiple servers without conflicts
- **LLM-powered tool assistant** - Natural language tool recommendations
- **Web Management UI** - Browser-based CRUD for everything

## Daemon Management

The daemon is a background process that hosts the Web UI and IPC server.

```bash
mcpd daemon start         # Start daemon in background (recommended)
mcpd daemon start --open  # Start and open browser automatically
mcpd daemon stop          # Stop daemon
mcpd daemon status        # Show daemon status
mcpd daemon               # Run in foreground (for debugging)
```

## Server Management

```bash
mcpd up [servers...]      # Start servers (auto-starts daemon if needed)
mcpd up filesystem        # Start specific server
mcpd down                 # Stop all servers
mcpd ps [-v] [server]    # Show server status
mcpd load                 # Preload server metadata into cache
mcpd refresh              # Refresh cached metadata
mcpd logs [server] [-f]   # View logs
mcpd reload               # Reload configuration
mcpd validate             # Validate mcpserver.json
```

## Tool Operations

```bash
mcpd tools                # List all servers with tool counts
mcpd tools <server>       # List tools for a server
mcpd tools <server> -v    # List with parameter details
mcpd exec <tool> [args]   # Execute a tool
```

## 🤖 Tool Assistant (LLM-powered)

Ask in natural language and get intelligent tool recommendations:

```bash
mcpd ask "I need to read local files"
mcpd ask "search for code on github"
mcpd ask "创建一个项目任务" --top-k 3
mcpd ask "read file" --skip-llm   # Skip LLM, use raw keyword search
```

The assistant performs:
1. **Query expansion** - LLM splits and expands your query (keywords + synonyms)
2. **Multi-channel recall** - 4 channels: inverted index, domain match, tag match, graph neighbors
3. **Reranking** - LLM reranks candidates with natural language reasons

## Search (Keyword)

Traditional keyword-based tool search:

```bash
mcpd search "read file"                # Search via CLI
curl -X POST localhost:18423/api/v1/search -d '{"query":"read"}'   # Via HTTP
```

## Tool Graph

Build an LLM-analyzed tool knowledge graph:

```bash
mcpd graph build          # Analyze all tools with LLM (tags, domain, scenarios)
mcpd graph show           # Show graph statistics
mcpd graph neighbors read_file  # Show related tools
```

## Configuration

```bash
mcpd config show
mcpd config set llm.enabled=true
mcpd config set llm.api_key=sk-xxx
mcpd config set llm.base_url=https://api.deepseek.com
mcpd config set llm.model=deepseek-v4-flash
mcpd config set gateway.bind=:18423
```

Config files are at `~/.mcpd/`:
- `mcpd.yml` - Daemon settings (idle timeout, gateway, LLM, etc.)
- `mcpserver.json` - MCP server definitions
- `graph.json` - Tool knowledge graph (auto-managed)
- `cache/` - Cached tool metadata

## Web Management

Access the Web UI at `http://localhost:18423/` when the daemon is running.

Tabs available:
- **Servers** - CRUD for MCP servers
- **🤖 Assistant** - Natural language tool recommendations
- **Tool Graph** - Browse tool tags, domains, relationships
- **Search** - Keyword-based tool search
- **Config** - View and edit configuration

## Tool Namespacing

Tools are namespaced as `<server>.<tool>`, e.g. `filesystem.read_file`.

If a tool name is unique across servers, the bare name also works: `read_file`.

## Integration with Claude Code

- The daemon auto-starts when you run `mcpd up` or other commands
- Servers auto-stop after 5 minutes of inactivity (configurable)
- Servers auto-start when their tools are invoked
- Use `mcpd exec <server>.<tool> --args '{"key":"value"}'` to invoke tools
- Use `mcpd ask "<natural language>"` for AI-assisted tool discovery
