# CraftTable MCP CLI

`@game-crafttable/mcp-client` 提供主命令 `crafttable-mcp`，并保留兼容别名 `crafttable-mcp-client`。

## 快速安装与配置

在 PowerShell 中执行：

```powershell
npm install --global --allow-git=all --ignore-scripts git+https://git.crash.work/cneicy/crafttable-mcp-client.git; crafttable-mcp login; crafttable-mcp configure all
```

这条命令会安装 CLI、打开浏览器完成 OAuth 登录，并在用户级配置中为 Codex、Claude Code 和 OpenCode 注册同一个本地 stdio 桥及 `crafttable` Agent Skill。当工作区数据与当前任务相关时，该 Skill 可以帮助 Agent 主动发现并调用 CraftTable。

npm 12 默认拒绝 Git 类型的包依赖，因此安装命令需要显式传入 `--allow-git=all`。仓库已经包含构建后的 CLI bundle，`--ignore-scripts` 可以避免安装期间执行包生命周期脚本。

## 常用命令

```powershell
crafttable-mcp login
crafttable-mcp status
crafttable-mcp tools
crafttable-mcp call list_spaces '{}'
crafttable-mcp configure all
```

`configure` 会同时安装 MCP 配置和随包提供的 Skill。`unconfigure` 会在 Skill 仍由本 CLI 管理时将两者一并移除；如果用户修改过本地 Skill，则默认保留，只有显式传入 `--force` 才会删除。已有的不同配置不会被静默覆盖，`--dry-run` 可以预览 MCP 和 Skill 两部分的变更。

`login` 使用 Authorization Code + PKCE 完成登录，并将 OAuth token 保存到操作系统凭据库。凭据按 MCP Server URL 和 OAuth client ID 隔离，CLI 不会降级为明文 token 文件。

`serve` 是供 Codex、Claude Code 和 OpenCode 使用的 stdio MCP 桥。协议模式下，stdout 只输出 MCP JSON-RPC。如果本机没有 OAuth 凭据，CLI 可以兼容使用旧的 `CRAFTTABLE_MCP_TOKEN` 环境变量，并且只在 stderr 提示当前正在使用服务账号路径。

默认连接配置：

- URL：`https://crafttable.crash.work/mcp`
- OAuth client ID：`crafttable-mcp-cli`
- 回调地址：`http://127.0.0.1:48321/oauth/callback`

可以使用 `--url`、`--client-id`、`--callback-port` 覆盖默认值，也可以设置 `CRAFTTABLE_MCP_URL`、`CRAFTTABLE_MCP_OAUTH_CLIENT_ID`、`CRAFTTABLE_MCP_OAUTH_CALLBACK_PORT` 环境变量。

远程地址必须使用 HTTPS。只有 `localhost`、`127.0.0.1` 和 `::1` 开发地址允许使用明文 HTTP。

如果 OAuth metadata 路径返回 HTML、404 或非 JSON 响应，CLI 会明确指出服务端 OAuth 尚未启用或反向代理配置错误，不再直接输出 JSON parser 异常。