内容
# 米夫塔
**封装任意MCP。使用正确的账户，无需重新连接。**
米夫塔（`@lubab/miftah`）是一个本地MCP身份验证包装器和凭证代理，用于多账户工作流。它位于MCP客户端（如Claude Desktop）和现有的上游MCP服务器之间，注入选定配置文件的凭证，转发MCP操作，并记录编辑后的审计元数据。
米夫塔**不是** GitHub MCP、Sentry MCP、PostHog MCP或其他提供商MCP的替代品。它包装它们。上游服务器仍然负责提供商行为；米夫塔处理配置文件选择、机密注入、生命周期、路由、策略和编辑。
> **状态：** 米夫塔是实验性的，尚未达到1.0版本。接口和安全行为可能会在小版本号之间发生变化。请参阅[发布策略](CHANGELOG.md#release-policy)并使用[私有披露流程](SECURITY.md)进行漏洞报告。
## 安装
对于已发布的版本：
```bash
npm install -g @lubab/miftah
```
米夫塔默认在本地运行。它没有云依赖或遥测。
## 快速入门
生成一个安全的模板：
```bash
miftah init github --preset github --output ~/.config/miftah/github.json
```
编辑配置文件环境以引用 shell 变量，然后验证它：
```bash
export GITHUB_WORK_TOKEN='...'
miftah validate --config ~/.config/miftah/github.json
```
直接运行一个包装服务器：
```bash
miftah --config ~/.config/miftah/github.json
```
相同的过程可以在Claude Desktop中配置：
```json
{
"mcpServers": {
"github": {
"command": "miftah",
"args": ["--config", "/Users/me/.config/miftah/github.json"]
}
}
}
```
## 配置文件
配置文件是命名后的凭证环境。尽可能将机密值保存在JSON之外：
```json
{
"version": "1",
"name": "github",
"defaultProfile": "work",
"upstream": {
"transport": "stdio",
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server:v1.5.0"]
},
"profiles": {
"work": {
"description": "工作GitHub",
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_WORK_TOKEN}"
},
"policy": "safe-write"
},
"personal": {
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_TOKEN}"
},
"policy": "readonly"
}
},
"policies": {
"readonly": {
"allowRisk": ["read"],
"denyRisk": ["write", "destructive"]
},
"safe-write": {
"allowRisk": ["read", "write"],
"denyRisk": ["destructive"],
"requireConfirmation": ["write"]
}
},
"security": {
"allowPlaintextSecrets": false,
"allowProfileSwitchingFromMcp": true,
"requireExplicitProfileForDestructive": true
}
}
```
GitHub预设版本为`ghcr.io/github/github-mcp-server:v1.5.0`。要安全升级，请先阅读发行说明，更新配置文件中的标签，运行`miftah validate`，然后在推广之前测试配置文件和配置文件。
克劳德可以调用`miftah_list_profiles`、`miftah_current_profile`、`miftah_use_profile`、`miftah_profile_info`、`miftah_health`、`miftah_validate_config`、`miftah_list_upstream_tools`、`miftah_restart_profile`和`miftah_route_preview`。上游工具在不与保留的管理名称冲突的情况下保持不变。上游工具在不与保留的管理名称冲突的情况下保持不变。在配置文件更改、重启、上游故障或恢复更改公共功能表面后，MCP客户端将收到列表更改通知，并应在依赖缓存功能之前重新列出受影响的工具、资源或提示。
对于帐户包，定义`upstreams`而不是`upstream`。工具、资源名称和提示名称以`<upstream>__<name>`形式公开（例如`github__search_issues`和`github__account_prompt`），每个配置文件可以提供按上游环境或标头重写。多上游资源URI是Miftah拥有的路由，例如`miftah://resource/github?uri=account%3A%2F%2Fcurrent`；其编码值在公开之前被编辑，而Miftah仅在其配置文件路由映射中保留确切的原始URI。在公开多上游资源或提示URI元数据之前，Miftah剥离URI用户信息和片段，并编辑每个查询值。读取和提示获取仅通过确切的路由映射路由，绝不通过客户端标识符猜测。
多上游资源和提示列表使用不透明的、基于内存的Miftah游标，因此不会公开单个上游游标。在配置文件更改或重启后重新列出，而不是保留旧游标。标准`upstream`或单个条目`upstreams`映射保留无凭证的原始资源URI、提示名称和本地上游游标以确保兼容性；URI和图标字段在边界之前在结构上编辑了用户信息、查询值或片段。零条目包仍然省略资源和提示功能。
`tooling.toolDiscoveryMode`默认为`"permissive"`。在此模式下，捆绑列表仅返回健康的 upstream 贡献，删除失败 upstream 的路由，并在后续工具请求时重试不完整的工具发现。如果所有上游都失败了功能列表，Miftah 返回 `UPSTREAM_DISCOVERY_FAILED` 而不是宣传空上游表面。将其设置为 `"strict"` 以拒绝任何不可用的上游；严格的工具发现还检查每个配置的配置文件是否具有相同的客户端可见工具合同。`miftah_health` 报告配置文件、上游名称、整体和进程状态、转换时间、自动重启计数、编辑错误、故意停止原因、待恢复时间和每个启动上游的每个功能发现状态。参见 `examples/multi-upstream.miftah.json`。
## 远程上游
对于远程MCP服务器，使用`"streamable-http"`：
```json
{
"upstream": {
"transport": "streamable-http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${MCP_TOKEN}"
}
},
"profiles": {
"work": {
"headers": {
"authorization": "Bearer ${WORK_MCP_TOKEN}"
}
}
}
}
```
标头名称不区分大小写，并且配置文件标头始终替换同名的上游标头。Miftah需要HTTPS用于非环回远程URL；仅当本地开发端点位于`localhost`、`127.0.0.0/8`或`::1`时，HTTP才被接受。`"http"`传输是`"streamable-http"`的兼容别名。`"sse"`仍然可用于旧MCP服务器，但已弃用；请为新部署首选Streamable HTTP。
故意重启Streamable HTTP或包装器关闭会发送MCP会话DELETE请求，然后关闭本地客户端传输。服务器可能会拒绝DELETE，状态码为HTTP 405，在这种情况下，Miftah仍然关闭其本地会话，但远程服务器控制任何剩余的服务器端状态。如果DELETE在配置的关闭截止日期之前无法解决，Miftah中止本地传输，而不是让活动凭证会话持续。HTTP状态失败作为`UPSTREAM_HTTP_ERROR`返回，MCP JSON-RPC失败作为`UPSTREAM_PROTOCOL_ERROR`返回；响应正文和远程错误消息不会暴露给调用者。
Miftah使用SDK现有的60秒MCP请求超时，不添加第二个请求超时设置。启动和关闭保留配置的30秒和5秒默认值。SDK执行其有界的Streamable HTTP SSE重新连接行为；如果传输最终关闭，Miftah的`process.restartOnCrash`策略和有界`maxRestarts`预算控制配置文件恢复。
## 路由和安全
路由可以使用活动配置文件或规则匹配工具参数：
```json
{
"routing": {
"mode": "hybrid",
"fallback": "ask",
"rules": [
{
"name": "work-repository",
"when": { "args.repo": "my-org/work" },
"profile": "work"
}
]
}
}
```
当多个配置文件匹配时，Miftah拒绝猜测。使用显式配置文件切换进行写入和破坏性操作。相同的路由、策略、编辑和审计管道适用于上游工具调用、资源读取和提示检索。策略模式使用每个上游工具的原始名称表示工具、`resources/read`表示读取和`prompts/get`表示提示检索。在转发读取或提示请求之前，Miftah会返回拒绝、需要确认、阻止或模糊的决策。提供者令牌范围仍然很重要：本地策略不能使具有写入能力的提供者令牌变为只读。设置策略名称的配置文件必须引用`policies`中的现有条目，而没有`policy`字段的配置文件保持默认允许行为。
## 机密处理
支持的本地引用包括环境变量（`${NAME}`和`secretref:env://NAME}`）、配置的dotenv文件（`secretref:dotenv://NAME}`）和显式选择明文（`secretref:plain://...}`）。操作系统密钥库和外部机密CLI是保留的扩展点。机密从诊断、错误、stderr转发、审计条目和工具响应中编辑。
使用`miftah doctor`检查配置和上游准备情况，而不打印进程环境值。
## 审计日志
设置`audit.path`以记录每个支持的MCP操作的终端JSONL事件，包括发现、管理、工具、资源和提示请求。事件包括进程会话ID、请求/事件ID、源和选定的配置文件、上游、路由和策略元数据（如果适用）、终端结果、稳定错误代码和持续时间。包装器和上游生命周期转换分别记录。参数在`audit.includeArguments`为`true`时省略。
新的审计目录和文件在平台支持的情况下使用所有者专用权限创建。`audit.failureMode`默认为`"fail-closed"`，在调度前验证审计接收器，如果无法准备，则拒绝请求。终端写入仍可能在上游副作用完成后失败，因此将`AUDIT_WRITE_FAILED`视为不确定结果，不要盲目重试非幂等工具。仅当可用性优先于该保证时，将其设置为`"fail-open"`；原始操作保持可用，`miftah_health`报告编辑后的`AUDIT_WRITE_FAILED`审计健康条目。
## 命令行界面
使用`miftah --help`获取生成的命令列表，使用`miftah <command> --help`获取特定命令选项。可用命令如下：
| 命令 | 目的 |
| --- | --- |
| `miftah --config <file>` / `miftah serve --config <file>` | 运行STDIO MCP包装器。 |
| `miftah validate --config <file>` | 解析和验证JSON配置；写入JSON。 |
| `miftah doctor --config <file> [--json]` | 报告编辑后的配置和上游准备情况。 |
| `miftah init [name] [--name <name>] [--preset <name>] [--output <file>]` | 生成通用、GitHub或Sentry模板。 |
| `miftah schema` | 打印JSON模式。 |
| `miftah list-tools --config <file> [--profile <name>]` | 以JSON形式发现上游工具。 |
| `miftah test-profile --config <file> [--profile <name>]` | 启动并初始化一个配置文件；写入JSON。 |
| `miftah logs --config <file> [--follow]` | 读取规范的、编辑后的审计JSONL；安全地跟随旋转。 |
| `miftah --version` / `miftah -v` / `miftah version [--json]` | 打印软件包SemVer。 `--json`故意保留纯SemVer输出。 |
结构化成功输出以stdout写入，stderr为空。稳定的非零类别为用法（`2`）、配置（`3`）、机密解析（`4`）、上游（`5`）和策略（`6`）；`1`是一个无类别的操作失败。引用配置和输出路径时，请使用空格括起来。`logs --follow`处理追加、截断和旋转，并在`SIGINT`或`SIGTERM`时干净地退出，而不启动上游。请参阅完整的[CLI参考](docs/cli.md)以获取帮助行为、默认值、JSON合约、编辑和审计读取边界。
## 文档
- [架构](docs/architecture.md)
- [配置](docs/config.md)
- [安全](docs/security.md)
- [安全报告](SECURITY.md)
- [CLI](docs/cli.md)
- [库API](docs/library-api.md)
- [克劳德桌面](docs/claude-desktop.md)
- [GitHub示例](docs/examples/github.md)
- [Sentry示例](docs/examples/sentry.md)
- [变更日志和发布策略](CHANGELOG.md)
- [贡献](CONTRIBUTING.md)
## 当前边界
当前实验代码实现了本地STDIO和远程HTTP/SSE上游客户端、配置文件切换、混合路由规则、策略、账户包的命名工具/资源/提示、弹性健康上游发现、可配置的本地进程生命周期控制、内存进程/会话缓存、编辑后的JSONL审计日志和可打包的CLI。本地进程控制涵盖启动和关闭截止日期、可选的空闲清理、选择加入崩溃恢复和有界重试预算，以及无驱逐配置文件会话容量限制。持久状态、UI、路由插件、配置文件匹配器、`process.startMode`、`process.cache`和可配置的工具命名空间被拒绝，并返回`UNSUPPORTED_CONFIG_OPTION`而不是被静默忽略。
## 许可证
MIT
