# Nginx Proxy Manager MCP Server

一个用于管理 Nginx Proxy Manager 的 Model Context Protocol (MCP) 服务器。

## ✨ 特性

- 🔐 **自动 JWT 刷新**：在 token 即将过期时自动刷新，避免多轮对话中认证失败
- 🛠️ **完整的 API 覆盖**：支持 Proxy Hosts、Redirection Hosts、Dead Hosts、Streams 等所有资源
- 📝 **支持 advanced_config**：创建/更新记录时完全支持 `advanced_config` 和 `locations[].advanced_config`
- 🔄 **自动重试**：收到 401 错误时自动重新登录并重试请求
- 🌐 **多种传输模式**：支持 stdio 和 Streamable HTTP 两种模式
- 🔧 **灵活配置**：支持命令行参数、环境变量、HTTP Headers 多种配置方式

## 📋 支持的 Tools

| 类别 | Tools |
|------|-------|
| **Proxy Hosts** | `npm_list_proxy_hosts`, `npm_get_proxy_host`, `npm_create_proxy_host`, `npm_update_proxy_host`, `npm_delete_proxy_host`, `npm_enable_proxy_host`, `npm_disable_proxy_host` |
| **Redirection Hosts** | `npm_list_redirection_hosts`, `npm_get_redirection_host`, `npm_create_redirection_host`, `npm_update_redirection_host`, `npm_delete_redirection_host`, `npm_enable_redirection_host`, `npm_disable_redirection_host` |
| **Dead Hosts** | `npm_list_dead_hosts`, `npm_get_dead_host`, `npm_create_dead_host`, `npm_update_dead_host`, `npm_delete_dead_host`, `npm_enable_dead_host`, `npm_disable_dead_host` |
| **Streams** | `npm_list_streams`, `npm_get_stream`, `npm_create_stream`, `npm_update_stream`, `npm_delete_stream`, `npm_enable_stream`, `npm_disable_stream` |
| **Access Lists** | `npm_list_access_lists`, `npm_get_access_list`, `npm_create_access_list`, `npm_update_access_list`, `npm_delete_access_list` |
| **Certificates** | `npm_list_certificates`, `npm_get_certificate`, `npm_create_certificate`, `npm_delete_certificate`, `npm_renew_certificate`, `npm_list_dns_providers`, `npm_test_http_challenge` |
| **Users** | `npm_list_users`, `npm_get_user`, `npm_create_user`, `npm_update_user`, `npm_delete_user`, `npm_get_user_permissions`, `npm_set_user_permissions` |
| **Settings** | `npm_list_settings`, `npm_get_setting`, `npm_update_setting`, `npm_list_audit_log`, `npm_get_report` |

## ⚠️ 已知问题

以下工具在 NPM API 层面存在问题，**并非本 MCP Server 的 bug**：

| 工具 | 错误 | 说明 |
|------|------|------|
| `npm_get_report` | `Not Found - /reports` | NPM API 端点 `/reports` 不存在，可能需要更新 NPM 版本 |
| `npm_create_user` | `Internal Error` | NPM API 返回 500，疑似 NPM 后端 bug，与传参无关 |
| `npm_get_user_permissions` | `Not Found - /users/{id}/permissions` | 权限查询端点不存在，NPM 可能已变更该 API 路径 |
| `npm_set_user_permissions` | 同上 | 依赖同一端点，同样不可用 |

> 以上问题需在 Nginx Proxy Manager 侧修复后才能正常工作。

## 🚀 快速开始

### 1. 安装依赖

```bash
pnpm install
```

### 2. 配置环境变量（可选）

对于 **stdio 模式**，需要配置 NPM 连接信息。对于 **Streamable HTTP 模式**，可以通过 HTTP Headers 提供配置。

复制 `.env.example` 到 `.env`：

```bash
cp .env.example .env
```

`.env` 文件内容：

```env
# Nginx Proxy Manager Configuration
NPM_BASE_URL=http://your-npm-server:81
NPM_USERNAME=admin@example.com
NPM_PASSWORD=your_password

# Optional: Token refresh margin in seconds (default: 300 = 5 minutes)
NPM_TOKEN_REFRESH_MARGIN=300

# MCP Transport Configuration
# Options: stdio (default), streamable-http
MCP_TRANSPORT=stdio

# Streamable HTTP Configuration (only used when MCP_TRANSPORT=streamable-http)
MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=1234
# Optional: Auth token for HTTP mode (clients must send Authorization: Bearer <token>)
MCP_HTTP_AUTH_TOKEN=
```

### 3. 编译

```bash
pnpm run build
```

### 4. 运行

**stdio 模式**（默认，适合 Claude Desktop）：

```bash
pnpm run start
```

**Streamable HTTP 模式**（适合远程访问）：

```bash
pnpm run start:http
```

## 🔧 配置方式

配置优先级（从高到低）：

1. **命令行参数** - `--base-url`, `--username`, `--password`
2. **环境变量 / .env 文件** - `NPM_BASE_URL`, `NPM_USERNAME`, `NPM_PASSWORD`
3. **HTTP Headers** - `NPM-Base-Url`, `NPM-Username`, `NPM-Password`（仅 Streamable HTTP 模式）

### 命令行参数

```bash
# stdio 模式
node dist/index.js --base-url http://10.0.1.199:81 --username admin@example.com --password mypassword

# Streamable HTTP 模式
node dist/index.js --transport streamable-http --host 0.0.0.0 --port 1234 --base-url http://10.0.1.199:81 --username admin@example.com --password mypassword
```

支持的参数：
- `--base-url` - NPM 服务器地址
- `--username` - NPM 用户名
- `--password` - NPM 密码
- `--transport` - 传输模式 (stdio 或 streamable-http)
- `--host` - HTTP 监听地址 (默认 0.0.0.0)
- `--port` - HTTP 端口
- `--auth-token` - MCP 认证 token

### HTTP Headers（Streamable HTTP 模式）

当环境变量未配置时，客户端可以通过 HTTP Headers 提供 NPM 配置：

```json
{
  "mcpServers": {
    "nginx-proxy-manager": {
      "type": "streamable-http",
      "url": "http://localhost:1234/mcp",
      "headers": {
        "NPM-Base-Url": "http://10.0.1.199:81",
        "NPM-Username": "admin@example.com",
        "NPM-Password": "password123"
      }
    }
  }
}
```

**优势**：
- 无需在服务器端配置 `.env`
- 不同客户端可以连接不同的 NPM 服务器
- 适合多租户场景

### 环境变量（stdio 模式）

对于 stdio 模式，MCP 客户端通常通过 `env` 字段传递配置：

```json
{
  "mcpServers": {
    "nginx-proxy-manager": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "NPM_BASE_URL": "http://10.0.1.199:81",
        "NPM_USERNAME": "admin@example.com",
        "NPM_PASSWORD": "password123"
      }
    }
  }
}
```

## 🌐 Streamable HTTP 模式

Streamable HTTP 模式允许通过 HTTP 访问 MCP Server，适合远程访问和团队共享。

### 启动

```bash
# 使用 .env 配置
pnpm run start:http

# 使用命令行参数
node dist/index.js --transport streamable-http --host 0.0.0.0 --port 1234
```

### API 端点

- **URL**: `http://<MCP_HTTP_HOST>:<MCP_HTTP_PORT>/mcp`
- **Methods**: `POST`, `GET`, `DELETE`
- **Content-Type**: `application/json`
- **Accept**: `application/json, text/event-stream`

### 认证

可选的 MCP 认证 token 保护：

```bash
# 通过环境变量
MCP_HTTP_AUTH_TOKEN=your-secret-token pnpm run start:http

# 通过命令行参数
node dist/index.js --transport streamable-http --auth-token your-secret-token
```

客户端配置：

```json
{
  "mcpServers": {
    "nginx-proxy-manager": {
      "type": "streamable-http",
      "url": "http://localhost:1234/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token",
        "NPM-Base-Url": "http://10.0.1.199:81",
        "NPM-Username": "admin@example.com",
        "NPM-Password": "password123"
      }
    }
  }
}
```

## 🔐 JWT 自动刷新机制

为了解决 Agent 多轮调用中 JWT 过期的问题，本 MCP Server 实现了以下机制：

1. **提前刷新**：在 token 即将过期前 5 分钟（可配置）自动刷新
2. **自动重试**：收到 401 错误时自动重新登录并重试请求
3. **并发安全**：多个请求同时触发刷新时，只会执行一次刷新

### 配置刷新间隔

在 `.env` 中设置 `NPM_TOKEN_REFRESH_MARGIN`（单位：秒）：

```env
# 在 token 过期前 5 分钟刷新（默认值）
NPM_TOKEN_REFRESH_MARGIN=300

# 在 token 过期前 10 分钟刷新
NPM_TOKEN_REFRESH_MARGIN=600
```

## 📝 使用示例

### 创建带 advanced_config 的 Proxy Host

```json
{
  "name": "npm_create_proxy_host",
  "arguments": {
    "domain_names": ["app.example.com"],
    "forward_scheme": "http",
    "forward_host": "127.0.0.1",
    "forward_port": 8080,
    "advanced_config": "proxy_set_header Host $host;\nproxy_set_header X-Real-IP $remote_addr;",
    "locations": [
      {
        "path": "/api",
        "forward_scheme": "http",
        "forward_host": "backend.local",
        "forward_port": 3000,
        "advanced_config": "proxy_set_header X-API-Key secret;"
      }
    ]
  }
}
```

### 更新 Proxy Host 的 advanced_config

```json
{
  "name": "npm_update_proxy_host",
  "arguments": {
    "host_id": 1,
    "advanced_config": "# Updated config\nproxy_buffering off;",
    "locations": [
      {
        "path": "/",
        "forward_scheme": "http",
        "forward_host": "10.0.1.101",
        "forward_port": 3000,
        "advanced_config": "proxy_set_header Host $host:60443;"
      }
    ]
  }
}
```

## 🚀 systemd 服务（开机启动）

Streamable HTTP 模式下，可以配置为 systemd 服务实现开机自动启动。

### 安装服务

```bash
# 编译项目
pnpm run build

# 安装 systemd 服务
pnpm run service:install
```

### 管理服务

```bash
# 启动/停止/重启
sudo systemctl start npm-mcp
sudo systemctl stop npm-mcp
sudo systemctl restart npm-mcp

# 查看状态
sudo systemctl status npm-mcp

# 查看日志（实时）
journalctl -u npm-mcp -f
```

### 开机启动控制

```bash
# 启用开机启动
sudo systemctl enable npm-mcp

# 禁用开机启动
sudo systemctl disable npm-mcp
```

### 卸载服务

```bash
pnpm run service:uninstall
```

## 🔧 开发

### 开发模式运行

```bash
# stdio 模式
pnpm run dev

# Streamable HTTP 模式
pnpm run dev:http
```

### 项目结构

```
mcp/
├── src/
│   ├── index.ts              # MCP Server 主入口
│   ├── npm-client.ts         # NPM API 客户端（含 JWT 自动刷新）
│   ├── types.ts              # TypeScript 类型定义
│   └── tools/
│       ├── proxy-hosts.ts    # Proxy Hosts tools
│       ├── redirection-hosts.ts  # Redirection Hosts tools
│       ├── dead-hosts.ts     # Dead Hosts tools
│       ├── streams.ts        # Streams tools
│       ├── access-lists.ts   # Access Lists tools
│       ├── certificates.ts   # Certificates tools
│       ├── users.ts          # Users tools
│       └── settings.ts       # Settings tools
├── scripts/
│   └── setup-systemd.sh      # systemd 服务安装脚本
├── docs/                     # API 文档
├── package.json
├── tsconfig.json
└── .env                      # 环境变量配置（可选）
```

## 📚 API 文档

详细的 API 文档请参考 `docs/` 目录：

- [README.md](docs/README.md) - API 概览
- [auth.md](docs/auth.md) - 认证与令牌
- [proxy-hosts.md](docs/proxy-hosts.md) - Proxy Hosts API
- [redirection-hosts.md](docs/redirection-hosts.md) - Redirection Hosts API
- [dead-hosts.md](docs/dead-hosts.md) - Dead Hosts API
- [streams.md](docs/streams.md) - Streams API
- [access-lists.md](docs/access-lists.md) - Access Lists API
- [certificates.md](docs/certificates.md) - Certificates API
- [users.md](docs/users.md) - Users API
- [settings.md](docs/settings.md) - Settings API

## 📄 License

MIT