# mcpd - MCP Server Lifecycle Manager

> Intelligent daemon for managing MCP (Model Context Protocol) server processes

[![npm version](https://img.shields.io/npm/v/@juncai/mcpd.svg)](https://www.npmjs.com/package/@juncai/mcpd)
[![License](https://img.shields.io/npm/l/mcpd.svg)](https://github.com/yourusername/mcpd/blob/master/LICENSE)

**Think of it as "systemd for MCP servers, but smarter"**

## What is mcpd?

mcpd is a daemon and CLI tool that manages MCP server processes with:

- ✅ **Intelligent idle detection** - Auto-stop servers after inactivity
- ✅ **Auto-start on demand** - Servers restart when you need them
- ✅ **Tool namespacing** - Use tools from multiple servers without conflicts
- ✅ **Hot reload** - Update config without restarting
- ✅ **Crash recovery** - Automatic restart with exponential backoff
- ✅ **Cross-platform** - Works on Windows, Linux, and macOS

## Installation

```bash
npm install -g @juncai/mcpd
```

### Requirements

- **Platform:** Windows x64 (Linux and macOS support coming soon)
- **Node.js:** Version 12.0.0 or higher

## Quick Start

### 1. Create Configuration

Create `mcpserver.json` in your project directory:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {
        "npm_config_registry": "https://registry.npmjs.org"
      }
    }
  }
}
```

### 2. Start a Server

```bash
mcpd up filesystem
```

### 3. Check Status

```bash
mcpd ps
```

Output:
```
NAME          STATE     TOOL_COUNT
filesystem    running   14
```

### 4. List Tools

```bash
mcpd tools
```

### 5. Execute a Tool

```bash
mcpd exec filesystem.read_file '{"path": "/tmp/test.txt"}'
```

### 6. Stop Server

```bash
mcpd down filesystem
```

## CLI Commands

```bash
# Server Management
mcpd up [servers...]           # Start servers (all if none specified)
mcpd down [--all]              # Stop servers
mcpd ps [-v] [server]          # Show status (verbose: -v or -vv)

# Tool Operations
mcpd tools [server]            # List available tools
mcpd tools [server] -v         # List tools with parameter details
mcpd tools [server] --json     # Output tools in JSON format
mcpd exec <tool> [args]        # Execute a tool

# Cache Management
mcpd load [servers...]         # Preload server metadata into cache
mcpd refresh [servers...]      # Refresh cached metadata

# Configuration
mcpd validate                  # Validate mcpserver.json
mcpd reload                    # Reload configuration
mcpd logs [server] [-f]        # View logs

# Daemon
mcpd daemon                    # Start daemon (internal)
```

## Example Configuration

Example configurations are included in the package:

```bash
# View example daemon configuration
cat $(npm root -g)/mcpd/examples/mcpd.yml

# View example MCP server configuration
cat $(npm root -g)/mcpd/examples/mcpserver.json
```

## Features

### Metadata Caching (v1.1+)

mcpd caches tool definitions for instant startup:

- **30-600x faster startup** (<100ms vs 3-60s)
- **Query stopped servers** - tools available from cache
- **Persistent** - survives daemon restarts
- **Smart invalidation** - auto-updates when config changes

### HTTP Server Support (v1.2+)

Connect to HTTP-based MCP servers:

```json
{
  "mcpServers": {
    "deepwiki": {
      "type": "http",
      "url": "https://mcp.deepwiki.com/mcp"
    },
    "custom-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
```

## Platform Support

| Platform | Architecture | Status |
|----------|-------------|--------|
| Windows  | x64         | ✅ Supported |
| Linux    | x64         | 📋 Coming soon |
| macOS    | x64         | 📋 Coming soon |
| macOS    | ARM64       | 📋 Coming soon |

## Troubleshooting

### Unsupported Platform Error

If you see:
```
Error: Unsupported platform: linux-x64
```

This means the platform is not yet supported. Check for updates:
```bash
npm update -g mcpd
```

### Server Won't Start

Check logs:
```bash
mcpd logs <server-name>
```

Common issues:
- Command not found: Install the MCP server package
- Permission denied: Check file permissions
- Port conflicts: Some servers need specific ports

## Documentation

Full documentation: [GitHub Repository](https://github.com/yourusername/mcpd)

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Links

- [GitHub Repository](https://github.com/yourusername/mcpd)
- [Issue Tracker](https://github.com/yourusername/mcpd/issues)
- [npm Package](https://www.npmjs.com/package/mcpd)
