servagent (0d4fcc)

仆人

Servagent是一个MCP（模型上下文协议）服务器，它使远程AI能够完全控制Linux服务器：命令执行、文件管理、服务管理等。

运输

服务器同时公开两个MCP传输：

特性

每个工具都有MCP注释 ToolAnnotations （只读、破坏性、幂等）来指导AI客户端。服务器指令包括反循环规则、错误处理和工作流指南。冗余工具（ls、cp、mv、rm、ps、kill等）已被删除-- execute_command 涵盖了所有这些用例。

先决条件

• Linux（Ubuntu/Debian、RHEL/CentOS等）
• Python>=3.10
• 安装即服务的根访问权限

单层衬里安装

只需一个命令即可直接在服务器上安装：

# Simple HTTP installation (by IP)
curl -sSfL https://raw.githubusercontent.com/servagent/servagent/main/install-remote.sh | sudo bash

# HTTPS installation with Let's Encrypt
curl -sSfL https://raw.githubusercontent.com/servagent/servagent/main/install-remote.sh | sudo bash -s -- your-domain.com

# Installation with full sudo privileges + HTTPS
curl -sSfL https://raw.githubusercontent.com/servagent/servagent/main/install-remote.sh | sudo bash -s -- --full-access your-domain.com

# Install a specific version
curl -sSfL https://raw.githubusercontent.com/servagent/servagent/main/install-remote.sh | sudo bash -s -- --version v0.2.0

脚本会自动下载最新版本（或 main 分支（如果不存在版本），提取存档并运行安装。这 -y 标志会自动注入，从而跳过交互式提示（因为stdin不是 curl | bash 管道）。

从Git克隆安装

如果您更喜欢手动克隆存储库：

# 1. Clone the repository
git clone https://github.com/Servagent/servagent.git
cd servagent

# 2a. Simple HTTP installation (by IP)
sudo bash install.sh

# 2b. OR direct HTTPS installation with Let's Encrypt
sudo bash install.sh your-domain.com

# 2c. OR installation with full sudo privileges (no interactive prompt)
sudo bash install.sh --full-access your-domain.com

脚本会自动执行以下操作：

• 创建一个 servagent 系统用户
• 安装在 /opt/servagent 使用virtualenv
• 生成API密钥（显示一次- 保存它)
• 创建并启用systemd服务
• 如果提供了域：让我们加密证书，端口443上的HTTPS，自动续订
• 交互式提示 授予完整的sudo权限（或 --full-access 自动化）

# Check status
servagent status

# View logs
sudo journalctl -u servagent -f

服务器在安装结束时自动启动：

• 无域名： http://:8765/mcp （流式HTTP）或 /sse 上海证券交易所
• 使用域： https://your-domain.com/mcp （流式HTTP）或 /sse 上海证券交易所

手动安装（开发）

# Create a virtualenv
python3 -m venv .venv
source .venv/bin/activate

# Install the project
pip install -e .

# Configure
cp .env.example .env
# Edit .env to set SERVAGENT_API_KEY

# Run
servagent

# Available commands
servagent --help
servagent --version

状态

检查服务状态和当前配置：

servagent status

显示：systemd服务状态（活动/非活动/失败）、PID、正常运行时间和配置摘要（端口、API密钥、OAuth、TLS、启用的工具）。API密钥和OAuth机密被屏蔽（只显示最后6个字符）。如果 .env 文件不可读，命令会自动升级 sudo.

API密钥管理

通过CLI生成和管理API密钥：

servagent apikey setup       # Generate an API key and write it to .env
servagent apikey renew       # Regenerate the API key (invalidates the current one)
servagent apikey remove      # Comment out the API key in .env

密钥仅在生成时完整显示(setup / renew).使用 servagent status 以验证其是否已配置（屏蔽）。

卸载

要从服务器中完全删除Servagent，请执行以下操作：

servagent uninstall              # Interactive (confirmation required)
servagent uninstall -y           # Non-interactive (no confirmation)
servagent uninstall --keep-certs # Keep Let's Encrypt certificates

脚本会自动删除：

• systemd服务和证书更新定时器
• Nginx配置（如适用）
• sudoers文件(/etc/sudoers.d/servagent)
• 应用程序目录(/opt/servagent：virtualenv， .env，来源）
• 这 servagent 系统用户
• 让我们加密证书（除非 --keep-certs 使用）

备注：系统包（certbot、python3、nginx）不会被删除，因为它们可能会被其他服务使用。

更新

更新到最新版本：

servagent update             # Update from the current branch
servagent update develop     # Update from a specific branch
servagent update --force     # Force reinstallation even if already up to date

脚本会自动执行以下操作：

1. 跑动 git pull 获取最新更改
2. 将源复制到 /opt/servagent/
3. 以可编辑模式重新安装软件包(pip install -e)在virtualenv中
4. 重新启动服务
5. 验证服务是否正常运行

如果未检测到任何更改，则脚本将停止而不重新启动服务。如果出现问题，将在执行结束时显示回滚命令。

配置

所有选项都可以通过环境变量或 .env 文件：

使用Let’s Encrypt的HTTPS

TLS直接内置于 install.sh。只需将域作为参数传递（请参阅单行安装）。

先决条件：域必须指向服务器的IP，并且端口80必须打开以接受Let's Encrypt的HTTP-01挑战。

要在已安装HTTP的服务器上启用HTTPS，请执行以下操作：

sudo bash setup-tls.sh your-domain.com

替代方案：Nginx反向代理

如果您更喜欢使用Nginx（当其他web服务在同一服务器上运行时很有用）：

# 1. Install Nginx and Certbot
sudo apt install nginx certbot python3-certbot-nginx

# 2. Obtain a Let's Encrypt certificate
sudo certbot --nginx -d your-domain.com

# 3. Copy the Nginx configuration
sudo cp nginx.conf.example /etc/nginx/sites-available/servagent
# Edit the file to replace 'your-domain.com' with your domain

# 4. Enable and reload
sudo ln -s /etc/nginx/sites-available/servagent /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

然后可以通过HTTPS访问MCP端点： https://your-domain.com/mcp

备注：在反向代理后面，设置 SERVAGENT_HOST=127.0.0.1 因此服务器会自动禁用MCP SDK的DNS重新绑定保护（Nginx已经处理了主机头验证）。

从MCP客户端连接

克劳德代码

Claude Code通过可流式HTTP本机支持远程MCP服务器。将此配置添加到Claude代码设置文件（.mcp.json，项目设置，ou via claude mcp add) :

{
  "mcpServers": {
    "servagent": {
      "type": "streamable-http",
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

克劳德桌面

Claude Desktop仅通过以下方式支持本地MCP服务器： stdio.要连接到远程服务器，请使用 mcp-remote 作为一座桥。将此添加到您的 claude_desktop_config.json :

{
  "mcpServers": {
    "servagent": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-domain.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

mcp-remote 创建本地stdio服务器，将请求中继到远程HTTP服务器。需要安装Node.js。

其他客户端（LM Studio等）

支持本机可流式HTTP的客户端可以使用以下配置：

{
  "mcpServers": {
    "servagent": {
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

SSE（传统客户）

{
  "mcpServers": {
    "servagent": {
      "url": "https://your-domain.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

卷曲测试

# Health check (the MCP endpoint responds to POST requests)
curl -X POST https://your-domain.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

文件上传

这 POST /upload 端点允许通过以下方式将文件发送到远程服务器 multipart/form-data它受到与MCP端点相同的Bearer令牌的保护。

# Send a file to the server
curl -X POST https://your-domain.com/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@my-file.tar.gz" \
  -F "path=/opt/app/my-file.tar.gz" \
  -F "create_dirs=true"

表单字段：

• file （必填）：要发送的文件
• path （必需）：远程服务器上的目标路径
• create_dirs （可选，默认 true)：如果需要，创建父目录

最大尺寸可通过以下方式配置 SERVAGENT_UPLOAD_MAX_SIZE （默认值：100 MB）。

认证

服务器支持两种共存的身份验证机制：

这两种机制并行工作。Bearer令牌允许直接访问所有端点。OAuth支持标准的注册和授权流程。

这 /.well-known/ 端点（OAuth发现，RFC 8414/RFC 9728）始终可以在没有身份验证的情况下访问。

OAuth 2.0（流式HTTP）

除了简单的Bearer令牌身份验证外，服务器还支持OAuth 2.0 /mcp 终点。这允许兼容的MCP应用程序通过标准OAuth协议（授权码+PKCE，RFC 7636）进行连接。

启用OAuth

# Auto-detects the issuer URL from TLS cert domain or server IP
servagent oauth setup

# Explicit issuer URL (if auto-detection fails)
servagent oauth setup --issuer-url https://your-domain.com/mcp

这会产生 CLIENT_ID 和 CLIENT_SECRET，并写下所有三个 SERVAGENT_OAUTH_* 变量到 .env:

# In .env — the URL MUST include the /mcp path
SERVAGENT_OAUTH_ISSUER_URL=https://your-domain.com/mcp

# Operator credentials (dual purpose: static OAuth client + /mcp/register protection)
SERVAGENT_OAUTH_CLIENT_ID=servagent-xxxxxxxxxxxxxxxx
SERVAGENT_OAUTH_CLIENT_SECRET=a-strong-randomly-generated-secret

续订/删除OAuth

# Regenerate credentials (invalidates all existing sessions)
servagent oauth renew

# Disable OAuth entirely (comments out vars in .env, removes database)
servagent oauth remove

# Disable OAuth but keep the database file
servagent oauth remove --keep-db

启用OAuth时：

• /mcp 受OAuth保护（MCP SDK处理令牌） 或 通过Bearer代币(API_KEY)
• /mcp/register 受HTTP基本身份验证保护 CLIENT_ID:CLIENT_SECRET
• /sse, /messages/, /upload 保持受简单Bearer令牌的保护(API_KEY)
• /.well-known/ 始终无需身份验证即可访问（OAuth发现）

身份验证矩阵

CLIENT_ID/CLIENT_SECRET的双重用途

操作员凭据(CLIENT_ID / CLIENT_SECRET)有两个目的：

1. 静态OAuth客户端：在启动时，服务器在SQLite数据库中将这些凭据预注册为有效的OAuth客户端（通过 ensure_static_client()).这允许Claude.ai和ChatGPT等接口在OAuth流中直接使用CLIENT_ID/SECRET（授权→ 令牌） 不打电话 /mcp/register已知平台（Claude.ai、ChatGPT）的重定向URI是自动预配置的。

1. /mcp/register 保护：相同的凭据通过HTTP基本身份验证保护动态注册端点。编程客户端（脚本、SDK）可以注册以获得自己的 client_id/client_secret.

两种模式共存：静态客户端适用于UI（Claude.ai、ChatGPT等），动态注册适用于脚本和SDK。

从Claude.ai连接

1. 关于Claude.ai，请访问 设置 → 连接器 → 添加自定义连接器
2. 填写以下字段：

- 名字: servagent （或您选择的名称） - 远程MCP服务器URL: https://your-domain.com/mcp - OAuth客户端ID：价值 SERVAGENT_OAUTH_CLIENT_ID - OAuth客户端密码：价值 SERVAGENT_OAUTH_CLIENT_SECRET

1. 确认--Claude.ai自动执行OAuth流（发现→ 授权→ 令牌）

从ChatGPT连接

1. 在ChatGPT上，转到 设置 → 连接器 → 添加自定义连接器
2. 填写以下字段：

- 名字: servagent - MCP服务器URL: https://your-domain.com/mcp - 客户端ID：价值 SERVAGENT_OAUTH_CLIENT_ID - 客户端密钥：价值 SERVAGENT_OAUTH_CLIENT_SECRET

1. 确认--ChatGPT使用其重定向URI执行OAuth流(https://chatgpt.com/connector_platform_oauth_redirect)

OAuth端点（位于 /mcp)

备注：The /.well-known/ 发现URL既可以在域根级别访问，也可以在以下级别访问 /mcp.307在根级别重定向到 /mcp 子应用程序，以确保与所有MCP客户端的兼容性。

OAuth流（动态注册）

对于使用动态注册的程序化客户端：

# 1. Register a client (HTTP Basic Auth with CLIENT_ID:CLIENT_SECRET)
curl -X POST https://your-domain.com/mcp/register \
  -u "MY_CLIENT_ID:MY_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": ["http://localhost:3000/callback"],
    "client_name": "My App",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "client_secret_post"
  }'
# → returns dynamic client_id + client_secret

然后，标准OAuth流程正常进行：

1. 客户端通过以下方式发现端点 GET /.well-known/oauth-authorization-server/mcp （或 /mcp/.well-known/oauth-authorization-server)
2. 客户端通过以下方式获得授权码 /mcp/authorize （使用PKCE）
3. 客户端通过以下方式将代码交换为访问令牌 POST /mcp/token
4. 客户端使用访问令牌进行调用 /mcp

服务器使用自动批准模型：任何注册的客户端（静态或动态）都被视为已授权。

访问令牌将在1小时后过期。刷新令牌持续30天，自动轮换。

存储

OAuth客户端和令牌保存在SQLite数据库中（默认值： ~/.servagent/oauth.db).数据在服务器重启后仍然有效。静态客户端在每次启动时都会重新注册（升级）。

技能

技能允许您使用特定于您的服务器的信息来丰富发送到LLM的上下文：托管域、SMTP凭据、可用服务等。每个技能都是一个目录，其中包含 SKILL.md 其内容被注入到MCP指令中的文件。

这 skills/ 目录位于项目根目录（在dev中）或 /opt/servagent/skills/ （生产中）。其内容被git忽略(.gitignore)因为它可能包含每个服务器特有的敏感信息。

结构

skills/
├── .gitkeep
├── webserver/
│   └── SKILL.md
├── smtp/
│   └── SKILL.md
└── docker/
    └── SKILL.md

例子： skills/webserver/SKILL.md

# webserver
Domain: myserver.com (points to this server)
Web root: /var/www/myserver.com
Nginx config: /etc/nginx/sites-available/myserver.com
SSL: Let's Encrypt, auto-renew via certbot timer

例子： skills/smtp/SKILL.md

# smtp
This server can send emails via SMTP.
- Host: smtp.gmail.com
- Port: 587
- User: bot@myserver.com
- Password: xxxx-xxxx-xxxx
- Use: `msmtp` or `swaks` CLI (already installed)

每个的内容 SKILL.md 按原样注入MCP指令中 ## Skills 部分。如果文件以markdown标题开头(#)，按原样使用。否则，a ### directory_name 标题是自动添加的。

安全

警告：此服务器可以完全控制主机。妥善固定。

• 总是 集 SERVAGENT_API_KEY 生产中
• 总是 使用TLS(setup-tls.sh 或Nginx）在生产中
• 通过防火墙限制端口访问(ufw, iptables)
• 该服务在专用用户下运行(servagent)
• 默认情况下，用户具有 不 sudo权限(NoNewPrivileges=true)
• 这 --full-access 选项（或交互式提示）授予 sudo NOPASSWD: ALL 通过 /etc/sudoers.d/servagent 并禁用 NoNewPrivileges

项目结构

servagent/
  src/servagent/
    __init__.py        # Version
    cli.py             # CLI entry point (click subcommands: run, status, uninstall, update, apikey, oauth)
    config.py          # Configuration (pydantic-settings)
    auth.py            # Authentication middleware (Bearer + Basic Auth + OAuth)
    oauth_provider.py  # OAuth 2.0 provider with SQLite storage + static client
    tools.py           # All MCP tools
    server.py          # Server module, Starlette app + MCP (Streamable HTTP + SSE + .well-known)
  skills/              # Skills directory (content in .gitignore)
    .gitkeep
  pyproject.toml                  # Metadata and dependencies
  install.sh                      # Linux installation script (from git clone)
  install-remote.sh               # One-liner installation script (curl | bash)
  uninstall.sh                    # Complete uninstallation script
  setup-tls.sh                    # HTTPS setup with Let's Encrypt
  generate-oauth-credentials.sh   # CLIENT_ID / CLIENT_SECRET generator
  nginx.conf.example              # Nginx configuration (optional)
  .env.example                    # Configuration template

了解更多

MCP（模型上下文协议）

• 模型上下文协议.io --官方文档、指南和教程
• --规范和文档链接
• 规格（2025-11-25） --直接访问注明日期的规范

技能

• agentskills.io 网站 --代理技能文档
• --代理技能规范和示例

许可证

麻省理工学院