内容
# Jakub 的 MCP 工具
MCP 服务器 + 基础设施发现和远程管理的 Web 仪表盘。通过 [Model Context Protocol](https://modelcontextprotocol.io) 为 AI 代理提供 SSH 命令执行、文件传输、日志跟踪和机器/服务库存的工具。配套的 Web 用户界面提供了一个基于浏览器的相同数据仪表盘。
所有组件 - MCP 服务器、REST API 和仪表盘 - 共享一个 SQLite 数据库。在 Web 界面中注册的机器和服务立即可用于 MCP 工具，代理执行的命令显示在仪表盘的活动日志中。
## Docker
```bash
docker compose up -d
# → 仪表盘： http://localhost:8082
```
数据库保存在主机上的 `./data` 中。配置您的 MCP 客户端：
```json
{
"mcpServers": {
"jakubs-mcp-tools": {
"command": "docker",
"args": ["compose", "run", "--rm", "mcp"]
}
}
}
```
## 在没有 Docker 的情况下运行
```bash
# 克隆并安装
git clone <仓库网址>
cd mcp-tools
cp .env.example .env
npm install
# 构建
npm run build
# 启动仪表盘 + API
npm run dev:all
# → 界面： http://localhost:8081
# → API： http://localhost:8082
# 直接运行 MCP 服务器
npm run dev
```
## 配置
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `DB_PATH` | `./infra.db` | SQLite 数据库文件路径 |
| `SSH_TIMEOUT` | `10000` | SSH 连接超时（毫秒） |
| `ALLOWLIST_ENABLED` | `true` | 设置为 `false` 以允许任何 SSH 命令而无需限制 |
| `ALLOWED_COMMANDS` | *(内置列表)* | 以逗号分隔的允许命令前缀（覆盖默认值） |
## 功能
### MCP 工具（适用于 AI 代理）
| 工具 | 描述 |
| --- | --- |
| `get_all_machines` | 列出所有机器及其微服务 |
| `get_machine_by_id` | 按 ID 查找特定机器 |
| `add_machine` | 注册新机器（主机名、IP、SSH 密钥） |
| `add_service` | 在机器上注册微服务 |
| `execute_ssh` | 通过 SSH 在远程机器上执行命令 |
| `scp_file` | 通过 SFTP 上传/下载文件 |
| `tail_logs` | 跟踪远程日志文件的最后 N 行 |
- **命令允许列表** - SSH 命令根据可配置的允许列表进行验证。 在 `.env` 中设置为 `ALLOWLIST_ENABLED=false` 以允许任何命令而无需限制。
- **审计跟踪** - 每个 SSH 命令和 SCP 传输都记录了退出代码、输出和时间戳。
- **基于密钥的身份验证** - 所有 SSH 连接都使用注册的私钥（无密码）。
### Web 仪表盘
- **仪表盘** - 综合统计、近期活动日志、活跃度最高的机器
- **机器** - 具有搜索、分页、CRUD 模态（主机名、操作系统、IP、SSH 用户）的表格
- **服务** - 具有搜索、机器筛选、分页、CRUD 模态（名称、网址、端口、类型、备注）的表格
- **日志** - 具有搜索、机器/状态筛选、详细视图和命令输出的完整审计跟踪
- 暗色主题、响应式（移动侧边栏抽屉）
## CLI 用法
每个模块都可以单独运行以进行测试：
```bash
# 查询机器
node dist/get_machines.js --all
node dist/get_machines.js --id 1
# 执行命令
node dist/execute_ssh.js --id 1 --cmd "docker ps"
# 传输文件
node dist/scp.js -i 1 -d to -r /tmp/out.txt -l ./local.txt
# 跟踪日志
node dist/tail_logs.js -i 1 -p /var/log/syslog -n 100
# 添加机器
node dist/add_entries.js add-machine --hostname web-01 --ip 10.0.0.1 --username root --key ~/.ssh/id_rsa
# 添加服务
node dist/add_entries.js add-service --machine-id 1 --name nginx --port 80 --type "Web hosting"
```
## npm 脚本
| 脚本 | 描述 |
| --- | --- |
| `build` | 编译 TypeScript（MCP 服务器 + API） |
| `start` | 运行 MCP 服务器 |
| `dev` | 构建 + 运行 MCP 服务器 |
| `dev:ui` | 仪表盘的 Vite 开发服务器 |
| `dev:api` | Node.js API 服务器（端口 8082） |
| `dev:all` | 同时运行界面 + API |
| `build:ui` | 仪表盘的生产版本 |
| `preview:ui` | 预览生产仪表盘版本 |
## 许可证
MIT
