内容
# Soma
`Soma` 是一个集成的 RMCP 服务器运行时和可执行二进制文件，旨在通过减少自定义 Rust 代码的使用，让新的代理功能能够轻松上线。它固化了每个服务器家族都在不断重发现的生产模式：一个紧凑的 MCP 工具、stdio 和可流式 HTTP 传输、CLI 对等性、直接 REST 路由、身份验证/OAuth、可观察性、插件打包、网页回退、Docker/运行时示例、生成的合约和发布自动化。
该存储库仍然可以为重命名的项目提供脚手架，但 Soma 现在是一个可直接使用的运行时。默认产品路径是在显式模式下运行 `soma`，将提供者文件放入 `providers/`（或将 `SOMA_PROVIDER_DIR` 指向其他位置），并让提供者注册表项目将这些功能映射到 MCP、CLI、REST、OpenAPI、Palette 摘要、生成的文档和插件元数据上。提供者清单还携带 MCP 原生的提示、资源、任务和诱导元数据，供注册表合约使用。脚手架是创建具有相同锁定运行时的新可分发存储库的路径。
**30 秒路径：** 安装 `soma` 二进制文件 -> `soma status` -> 从 MCP 客户端运行 `npx -y soma-rmcp mcp` -> 通过 `tools/call` 调用 `soma` MCP 工具，并传递 `{"action":"status"}`。
**状态：** 生产就绪的 RMCP 运行时。只有当提供者声明了写入能力的提供者操作才被允许，破坏性操作受到限制。
**不适用于：** 未经身份验证的公共网关、替换上游服务授权、任意不受信任的代码执行或单独的多租户安全边界。
## 目录
- [命名](#命名)
- [功能和边界](#功能和边界)
- [安装](#安装)
- [快速入门](#快速入门)
- [客户端配置](#客户端配置)
- [运行时表面](#运行时表面)
- [MCP 工具参考](#mcp-工具参考)
- [CLI 参考](#cli-参考)
- [配置](#配置)
- [身份验证](#身份验证)
- [安全性和信任模型](#安全性和信任模型)
- [架构](#架构)
- [分发合约](#分发合约)
- [开发](#开发)
- [验证](#验证)
- [部署](#部署)
- [故障排除](#故障排除)
- [相关服务器](#相关服务器)
- [文档](#文档)
- [许可证](#许可证)
## 命名
Soma 首先是一个运行时产品，其次是一个模板/导出源。生成的项目在脚手架后处理期间会替换这些名称，但已发布的 `soma` 命令是产品行为的真实来源。
| 表面 | Soma 值 | 生成项目模式 |
|---|---|---|
| 存储库 | `jmagar/soma` | `<service>-rmcp` 或文档中规定的产品例外 |
| Rust crate/package | `soma` | 服务特定的 crate 名称 |
| 规范二进制文件 | `soma` | 通常是 `r<service>` 或产品名称 |
| npm 包 | `soma-rmcp` | `<service>-rmcp` |
| MCP 工具 | `soma` | 通常是 `<service>` |
| 环境前缀 | `SOMA_*` | 生成的服务前缀 |
## 功能和边界
| 路径 | 使用场景 | 您需要编写 | 运行时提供 |
|---|---|---|---|
| 插件提供者 | 您可以用清单、脚本、WASM 模块、OpenAPI 操作或上游 MCP 调用描述功能。 | `providers/` 下的文件，包含工具、提示、资源、环境需求、功能授予和表面覆盖层。 | MCP 工具调度、动态 CLI 命令、直接 REST 路由、模式验证、身份验证策略、刷新、OpenAPI/Palette 摘要、生成文档和插件元数据。 |
| 静态 Rust 提供者 | 功能需要本地 Rust、紧密集成或可重用 crate。 | 在提供者注册表中注册的 Rust 提供者/操作。 | 与表面重写相同的 MCP/CLI/REST/docs/插件投影。 |
| 脚手架产品 | 您需要一个重命名的存储库、包标识、端口、插件、Docker 标签和发布元数据。 | `scaffold_intent` 载荷或 `cargo xtask scaffold` 选项。 | 编译产品存储库、脚手架报告、cargo-generate 后处理和脚手架/导出验证检查。 |
| 自定义配置文件 | 您需要一个更小的二进制文件或部署形状。 | Cargo 功能选择。 | `local-adapter`、`server` 和 `full` 配置文件后面的相同运行时 crate。 |
## 内置功能
- 一个紧凑的 MCP 服务工具 (`soma`)，具有 `action` 调度，因此即使提供者目录增长，代理工具列表也保持较小。
- 一个规范的二进制文件：`soma`，具有明确的 `serve`、`mcp` 和 CLI 模式，用于 REST API、可流式 HTTP MCP、stdio MCP、选定网页 UI 和本地操作。
- 从 `.json`、`.ts`、`.py`、`.wasm` 和 `.md` 文件动态加载提供者，以及本地 Rust 提供者和上游 MCP/OpenAPI 提供者种类。支持结构化的 `providers/{tools,prompts,resources}/` 布局，以及路径派生的 MCP 资源（静态文件和动态 `.ts` 读取器），具有路径遍历信任边界。
- 用于工具、提示、资源、任务、诱导表单、环境需求、功能授予和表面覆盖层的提供者清单合约。
- 共享验证、破坏性操作确认、身份验证/范围强制、响应限制、编辑、日志记录、指标、生成的 OpenAPI、生成的提供者表面文档、插件清单、设置、医生和发布工具。
Soma 拥有运行时投影、验证、身份验证策略、打包、生成的元数据和脚手架自动化。提供者代码拥有服务特定的行为和凭证。上游服务拥有自己的授权和数据模型。Soma 故意拒绝将凭证作为工具调用输入的一部分，并且不将提供者清单转变为不受限制的远程执行边界。
## 安装
当 MCP 客户端期望 `npx` 命令时，请使用 npm 启动器。该包是 Rust 二进制文件的启动器；首先安装 `soma` 或将其绝对路径设置为 `SOMA_BIN`。
```bash
npx -y soma-rmcp mcp
```
在开发存储库时使用 Cargo：
```bash
cargo run --bin soma -- mcp
cargo run --bin soma -- serve
```
发布构建会发布 GitHub Release 二进制文件、Docker/OCI 元数据、`soma-rmcp` npm 启动器、MCP 注册表元数据和插件包文件，均来自同一发布组件。
## 产品配置文件
选择您想要的表面积，无需更改提供者编写模型。
| 目标 | 最适合 | 默认配置文件 | 包括 |
|---|---|---|---|
| 本地代理适配器 | 薄包装在已丢弃的提供者或上游 API 上 | `local-adapter` | CLI + stdio MCP 在一个本地二进制文件中。默认情况下没有 REST/Web 镜像。 |
| 共享 API/MCP 服务器 | 多个客户端或网关使用的服务 | `server` | CLI + REST API + 可流式 HTTP MCP + stdio MCP + 健康/状态路由 + 身份验证能力运行时。 |
| 完整应用平台 | 应用程序拥有状态、作业、仪表板、工作流或人类界面 | `full` | `server` 加嵌入式网页 UI、OAuth、可观察性和插件支持。 |
| 仅 CLI 或自定义本地工具 | 脚本、操作实用程序、单机工具 | 自定义功能集，通常从 `cli` 开始 | CLI 解析器和共享服务层。打包的本地二进制文件使用 `local-adapter`，因此仅 CLI 产品可能会修剪 MCP 或调整二进制文件功能门。 |
当您需要自定义形状时，可以使用较低级别的 Cargo 功能：
| 功能 | 目的 |
|---|---|
| `cli` | CLI 壳和命令解析。 |
| `mcp` | MCP 工具、模式、资源、提示和范围层。 |
| `mcp-stdio` | 本地 stdio MCP 传输。 |
| `api` | REST 处理程序和 OpenAPI 支持的业务路由。 |
| `auth` | 共享身份验证策略和持有者令牌强制执行。 |
| `oauth` | Google、Authelia 和 GitHub OAuth/OIDC 以及在 `auth` 之上的 JWT 发布。 |
| `mcp-http` | 在 Axum 中安装的可流式 HTTP MCP。 |
| `web` | 嵌入式静态网页 UI 回退。 |
| `observability` | 指标/跟踪钩子。 |
| `plugin` | 插件设置/支持帮助程序。 |
| `local-adapter` | 精简本地二进制文件：`cli` + `mcp-stdio`。 |
| `server` | 可部署的 HTTP 运行时配置文件：`cli` + `api` + HTTP MCP + stdio MCP。 |
| `full` | 完整平台配置文件：本地适配器、服务器、网页、OAuth、可观察性和插件支持。 |
## 快速入门
直接运行产品：
```bash
git clone https://github.com/jmagar/soma
cd soma
# 完整平台模式：REST API + HTTP MCP + 网页回退到 :40060
cargo run --bin soma -- serve
# 本地二进制文件：stdio MCP
cargo run --bin soma -- mcp
# 本地二进制文件：CLI
cargo run --bin soma -- greet --name Alice
```
有用的烟雾检查：
```bash
curl http://localhost:40060/health
cargo run --bin soma -- status
cargo run --bin soma -- doctor
```
直接调用 MCP 端点：
```bash
curl -s -X POST http://localhost:40060/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"soma","arguments":{"action":"greet","name":"Alice"}}}'
```
## 插入提供者
新的服务器的最快路径是优先使用提供者。添加提供者清单或模块到 `providers/`，然后运行相同的二进制文件。在提供者目录应该位于工作目录之外时使用 `SOMA_PROVIDER_DIR`。
```bash
mkdir -p providers
cat > providers/hello-local.json <<'JSON'
{
"schema_version": 1,
"provider": {
"name": "hello-local",
"kind": "static-rust",
"title": "Hello Local"
},
"tools": [
{
"name": "hello_local",
"description": "Return a deterministic hello payload from a dropped provider.",
"input_schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": { "type": "string" }
}
},
"cli": {
"enabled": true,
"command": "hello-local"
},
"rest": {
"enabled": true,
"method": "POST",
"path": "/v1/hello-local"
},
"meta": {
"result": {
"message": "hello from a dropped provider"
}
}
}
]
}
JSON
```
通过动态 CLI 表面调用它：
```bash
cargo run --bin soma -- hello-local --name Alice
```
运行服务器并通过 REST 和 MCP 调用相同的提供者：
```bash
cargo run --bin soma -- serve
curl -s -X POST http://localhost:40060/v1/hello-local \
-H "Content-Type: application/json" \
-d '{"name":"Alice"}'
curl -s -X POST http://localhost:40060/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"soma","arguments":{"action":"hello_local","name":"Alice"}}}'
```
纯 Python 函数也可以直接放入 `providers/`：
```python
PROVIDER = {"name": "math-tools", "kind": "python"}
def add(a: int, b: int) -> int:
"""Add two integers."""
return a + b
```
当 `TOOLS` 消失时，模块中定义的公共函数成为工具。支持同步和异步函数，常见的 Python 类型注释被转换为输入模式。
Python 提供者文件是受信任的代码。Soma 在提供者目录刷新期间导入它们以发现工具，然后在具有清除环境的子进程中执行工具调用，并仅具有已声明的提供者/工具环境值。目录导入不接收提供者环境；在工具函数内部读取机密，而不是在模块导入时。
提供者清单可以声明：
- 默认情况下通过 MCP 暴露的工具/操作，以及当其覆盖层选择加入时通过 CLI/REST
- MCP 原生的提示、资源、任务和诱导元数据，供提供者注册表合约使用
- 所需环境变量和编辑规则
- 文件系统、网络、浏览器、终端、GitHub 和环境功能授予
- 限制、破坏性操作元数据、示例、生成文档、插件和 UI 元数据
支持的提供者类型有 `static-rust`、`openapi`、`ai-sdk`、`wasm`、`mcp`、`python`、`langchain` 和 `llamaindex`。参见 [docs/specs/dynamic-provider-runtime.md](docs/specs/dynamic-provider-runtime.md)、[docs/contracts/provider-manifest.schema.json](docs/contracts/provider-manifest.schema.json) 和 [docs/generated/provider-surfaces.md](docs/generated/provider-surfaces.md)。
## 脚手架新项目
当提供者优先的路径需要成为具有自己的 crate 名称、二进制文件名称、端口、插件包、Docker 元数据、发布元数据和文档的新存储库时，请使用 `cargo xtask scaffold`。它可以计划而无需触及文件，使用 `cargo-generate` 加上 Rust 后处理器，写入 `docs/scaffold-report.md`，并验证生成的导出形状。
从服务名称计划：
```bash
cargo xtask scaffold --name myservice --category upstream-client --port auto --plan
```
从 MCP `scaffold_intent` JSON 计划：
```bash
cargo xtask scaffold --intent scaffold-intent.json --plan
```
生成到输出父目录：
```bash
cargo xtask scaffold --intent scaffold-intent.json --apply ../generated
```
验证现有生成的项目：
```bash
cargo xtask scaffold --verify ../generated/myservice-mcp
```
打印适用于生成的存根的路径感知后续计划：
```bash
cargo xtask scaffold --adapt-plan ../generated/myservice-mcp
```
从操作清单中物化启动器工件：
```bash
cargo xtask scaffold \
--write-action-starters ../generated/myservice-mcp \
--actions actions.json
```
添加启动操作片段：
```bash
cargo xtask scaffold \
--intent scaffold-intent.json \
--actions actions.json \
--plan
```
操作清单示例：
```json
{
"actions": [
{
"name": "list_things",
"description": "List visible things.",
"scope": "read",
"params": [
{ "name": "kind", "type": "string", "required": false }
]
}
]
}
```
使用：
- `--category upstream-client` 用于围绕现有 API 的精简本地适配器。
- `--category application-platform` 用于 API + CLI + MCP + 网页默认值。
- `--no-cargo-check` 仅在需要快速静态验证时使用。
参见 [docs/SCAFFOLD.md](docs/SCAFFOLD.md)、[docs/CARGO_GENERATE.md](docs/CARGO_GENERATE.md) 和 [docs/contracts/scaffold-intent.schema.json](docs/contracts/scaffold-intent.schema.json) 以获取完整的脚手架合约。
## 架构
运行时将产品行为置于提供者注册表之后。每个外部表面都是一个薄的解析器/格式化器，围绕相同的提供者快照和服务运行时，因此丢弃提供者不需要手动编辑 MCP、CLI、REST、OpenAPI、插件或文档代码。
```text
ProviderRegistry
crates/soma/application/src/provider_registry.rs
验证提供者清单，计算快照/指纹，索引工具、提示、资源、CLI 命令、REST 路由和 MCP 原语。
提供者来源
crates/soma/application/src/providers/
静态 Rust、文件支持的 JSON 清单、TypeScript AI SDK 边车、Python LangChain/LlamaIndex 边车、WASM、OpenAPI 支持的提供者和上游 MCP 提供者。
SomaService
crates/soma/application/src/service.rs
静态 Rust 提供者使用的内置产品/服务逻辑。
传输壳
crates/soma/cli/src/lib.rs CLI 解析器和输出格式化。
crates/soma/mcp/src/tools.rs MCP JSON 参数到服务调用。
crates/soma/api/src/api.rs REST 提取器到服务调用。
apps/soma/src/routes.rs Axum 路由器、身份验证、MCP、API、网页回退。
内置操作元数据
crates/soma/domain/src/actions.rs
原生操作元数据、验证、缓存目录/帮助和原生调度。
```
薄壳规则很严格：
1. 在表面上解析输入。
2. 调用提供者注册表或服务运行时。
3. 返回或打印结果。
不要在 CLI、MCP、REST 处理程序或 `main.rs` 中放置业务规则。
## 运行时表面
规范的二进制文件可以从一个可执行文件中运行整个应用程序：
```bash
soma serve # HTTP 服务器：REST API + 可流式 HTTP MCP + 网页回退
soma mcp # stdio MCP 传输
soma status # 通过相同二进制文件的 CLI 命令
```
本地适配器模式针对插件/本地使用进行了优化：
```bash
soma mcp # stdio MCP 传输
soma greet --name Alice # CLI 命令
soma doctor # 操作员预飞行检查
soma watch # 轮询 /health 并发出状态变化
soma setup check # 插件/应用数据设置检查
```
每个显式运行时模式都加载提供者注册表。文件提供者默认到 `./providers`，可以通过 `SOMA_PROVIDER_DIR` 移动。CLI 启动、MCP 调度和动态 REST 路由在执行前刷新文件提供者，然后强制执行活动提供者快照的模式、表面、范围、功能和破坏性操作规则。
服务器配置文件中的 HTTP 路由：
| 路径 | 目的 |
|---|---|
| `/mcp` | 可流式 HTTP MCP 传输。 |
| `/health` | 无身份验证的活动检查。 |
| `/readyz` | 就绪检查。 |
| `/status` | 公开的裁剪运行时状态。 |
| `/openapi.json` | 生成的 REST OpenAPI 模式。 |
| `/metrics` | 带有 `observability` 的 Prometheus 指标。 |
| `/v1/capabilities` | REST 路由清单。 |
| `/v1/greet`，`/v1/echo`，`/v1/status`，`/v1/help` | 直接 REST 业务路由。 |
| `/v1/tools/{action}` | 丢弃提供者的工具的通用 REST 执行路由。 |
| `/v1/{provider-route}` | 提供者声明的可选 REST 路由，当工具提供自定义 REST 覆盖层时。 |
| `/mcp/.well-known/*` | 启用 OAuth 时的 OAuth 元数据。 |
| `/*` | 带有 `web` 的嵌入式网页 UI 回退。 |
REST 仅限直接路由：没有 `/v1/soma` 操作信封。MCP 保留一个 `soma` 工具，并带有 `action` 参数。
## MCP 工具参考
运行时暴露了一个紧凑的 MCP 工具，`soma`，带有 `action` 参数。
内置动作和已删除的提供程序工具共享相同的调度路径。
这保持了 MCP 发现的简洁，同时允许提供程序目录在单个工具后面增长。
<!-- BEGIN GENERATED README_ACTION_TABLE -->
<!-- Generated by scripts/generate-docs.py; do not edit by hand. -->
| 动作 | 范围 | 成本 | 传输 | REST 路由 | CLI | 参数 | 描述 |
|---|---|---|---|---|---|---|---|
| `greet` | `soma:read` | `cheap` | MCP + CLI + REST | `POST /v1/greet` | `soma greet [--name N]` | `name` (可选字符串) | 返回问候。 |
| `echo` | `soma:read` | `cheap` | MCP + CLI + REST | `POST /v1/echo` | `soma echo --message <msg>` | `message` (必填字符串) | 回声消息不变。 |
| `status` | `soma:read` | `cheap` | MCP + CLI + REST | `GET /v1/status` | `soma status` | 无 | 返回服务器状态和配置信息。 |
| `elicit_name` | `soma:read` | `cheap` | 仅 MCP | - | `_MCP-only_` | 无 | 请求 MCP 客户端收集名称，然后返回个性化问候。 |
| `scaffold_intent` | `soma:read` | `moderate` | 仅 MCP | - | `_MCP-only_` | 无 | 通过 MCP 诱导收集脚手架设置意图，并返回脚手架项目技能的 JSON。 |
| `help` | 公共 | `cheap` | MCP + CLI + REST | `GET /v1/help` | `soma --help` | 无 | 显示动作参考。 |
<!-- END GENERATED README_ACTION_TABLE -->
内置业务动作保持 MCP + CLI + REST 一致性，除非由于协议原因无法实现。
`elicit_name` 和 `scaffold_intent` 是仅 MCP 的，因为它们依赖于 MCP 诱导。
`serve`、`mcp`、`doctor`、`watch`、`setup` 和 `package` 是 CLI 操作命令，而不是业务动作。
已删除的提供程序工具默认启用 MCP，并通过 `POST /v1/tools/{action}` 可执行，除非工具显式设置 `rest.enabled=false`。
`rest` 叠加层可以添加自定义路由、方法和 OpenAPI 元数据；通用路由保持为 web/adapter 安全执行形状。
CLI 暴露通过每个工具的 `cli` 叠加层选择加入。
提供程序提示、资源、任务和诱导表单是提供程序清单合同和注册表索引的一部分；它们默认不会镜像到 CLI 或 REST。
## CLI 参考
`soma` 二进制文件通过与 MCP 使用的相同注册表快照公开操作命令和提供程序支持的动作：
```bash
soma greet --name Alice
soma echo --message hello
soma status
soma help
soma providers validate
soma providers inspect
soma providers test status
soma providers list --dir ./examples/providers
soma providers lint --dir ./examples/providers
soma providers status --dir ./examples/providers
soma doctor
soma setup check
soma package generate --check
```
提供程序工具通过 `cli` 叠加层选择加入 CLI 暴露。
动态 CLI 标志源自提供程序输入模式，因此生成的提供程序目录仍然是当前动作形状的真实来源。
## 安全和信任模型
MCP 调用者永远不会在工具参数中提供 API 密钥、OAuth 机密、承载令牌、密码或其他凭证。
凭证存储在环境变量、配置文件、appdata 或上游提供程序运行时中。
提供程序清单在调度前会进行验证。
注册表强制执行表面选择加入、JSON 模式输入验证、身份验证范围、声明的主机功能、破坏性动作确认、响应大小限制和结构化提供程序错误。
Python、LangChain、LlamaIndex 和 TypeScript 提供程序文件被信任为本地代码；WASM 提供程序通过沙箱化的 WASM 提供程序路径运行；OpenAPI 和 MCP 提供程序将信任委托给其配置的上游服务。
## 身份验证
HTTP 服务器支持四种身份验证策略：
| 策略 | 何时 | 效果 |
|---|---|---|
| 回环开发 | 回环绑定，或在回环上设置 `SOMA_MCP_NO_AUTH=true` | 无身份验证中间件，无范围检查。 |
| 承载令牌 | 设置 `SOMA_MCP_TOKEN` | `/mcp` 和 `/v1/*` 需要 `Authorization: Bearer <token>`。 |
| OAuth | 设置 `SOMA_MCP_AUTH_MODE=oauth` 并至少配置一个提供程序 | 基于浏览器的 Google、Authelia 或 GitHub 登录问题 JWT 承载令牌。 |
| 受信任网关 | 在非回环上设置 `SOMA_NOAUTH=true` | 本地身份验证和范围检查禁用，因为上游网关负责。 |
启动守护进程拒绝非回环的无身份验证绑定，除非配置了承载、OAuth 或受信任网关模式。
`/health`、`/readyz`、`/status` 和 `/openapi.json` 由于设计原因而公开，仅返回安全的运行时元数据。
参见 [docs/AUTH.md](docs/AUTH.md) 获取详细的身份验证模型。
## 配置
值从 `config.toml`、本地应用数据文件和环境变量加载；显式环境变量优先。
内置的离线提供程序无需真实凭证即可工作，但生成的项目应将其真实的上游/平台凭证标记为必填。
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `SOMA_API_URL` | 否 | 空 | 已部署的平台 API 或上游服务 URL。空值选择存根/离线行为。 |
| `SOMA_API_KEY` | 否 | 空 | 承载令牌或上游服务 API 密钥。 |
| `SOMA_PROVIDER_DIR` | 否 | `providers` | 扫描提供程序文件的目录。相对路径从当前工作目录解析。 |
| `SOMA_MCP_HOST` | 否 | `127.0.0.1` | HTTP 服务器绑定主机。 |
| `SOMA_MCP_PORT` | 否 | `40060` | HTTP 服务器绑定端口。 |
| `SOMA_MCP_SERVER_NAME` | 否 | `soma` | 向客户端通告的 MCP 服务器名称。 |
| `SOMA_MCP_NO_AUTH` | 否 | `false` | 禁用回环开发的身份验证。 |
| `SOMA_NOAUTH` | 否 | `false` | 受信任网关的非回环无身份验证模式。 |
| `SOMA_MCP_TOKEN` | 承载 | 空 | 静态承载令牌。 |
| `SOMA_MCP_ALLOWED_HOSTS` | 否 | 空 | 额外的逗号分隔主机头值。 |
| `SOMA_MCP_ALLOWED_ORIGINS` | 否 | 空 | 额外的逗号分隔 CORS 来源。 |
| `SOMA_MCP_TRACE_HEADERS` | 否 | `off` | 受信任的入站 HTTP 跟踪提取：`off`、`trusted` 或 `trusted-with-baggage`。 |
| `SOMA_MCP_AUTH_MODE` | 否 | `bearer` | `bearer` 或 `oauth`。 |
| `SOMA_MCP_PUBLIC_URL` | OAuth | 空 | OAuth 元数据和回调的公共 URL。 |
| `SOMA_MCP_GOOGLE_CLIENT_ID` | OAuth | 空 | Google OAuth 客户端 ID。 |
| `SOMA_MCP_GOOGLE_CLIENT_SECRET` | OAuth | 空 | Google OAuth 客户端密钥。 |
| `SOMA_MCP_AUTHELIA_ISSUER_URL` | Authelia | 空 | HTTPS Authelia OIDC 发行者 URL。 |
| `SOMA_MCP_AUTHELIA_CLIENT_ID` | Authelia | 空 | Authelia OIDC 客户端 ID。 |
| `SOMA_MCP_AUTHELIA_CLIENT_SECRET` | Authelia | 空 | Authelia OIDC 客户端密钥。 |
| `SOMA_MCP_GITHUB_CLIENT_ID` | GitHub | 空 | GitHub OAuth 应用客户端 ID。 |
| `SOMA_MCP_GITHUB_CLIENT_SECRET` | GitHub | 空 | GitHub OAuth 应用客户端密钥。 |
| `SOMA_MCP_AUTH_DEFAULT_PROVIDER` | 否 | 优先 | 请求省略 `provider` 时使用的提供程序；自动优先级为 Google、Authelia、GitHub。 |
| `SOMA_MCP_AUTH_ADMIN_EMAIL` | OAuth | 空 | 初始/管理员 OAuth 电子邮件。 |
| `RUST_LOG` | 否 | `info` | 日志过滤器。Stdio 模式抑制嘈杂的日志，以避免破坏 JSON-RPC。 |
保持 `SOMA_MCP_TRACE_HEADERS=off` 除非服务器绑定到回环或受信任的网关剥离或覆盖来自不受信任的客户端的跟踪头。
单独的承载/OAuth 身份验证不是信任边界。
参见 [docs/TRACE_CONTEXT.md](docs/TRACE_CONTEXT.md) 获取完整的仅入站跟踪头合约。
示例：
- [.env.example](.env.example) 用于机密、URL 和运行时环境。
- [config.soma.toml](config.soma.toml) 用于非机密默认值。
提供程序回调路径默认为 `/auth/google/callback`、`/auth/authelia/callback` 和 `/auth/github/callback`；回调和范围覆盖在 [docs/ENV.md](docs/ENV.md) 中列出。
GitHub OAuth 应用不提供上游刷新令牌，因此 GitHub 身份验证的会话不接收本地刷新令牌，必须在其访问令牌过期后再次登录。
参见 [docs/AUTH.md](docs/AUTH.md) 获取提供程序选择和安全详细信息。
## 开发
```bash
# 构建配置文件
cargo build --bin soma --no-default-features --features local-adapter
cargo build --bin soma --no-default-features --features server
cargo build --bin soma --features full
# 运行检查
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo nextest run
cargo xtask contract-audit
cargo xtask generate-provider-surfaces --check
# 常用 just 配方
just dev # 回环 HTTP 服务器，本地无身份验证
just mcp # stdio MCP
just greet # CLI 烟雾测试
just doctor # 预飞行检查
just build-local # 本地适配器二进制文件
just build-full # web 资产 + 完整平台二进制文件
just verify # fmt、lint、检查、测试
just check-docs # 生成的文档/元数据当前
just scaffold-contract-check
just validate-plugin
```
`cargo xtask ci` 运行主要的本地 CI 序列。
安装后使用可选工具，如 `cargo-nextest`、`taplo` 和 `cargo-audit`。
## 客户端配置
可流式 HTTP：
```json
{
"mcpServers": {
"soma": {
"url": "http://localhost:40060/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
```
Stdio：
```json
{
"mcpServers": {
"soma": {
"command": "/path/to/soma",
"args": ["mcp"],
"env": {
"SOMA_API_URL": "https://api.example.com",
"SOMA_API_KEY": "YOUR_API_KEY",
"RUST_LOG": "warn"
}
}
}
}
```
对于生成的项目，请将 `soma`、`SOMA_*`、工具名称、范围和路径替换为生成的服务名称。
## 插件曲面
存储库提供了一个共享的 Soma 插件包，位于 [plugins/soma](plugins/soma) 下，用于 Claude Code、Codex 和 Gemini 曲面。
插件清单是无版本的；发布工具从 git 状态导出版本标识。
插件包可以使用本地 stdio 适配器，并包括用于 appdata 和环境文件的设置/医生支持。
主要文档：
- [docs/PLUGINS.md](docs/PLUGINS.md)
- [plugins/soma/.codex-plugin/README.md](plugins/soma/.codex-plugin/README.md)
- [plugins/soma/skills/soma/SKILL.md](plugins/soma/skills/soma/SKILL.md)
- [plugins/soma/skills/scaffold-project/SKILL.md](plugins/soma/skills/scaffold-project/SKILL.md)
## 分发合约
`soma` 发布组件在 [release/components.toml](release/components.toml) 中定义。
版本化工件必须在 Rust 包、`Cargo.lock`、`server.json`、npm 包、生成的 OpenAPI 元数据、OCI 镜像标识符和更改日志中保持一致。
插件清单保持无版本。
市场和插件发布标识从 git/package 元数据导出，而 `server.json` 和生成的提供程序曲面文档描述了当前已发布的运行时曲面。
在发布发布元数据之前运行 `cargo xtask check-version-sync`、`cargo xtask generate-provider-surfaces --check` 和 `cargo xtask check-docs`。
## Web UI
`web` 功能提供由 `soma-web` 捆绑的静态导出。
可编辑的前端源代码位于 [apps/web](apps/web) 中，`cargo xtask sync-web-source` 将源代码复制到 Rust crate 捆绑中。
有用命令：
```bash
cargo xtask build-web
cargo xtask sync-web-source
cargo xtask check-web-source-sync
pnpm -C apps/web validate
```
不 需要人类 UI 的生成项目应使用 `local-adapter`、`server` 或自定义功能集而无需 `web`。
## 部署
完整平台配置文件设计为一个可部署的 `soma` 二进制文件。
存储库还包括 Docker 和 Compose 示例：
- [config/Dockerfile](config/Dockerfile)
- [docker-compose.prod.yml](docker-compose.prod.yml)
- [entrypoint.sh](entrypoint.sh)
在适配生成的项目时，请验证规范的二进制名称、暴露的端口、健康检查端口、镜像标签、服务用户/组、数据卷和所需的环境变量。
脚手架验证器捕获了几个仅限脚手架的工件，但部署文件在发布镜像之前仍需要特定于服务的审查。
## 何时不使用即插即用提供程序
大多数新功能应从提供程序文件开始。
当需要可重用的 crate 边界、更丰富的服务状态、自定义客户端、后台作业、专用包标识或手动调整的传输行为时，请选择原生 Rust 或脚手架产品。
对于生成的产品，首先打印配置文件感知的检查清单：
```bash
cargo xtask scaffold --adapt-plan ../generated/myservice-mcp
```
然后为重复的动作线路生成可审查的启动器工件：
```bash
cargo xtask scaffold \
--write-action-starters ../generated/myservice-mcp \
--actions actions.json
```
这会在生成的项目中写入 `docs/action-starters/`，其中包含动作元数据、MCP 调度、CLI 变体、服务存根和测试覆盖的片段。
1. 仅当提供程序文件路径不够时，请替换 `crates/soma/client/src/client.rs` 中的存根客户端。
2. 将域逻辑放在 `crates/soma/application/src/service.rs` 或聚焦的服务模块中。
3. 注册原生提供程序/动作元数据，以便 MCP、CLI、REST、文档和插件保持注册表驱动。
4. 重新生成 MCP 模式文档、提供程序曲面文档和 OpenAPI，以便生成的曲面反映提供程序注册表。
5. 仅为基础设施路由添加 REST 处理程序；业务动作应保持注册表支持的直接路由。
6. 更新 `crates/soma/config/src/config.rs` 中的配置字段和环境前缀。
7. 更新 `.env.example`、`config.soma.toml`、插件选项和设置映射。
8. 更新 `server.json`、插件元数据、存储库 URL、Docker 标签和发布元数据。
9. 为 MCP 调度、CLI 解析、REST 路由、提供程序加载和服务行为添加测试。
10. 对于生成的/导出的项目，运行脚手架验证加上项目的本地质量门控。
对于公共存储库，还要审查跟踪的文档、生成的元数据、CI 运行器配置和机密扫描允许列表，然后再发布。
## 故障排除
- `soma doctor` 检查本地配置、appdata 和连接性。
- `soma providers validate` 确认提供程序清单和编译的模式与*已加载、运行的*注册表一致。
- `soma providers inspect` 显示提供程序曲面、能力姿态和生成的动作库存。
- `soma providers list|lint|status` 检查磁盘上的即插即用提供程序文件，而不加载注册表或执行任何处理程序 - 在运行时触摸 TS/WASM/MCP/OpenAPI 提供程序之前是安全的。
- Stdio 模式保持日志安静，以免破坏 JSON-RPC；使用 HTTP 模式或文件日志时进行嘈杂的启动故障调查。
- 如果生成的文档漂移，请运行 `cargo xtask generate-provider-surfaces --write` 然后重新运行 `--check` 命令。
## 相关服务器
- [unifi-rmcp](https://github.com/jmagar/unifi-rmcp) - UniFi 控制器 REST API 桥。
- [tailscale-rmcp](https://github.com/jmagar/tailscale-rmcp) - Tailscale 设备、用户和尾网操作的 API 桥。
- [unraid-rmcp](https://github.com/jmagar/unraid-rmcp) - Unraid GraphQL 桥，用于 NAS 和服务器管理。
- [apprise-rmcp](https://github.com/jmagar/apprise-rmcp) - Apprise 通知分发桥，用于许多投递后端。
- [gotify-rmcp](https://github.com/jmagar/gotify-rmcp) - Gotify 发送、消息、应用和客户端的推送通知桥。
- [arcane-rmcp](https://github.com/jmagar/arcane-rmcp) - Arcane Docker 管理桥，用于容器和相关资源。
- [yarr](https://github.com/jmagar/yarr) - 媒体栈桥，用于 Sonarr、Radarr、Prowlarr、Plex 和相关服务。
- [ytdl-rmcp](https://github.com/jmagar/ytdl-rmcp) - 媒体下载和工作流服务器。
- [synapse-rmcp](https://github.com/jmagar/synapse-rmcp) - 本地 Synapse 工作流服务器，用于侦察和通量动作。
- [cortex](https://github.com/jmagar/cortex) - Syslog 和家庭实验室日志聚合 MCP 服务器。
- [axon](https://github.com/jmagar/axon) - RAG、爬取、抓取、提取和语义搜索项目。
- [labby](https://github.com/jmagar/labby) - 家庭实验室控制平面和 MCP 网关项目。
- [lumen](https://github.com/jmagar/lumen) - 本地语义代码搜索 MCP 服务器。
## 文档
| 主题 | 文档 |
|---|---|
| 架构和分层 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)，[docs/PATTERNS.md](docs/PATTERNS.md) |
| 动态提供程序运行时 | [docs/specs/dynamic-provider-runtime.md](docs/specs/dynamic-provider-runtime.md)，[docs/generated/provider-surfaces.md](docs/generated/provider-surfaces.md) |
| 提供程序清单合约 | [docs/contracts/provider-manifest.schema.json](docs/contracts/provider-manifest.schema.json)，[docs/contracts/examples/provider-manifests](docs/contracts/examples/provider-manifests) |
| 脚手架工作流 | [docs/SCAFFOLD.md](docs/SCAFFOLD.md)，[docs/CARGO_GENERATE.md](docs/CARGO_GENERATE.md) |
| 脚手架意图合约 | [docs/specs/scaffold-intent-handoff.md](docs/specs/scaffold-intent-handoff.md)，[docs/contracts/scaffold-intent.schema.json](docs/contracts/scaffold-intent.schema.json) |
| MCP 动作模式 | [docs/MCP_SCHEMA.md](docs/MCP_SCHEMA.md) |
| REST OpenAPI | [docs/generated/openapi.json](docs/generated/openapi.json) |
| 身份验证 | [docs/AUTH.md](docs/AUTH.md) |
| 插件 | [docs/PLUGINS.md](docs/PLUGINS.md) |
| 发布/版本控制 | [release/components.toml](release/components.toml)，[docs/MCP-REGISTRY-PUBLISH-GUIDE.md](docs/MCP-REGISTRY-PUBLISH-GUIDE.md) |
| 自动化 | [xtask/README.md](xtask/README.md)，[scripts/README.md](scripts/README.md) |
| 测试 | [apps/soma/tests/README.md](apps/soma/tests/README.md) |
## 验证
产品运行时验证：
```bash
cargo xtask check-docs
cargo xtask generate-provider-surfaces --check
cargo xtask check-schema-docs --check
cargo xtask check-openapi --check
cargo xtask validate-plugin-layout
cargo xtask check-version-sync
just verify
```
脚手架/模板验证是一条单独的路径。当变更影响到脚手架合约、cargo-generate 后处理或生成项目输出时运行它们：
```bash
cargo xtask check-scaffold-intent-contract
cargo xtask scaffold --verify ../generated/myservice-mcp
cargo xtask check-cargo-generate
```
在迭代过程中使用有针对性的验证，然后在发布前运行更广泛的产品和受影响的脚手架验证。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器