内容
# mcplease
`mcplease` 是一个本地的 MCP 聚合守护进程。配置您的 MCP 客户端一次与 `mcplease` 通信，然后在单个 XDG 配置文件中配置下游 MCP 服务器。
## MVP 状态
MVP 支持：
- 本地 MCP HTTP 端点；
- HTTP 上游 MCP 服务器；
- `initialize`、`tools/list` 和 `tools/call`；
- 命名空间工具，例如 `github.search_repositories`；
- 按上游设置的头部信息，支持 `${ENV_VAR}` 扩展。
- 按上游设置的头部信息和 stdio 环境变量，支持 `op://` 1Password 引用。
- 用于上游和单个工具的 TUI 切换。
## 配置路径
配置路径优先级：
1. `--config`
2. `MCPLEASE_CONFIG`
3. `$XDG_CONFIG_HOME/mcplease/config.yaml`
4. `~/.config/mcplease/config.yaml`
## 示例配置
```yaml
version: 1
server:
listen: 127.0.0.1:7331
storage:
path: ~/.config/mcplease/mcplease.db
stats:
enabled: true
upstreams:
github:
transport: http
url: http://127.0.0.1:3101/mcp
headers:
Authorization: "Bearer ${GITHUB_MCP_TOKEN}"
```
上游 `headers` 和 stdio `env` 值中的机密信息可以来自环境变量或 1Password：
```yaml
upstreams:
github:
transport: http
url: http://127.0.0.1:3101/mcp
headers:
Authorization: "Bearer op://Private/GitHub MCP/token"
context7:
transport: stdio
command: npx
args:
- -y
- "@upstash/context7-mcp"
env:
CONTEXT7_API_KEY: "op://Private/Context7/token"
```
1Password 引用在启动时使用 `op read <reference>` 读取，因此 1Password CLI 必须已安装并登录。缺少 CLI、无效引用或锁定的 1Password 会话会导致配置加载失败，并影响配置字段出错。
`storage.path` 是用于使用情况统计、OAuth 令牌、已知工具和禁用工具策略的单个 SQLite 数据库。仅设置 `stats.path` 的旧配置将继续使用该路径作为存储数据库。
## 运行
```bash
cargo run -- --config ./config.yaml
```
## TUI
```bash
cargo run -- tui --config ./config.yaml
```
使用 `Tab` 在上游和工具屏幕之间切换。工具行从上一次成功的守护进程发现中填充。禁用工具会将其隐藏在 `tools/list` 中，并立即拒绝 `tools/call；` 无需重新加载。
## 工具搜索范围
默认情况下，`mcplease` 通过 `/mcp` 上的 `tools/list` 公开每个已发现的上游工具。对于大型工具目录，请指向客户端到 `/mcp/search` 以公开一个小型网关曲面：
```text
http://127.0.0.1:7331/mcp/search
```
搜索模式公开：
- `search_tools`：搜索隐藏的工具目录并返回紧凑的候选项。
- `describe_tools`：返回完整定义和输入模式以获取确切的工具名称。
- `call_tool`：通过确切的公开名称调用真正的上游工具。
搜索后端是内部的。它使用本地 SQLite 存储数据库与 FTS5/BM25，并在启动发现和热重载后重建索引。
要直接检查本地工具搜索索引：
```bash
mcplease call tool-search --query "github repositories"
```
## 日志
默认情况下，`mcplease` 在 `info` 级别记录日志，除非设置了 `RUST_LOG`。
对于调试日志：
```bash
cargo run -- --config ./config.yaml --log-level debug
```
`--log-level` 接受 `trace`、`debug`、`info`、`warn` 或 `error`，并覆盖 `mcplease` 日志的 `RUST_LOG`。
对于结构化 JSON 日志：
```bash
cargo run -- --config ./config.yaml --log-level debug --json-logs
```
