生成
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步 — 列出可用服务器
输出:注意`server_id`您要管理的服务器的名称。
第 2 步 — 启动服务器
在后台生成服务器进程。日志转到:当没有连接的客户端时,MCP stdio 服务器立即退出 - 这是预期的。服务器并不意味着连续独立运行;它是由客户按需启动的。
第 3 步 — 检查服务器状态
对于使用 CDP 的服务器(受 Akamai 保护的网站,例如 Expedia),状态还显示浏览器会话运行状况:
第 4 步 — 停止服务器
发送 SIGTERM 并清除 PID 文件。
第 5 步 — 连接到 Claude Code
将服务器添加到`~/.claude.json`下`mcpServers`。 Claude Code 通过以下方式自动启动服务器进程`command`+`args`。具体示例(将路径替换为您实际的noui目录):保存后,重新启动Claude Code。服务器中定义的工具将在 Claude Code 的工具列表中可用。您可以通过运行来验证`/noui-generate-mcp`在克劳德代码中。
# NoUI MCP Server Lifecycle
Manage generated FastMCP servers and connect them to Claude Code. Servers are generated by `/noui-record-workflow` and live under `workbench/mcp_servers/<app_slug>/<server_id>/`.
All commands run from the `noui/` directory using `.venv/bin/python cli/main.py`.
**Prerequisite:** At least one server must exist under `workbench/mcp_servers/`. Run `/noui-record-workflow` first if none exist.
**How requests are executed:** by default, each tool opens a WebSocket to Tabby's CDP endpoint and runs `fetch(..., {credentials: 'include'})` inside the authenticated browser. A live Tabby session with the target site open is required at invocation time. See `/noui-record-workflow` → *How Execution Works* for the full explanation and the `--execution-mode http` escape hatch.
---
## Critical Rules (Never Violate)
- **ALWAYS** run `mcp list` first to get the exact `server_id` before any other command
- **NEVER** edit `server.py` or `manifest.json` directly — regenerate by re-running `workflow export --as mcp`
- When adding to `~/.claude.json`, **ALWAYS** use the absolute path to `.venv/bin/python` — not the system `python` or `python3`
- **ALWAYS** restart Claude Code after editing `~/.claude.json` — the config is read at startup
- You do **not** need to run `mcp start` separately when using the `~/.claude.json` stdio config — Claude Code launches the process automatically
Every generated server folder includes an **`API.md`** file — a human-readable API reference for all tools. Read it to understand a server's tools without inspecting `tools.json` or operation files. Refresh it with `mcp docs <server_id>` after any edit to `tools.json`.
---
## Step 1 — List Available Servers
```bash
.venv/bin/python cli/main.py mcp list
```
Output:
```
MCP servers:
SERVER ID APP TOOLS STATUS
-----------------------------------------------------------------------
hubspot-create-contact-abc12345 HubSpot 3 stopped
jsonplaceholder-test-3ab1cc83 Jsonplaceholder Test 2 running (PID 46929)
```
Note the `server_id` of the server you want to manage.
---
## Step 2 — Start a Server
```bash
.venv/bin/python cli/main.py mcp start <server_id>
```
Spawns the server process in the background. Logs go to:
```
workbench/mcp_servers/<app_slug>/<server_id>/.mcp-<server_id>.log
```
> MCP stdio servers exit immediately when there is no connected client — this is expected. The server is not meant to run continuously standalone; it is launched on-demand by the client.
---
## Step 3 — Check Server Status
```bash
.venv/bin/python cli/main.py mcp status <server_id>
```
For servers that use CDP (Akamai-protected sites like Expedia), status also shows browser session health:
```
CDP : ✓ reachable (localhost:9222) ← worker is running
CDP : ✗ not reachable (localhost:9222) ← run: noui tabby session ensure
```
---
## Step 4 — Stop a Server
```bash
.venv/bin/python cli/main.py mcp stop <server_id>
```
Sends SIGTERM and clears the PID file.
---
## Step 5 — Connect to Claude Code
Add the server to `~/.claude.json` under `mcpServers`. Claude Code launches the server process automatically via `command` + `args`.
```json
{
"mcpServers": {
"<server_id>": {
"type": "stdio",
"command": "/absolute/path/to/noui/.venv/bin/python",
"args": [
"/absolute/path/to/noui/workbench/mcp_servers/<app_slug>/<server_id>/server.py"
]
}
}
}
```
**Concrete example** (replace paths with your actual noui directory):
```json
{
"mcpServers": {
"jsonplaceholder-test-3ab1cc83": {
"type": "stdio",
"command": "/home/gabriel/Documents/adopt/noui/.venv/bin/python",
"args": [
"/home/gabriel/Documents/adopt/noui/workbench/mcp_servers/jsonplaceholder-test/jsonplaceholder-test-3ab1cc83/server.py"
]
}
}
}
```
After saving, **restart Claude Code**. The tools defined in the server will be available in Claude Code's tool list. You can verify by running `/noui-generate-mcp` in Claude Code.
---
## Decision Flow
```
Start
│
├─ Need to see what servers exist?
│ └─ Step 1: mcp list
│
├─ Auth not working / not sure if server is ready?
│ ├─ mcp verify <server_id> → PASS / NEEDS_SECRET / REPAIR_APPLIED
│ └─ mcp diagnose-auth <server_id> → full breakdown with repair suggestions
│
├─ Need to run a server standalone (test/debug)?
│ ├─ Step 2: mcp start <server_id>
│ ├─ Step 3: mcp status <server_id>
│ └─ Step 4: mcp stop <server_id>
│
└─ Need to use tools from Claude Code?
└─ Step 5: add to ~/.claude.json → restart Claude Code
└─ Verify: /mcp in Claude Code shows the server
```
---
## CLI Command Reference
| Command | Purpose |
|---|---|
| `.venv/bin/python cli/main.py mcp list` | List all generated servers with running status |
| `.venv/bin/python cli/main.py mcp start <server_id>` | Start a server process in the background |
| `.venv/bin/python cli/main.py mcp stop <server_id>` | Stop a running server process |
| `.venv/bin/python cli/main.py mcp status <server_id>` | Show running state, tool count, manifest path, and CDP reachability (for browser-based servers) |
| `.venv/bin/python cli/main.py mcp docs <server_id>` | Regenerate `API.md` from current `tools.json` |
| `.venv/bin/python cli/main.py mcp docs <server_id> --check` | Exit non-zero if `API.md` is stale (for CI / agent validation) |
| `.venv/bin/python cli/main.py mcp verify <server_id>` | Run AuthVerifier — reports PASS / REPAIR_APPLIED / NEEDS_SECRET / UNSUPPORTED |
| `.venv/bin/python cli/main.py mcp diagnose-auth <server_id>` | Full auth diagnosis: strategy, env var status, per-step verification, repair suggestions |
---
## Troubleshooting
| Symptom | Fix |
|---|---|
| `mcp list` shows no servers | No workflows exported yet — run `/noui-record-workflow` first |
| `MCP server '<id>' not found` | Run `mcp list` to get the exact `server_id` string |
| Server crashes immediately | Check `.mcp-<server_id>.log` in the server dir for Python errors |
| Stale PID (shows running but is not) | `mcp stop <server_id>` clears stale PID; then `mcp start` again |
| Claude Code does not see tools after adding to config | Confirm absolute paths are correct; restart Claude Code; run `/noui-generate-mcp` to verify connection |
| `server.py not found` error | Re-run `workflow export --as mcp` for that session to regenerate the server |
| Auth errors at runtime (authenticated server) | Run `mcp diagnose-auth <server_id>` — shows missing env vars and repair steps |
| `NEEDS_SECRET <VAR>` from verify | Set `<VAR>=<value>` in `noui/.env` and re-run `mcp verify <server_id>` |
| Server is v1 (no `auth_plan.json`) | Re-export with `workflow export --as mcp ... --profile-slug <slug> --verify` to upgrade to v2 |
| Tool fails with "All connection attempts failed" | CDP-based server needs browser session — run `mcp status <server_id>` to check CDP, then `noui tabby session ensure` |
| Tabby session shows HEALTHY but tools still fail | Worker crashed but DB state is stale — run `noui tabby session ensure` (auto-detects and restarts dead workers) |
| Exported server has `profile_slug: null` | No `--profile-slug` was passed at export time — re-export: `workflow export --as mcp <session_id> --profile-slug <slug>` |
---
> Source: [adoptai/noui](https://github.com/adoptai/noui) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
重要规则(切勿违反)
第 1 步 — 列出可用服务器
第 2 步 — 启动服务器
第 3 步 — 检查服务器状态
第 4 步 — 停止服务器
文件/命令 -> /noui-record-workflow · workbench/mcp_servers/<app_slug>/<server_id>/ · noui/ · .venv/bin/python cli/main.py · workbench/mcp_servers/ · fetch(..., {credentials: 'include'}) · --execution-mode http · mcp list
内容校验值 -> 975a9e9cb68a
当前原文的自动摘译,尚未人工审校。
重要规则(切勿违反)
永远奔跑
mcp list首先得到准确的server_id在任何其他命令之前切勿编辑server.py或manifest.json直接 — 通过重新运行重新生成workflow export --as mcp当添加到~/.claude.json,始终使用绝对路径.venv/bin/python——不是系统python或python3编辑后始终重新启动克劳德代码~/.claude.json— 配置在启动时读取 您不需要运行mcp start使用时单独~/.claude.jsonstdio config — Claude Code 自动启动进程