> ## Documentation Index
> Fetch the complete documentation index at: https://coding-1afcb9be.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装与配置

> 包安装、入口命令、传输方式、权限模式和常用配置。

# 安装与配置

Coding Tools MCP 是一个 Python 包，安装后提供 `coding-tools-mcp` 命令。

## 安装

```bash theme={null}
python -m pip install coding-tools-mcp
```

包要求 Python `>=3.11`，运行时依赖包含 `PyJWT`。开发依赖可使用 `coding-tools-mcp[dev]`，图片能力相关依赖可使用 `coding-tools-mcp[image]`。

## 核心 CLI 参数

| 参数                                   | 默认值                                            | 用途                                              |
| ------------------------------------ | ---------------------------------------------- | ----------------------------------------------- |
| `--workspace`                        | `CODING_TOOLS_MCP_WORKSPACE` 或当前目录             | 暴露给文件工具和命令执行的工作区根目录。                            |
| `--host`                             | `CODING_TOOLS_MCP_HOST` 或 `127.0.0.1`          | HTTP 绑定地址。                                      |
| `--port`                             | `CODING_TOOLS_MCP_PORT` 或 `8000`               | HTTP 绑定端口。                                      |
| `--stdio`                            | `false`                                        | 使用逐行 JSON-RPC stdio，而不是 HTTP。                   |
| `--auth-token`                       | `CODING_TOOLS_MCP_AUTH_TOKEN`                  | 要求 `/mcp` 请求携带 `Authorization: Bearer <token>`。 |
| `--oauth-mode`                       | `false`                                        | 启用 OAuth 2.1 Authorization Code + PKCE。         |
| `--tool-profile`                     | `CODING_TOOLS_MCP_TOOL_PROFILE` 或 `full`       | 控制暴露哪些 MCP 工具。                                  |
| `--shell-env-inherit`                | `CODING_TOOLS_MCP_SHELL_ENV_INHERIT` 或 `core`  | 控制 `exec_command` 继承的基础环境变量。                    |
| `--permission-mode`                  | 运行时策略默认值                                       | 控制 `exec_command` 的安全门禁。                        |
| `--allow-network`                    | `false`                                        | 兼容别名：允许带网络特征的命令调用。                              |
| `--enable-view-image`                | 默认启用，除非 `CODING_TOOLS_MCP_ENABLE_VIEW_IMAGE=0` | 暴露 `view_image`。                                |
| `--dangerously-skip-all-permissions` | `false`                                        | 兼容别名：等价于 `--permission-mode dangerous`。         |

## 传输方式

HTTP：

```bash theme={null}
coding-tools-mcp --workspace /repo --host 127.0.0.1 --port 8000
```

请求入口是 `/mcp`，元数据也可从 `/.well-known/mcp.json` 和 `/.well-known/mcp/server-card.json` 获取。

Stdio：

```bash theme={null}
coding-tools-mcp --stdio --workspace /repo
```

stdio 适合由客户端直接管理 MCP server 子进程的场景。

## 鉴权

本地 loopback HTTP 可以无鉴权。非 loopback 绑定需要以下之一：

* `--auth-token` 或 `CODING_TOOLS_MCP_AUTH_TOKEN`
* `--oauth-mode` 或 `CODING_TOOLS_MCP_OAUTH_MODE=1`
* `CODING_TOOLS_MCP_AUTH_MODE=noauth`，仅用于外层已有可信鉴权和网络隔离的部署

`CODING_TOOLS_MCP_AUTH_MODE` 可取 `bearer`、`noauth`、`oauth`。

OAuth 相关环境变量包括：

* `CODING_TOOLS_MCP_OAUTH_CLIENT_ID`
* `CODING_TOOLS_MCP_OAUTH_CLIENT_SECRET`
* `CODING_TOOLS_MCP_OAUTH_PASSWORD`
* `CODING_TOOLS_MCP_SERVER_URL`
* `CODING_TOOLS_MCP_OAUTH_TOKEN_SECRET`
* `CODING_TOOLS_MCP_OAUTH_TOKEN_TTL`

如果未设置 OAuth password 或 token secret，服务会在运行时生成值，并把授权密码打印到 stderr。

## 工具 profile

| Profile               | 行为                               |
| --------------------- | -------------------------------- |
| `full`                | 暴露完整实现的工具集合。                     |
| `read-only`           | 隐藏会改变文件、进程状态或权限状态的工具。            |
| `compat-readonly-all` | 为兼容客户端把工具注解为只读，但其中一些工具仍可能改变本地状态。 |

## 权限模式

| 模式          | 网络特征命令 | Shell 展开和内联脚本 | Landlock | 敏感环境过滤 |
| ----------- | ------ | ------------- | -------- | ------ |
| `safe`      | 阻止     | 阻止            | 可用时启用    | 启用     |
| `trusted`   | 允许     | 允许            | 可用时启用    | 启用     |
| `dangerous` | 允许     | 允许            | 禁用       | 禁用     |

本地开发中需要包管理器、测试命令或 shell 特性时，通常使用 `trusted`。只有外层沙箱已经提供真实隔离时，才考虑 `dangerous`。

## 命令环境

`exec_command` 使用受控环境。`--shell-env-inherit` 支持：

* `core`：继承 PATH、locale 等核心变量。
* `all`：继承进程环境，但仍受过滤影响。
* `none`：从空基础环境开始，只使用显式设置。

不要把 token、私钥、API key 或密码放入 `exec_command.env`。在 `safe` 和 `trusted` 中，敏感名称、敏感值和风险 loader/startup 变量会被过滤。

## 运行时文件

默认运行时根目录位于系统临时目录下的 `coding-tools-mcp`。设置 `CODING_TOOLS_MCP_RUNTIME_ROOT` 可以覆盖该位置。