内容
# 索玛
`索玛` 是一个集成的 RMCP 服务器运行时和二进制文件，用于以最少的自定义 Rust 代码上线新的代理功能。它锁定了每个服务器家族都在重新发现的生产模式：一个紧凑的 MCP 工具、标准输入输出和流式 HTTP 传输、CLI 对齐、直接 REST 路由、身份验证/OAuth、可观察性、插件打包、网页回退、Docker/运行时示例、生成的合约和发布自动化。
该仓库仍然可以为一个重命名的项目提供脚手架，但现在 `索玛` 是一个发布的运行时。首先。默认的产品路径是在显式模式下运行 `索玛`，将提供者文件放入 `providers/`（或将 `SOMA_PROVIDER_DIR` 指向其他位置），并让提供者注册表项目将这些功能投射到 MCP、CLI、REST、OpenAPI、Palette 摘要、生成的文档和插件元数据中。提供者清单还携带 MCP 原生的提示、资源、任务和诱导元数据，供注册表合约使用。脚手架是创建具有相同锁定运行时的新可分发仓库的路径。
**30 秒路径：** 安装 `索玛` 二进制文件 -> `索玛 状态` -> 从 MCP 客户端使用 `npx -y 索玛-rmcp mcp` -> 通过 `tools/call` 调用 `索玛` MCP 工具，并传入 `{"action":"status"}`。
**状态：** 生产就绪的 RMCP 运行时。只有当提供者声明了它们时，才允许写入提供者操作，并且破坏性操作是有限制的。
**不适用于：** 未认证的公共网关、上游服务授权、任意不受信任的代码执行或多租户安全边界本身。
## 目录
- [命名](#命名)
- [功能和边界](#功能和边界)
- [安装](#安装)
- [快速入门](#快速入门)
- [客户端配置](#客户端配置)
- [运行时界面](#运行时界面)
- [MCP 工具参考](#mcp-工具参考)
- [CLI 参考](#cli参考)
- [配置](#配置)
- [身份验证](#身份验证)
- [安全性和信任模型](#安全性和信任模型)
- [架构](#架构)
- [分发合约](#分发合约)
- [开发](#开发)
- [验证](#验证)
- [部署](#部署)
- [故障排除](#故障排除)
- [相关服务器](#相关服务器)
- [文档](#文档)
- [许可证](#许可证)
## 命名
索玛是运行时产品，首先是模板/导出源，其次是生成的项目在脚手架后处理期间替换这些名称，但发布的 `索玛` 命令是产品行为的真实来源。
| 界面 | 索玛值 | 生成项目模式 |
|---|---|---|
| 仓库 | `jmagar/索玛` | `<服务>-rmcp` 或文档中记录的产品例外 |
| Rust crate/package | `索玛` | 服务特定的 crate 名称 |
| 规范二进制文件 | `索玛` | 通常为 `r<服务>` 或产品名称 |
| npm 包 | `索玛-rmcp` | `<服务>-rmcp` |
| MCP 工具 | `索玛` | 通常为 `<服务>` |
| 环境前缀 | `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 服务工具 (`索玛`)，具有 `action` 调度，因此即使提供者目录增长，代理工具列表仍然很小。
- 一个规范的二进制文件：`索玛`，具有明确的 `serve`、`mcp` 和 CLI 模式，用于 REST API、流式 HTTP MCP、stdio MCP、Web UI 和本地操作。
- 从 `.json`、`.ts`、`.py`、`.wasm` 和 `.md` 文件动态加载提供者，以及原生 Rust 提供者和上游 MCP/OpenAPI 提供者。支持结构化的 `providers/{tools,prompts,resources}/` 布局，以及根级文件，包括路径派生的 MCP 资源（静态文件和动态 `.ts` 读取器）和路径遍历信任边界。
- 提供者清单合约，用于工具、提示、资源、任务、诱导表单、环境需求、功能授予和表面覆盖。
- 共享验证、破坏性操作确认、身份验证/范围强制执行、响应限制、编辑、日志记录、指标、生成的 OpenAPI、生成的提供者表面文档、插件清单、设置、医生和发布工具。
索玛拥有运行时投影、验证、身份验证策略、打包、生成的元数据和脚手架自动化。提供者代码拥有服务特定的行为和凭证。上游服务拥有自己的授权和数据模型。索玛故意拒绝将凭证作为工具调用输入的一部分，并且不将提供者清单转换为不受限制的远程执行边界。
## 安装
当 MCP 客户端期望 `npx` 命令时，请使用 npm 启动器。该包是 Rust 二进制文件的启动器；首先安装 `索玛` 或设置 `SOMA_BIN` 为其绝对路径。
```bash
npx -y 索玛-rmcp mcp
```
在开发仓库时使用 Cargo：
```bash
cargo run --bin 索玛 -- mcp
cargo run --bin 索玛 -- serve
```
发布构建发布 GitHub 发布二进制文件、Docker/OCI 元数据、`索玛-rmcp` npm 启动器、MCP 注册表元数据和插件包文件，从同一发布组件。
## 产品配置文件
选择您想要的表面积，无需更改提供者编写模型。
| 目标 | 最适合 | 默认配置文件 | 包括 |
|---|---|---|---|
| 本地代理适配器 | 本地插件或上游 API 的薄包装 | `local-adapter` | CLI + stdio MCP 在一个本地二进制文件中。默认情况下没有 REST/Web 镜像。 |
| 共享 API/MCP 服务器 | 多个客户端或网关使用的服务 | `server` | CLI + REST API + 流式 HTTP MCP + stdio MCP + 健康/状态路由 + 身份验证功能运行时。 |
| 完整应用平台 | 应用程序拥有状态、作业、仪表板、工作流或人类界面 | `full` | `server` 加上嵌入式 Web UI、OAuth、可观察性和插件支持。 |
| CLI-only 或自定义本地工具 | 脚本、操作实用程序、一机工具 | 自定义功能集，通常从 `cli` 开始 | CLI 解析器和共享服务层。包装的本地二进制文件使用 `local-adapter`，因此 CLI-only 产品可能会修剪 MCP 或调整二进制文件功能门控。 |
当您需要自定义形状时，可以使用较低级别的 Cargo 功能：
| 功能 | 目的 |
|---|---|
| `cli` | CLI 壳和命令解析。 |
| `mcp` | MCP 工具、模式、资源、提示和作用域层。 |
| `mcp-stdio` | 本地 stdio MCP 传输。 |
| `api` | REST 处理程序和 OpenAPI 支持的业务路由。 |
| `auth` | 共享身份验证策略和承载令牌强制执行。 |
| `oauth` | Google OAuth 和 JWT 发行在 `auth` 之上。 |
| `mcp-http` | 在 Axum 中安装的流式 HTTP MCP。 |
| `web` | 嵌入式静态 Web UI 回退。 |
| `observability` | 指标/跟踪钩子。 |
| `plugin` | 插件设置/支持帮助程序。 |
| `local-adapter` | 精简本地二进制文件：`cli` + `mcp-stdio`。 |
| `server` | 可部署的 HTTP 运行时配置文件：`cli` + `api` + HTTP MCP + stdio MCP。 |
| `full` | 完整的平台配置文件：本地适配器、服务器、Web、OAuth、可观察性和插件支持。 |
## 快速入门
直接运行产品：
```bash
git clone https://github.com/jmagar/索玛
cd 索玛
# 完整平台模式：REST API + HTTP MCP + 网页回退到 :40060
cargo run --bin 索玛 -- serve
# 本地二进制文件：stdio MCP
cargo run --bin 索玛 -- mcp
# 本地二进制文件：CLI
cargo run --bin 索玛 -- greet --name Alice
```
有用的烟雾检查：
```bash
curl http://localhost:40060/health
cargo run --bin 索玛 -- status
cargo run --bin 索玛 -- 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":"索玛","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 索玛 -- hello-local --name Alice
```
运行服务器并通过 REST 和 MCP 调用同一个提供者：
```bash
cargo run --bin 索玛 -- 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":"索玛","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 提供者文件是受信任的代码。索玛在提供者目录刷新期间导入它们以发现工具，然后在具有清除环境和仅声明的提供者/工具环境值的边车中执行工具调用。目录导入不接收提供者环境；在工具函数内读取机密，而不是在模块导入时。
提供者清单可以声明：
- 默认情况下通过 MCP 工具公开的功能
- 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)。
## 脚手架新项目
使用 `cargo xtask scaffold` 当提供者优先的路径需要成为具有自己的 crate 名称、二进制文件名称、端口、插件包、Docker 元数据、发布元数据和文档的新仓库时。它可以计划而不触摸文件，使用 `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 + Web 默认值。
- `--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-service/src/provider_registry.rs
验证提供者清单，计算快照/指纹，索引工具、提示、资源、CLI 命令、REST 路由和 MCP 原语。
提供者来源
crates/soma-service/src/providers/
静态 Rust 文件支持的 JSON 清单、TypeScript AI SDK 边车、Python LangChain/LlamaIndex 边车、WASM、OpenAPI 支持的提供者和上游 MCP 提供者。
SomaService
crates/soma-service/src/app.rs
静态 Rust 提供者使用的内置产品/服务逻辑。
传输壳
crates/soma-cli/src/lib.rs CLI 解析器和输出格式化。
crates/soma-mcp/src/tools.rs MCP JSON 参数到服务调用。
crates/soma-api/src/api.rs REST 提取器到服务调用。
crates/soma/src/routes.rs Axum 路由器、身份验证、MCP、API、网页回退。
内置动作元数据
crates/soma-contracts/src/actions.rs
原生动作元数据、验证、缓存的目录/帮助和原生调度。
薄壳规则是严格的：
1. 在界面处解析输入。
2. 调用提供者注册表或服务运行时。
3. 返回或打印结果。
不要将业务规则放入 CLI、MCP、REST 处理程序或 `main.rs`。
## 运行时界面
规范二进制文件可以从一个可执行文件运行整个应用程序：
```bash
索玛 serve # HTTP 服务器：REST API + 流式 HTTP MCP + 网页回退到 40060
索玛 mcp # stdio MCP 传输
索玛 status # CLI 命令通过相同的二进制文件
```
本地适配器模式针对插件/本地使用进行了优化：
```bash
索玛 mcp # stdio MCP 传输
索玛 greet --name Alice # CLI 命令
索玛 doctor # 操作员预飞行检查
索玛 watch # 0..* 轮询 /health 并发出状态变化
索玛 设置 检查 # 插件/应用数据设置检查
索玛 搭建 检查 # 插件/应用程序设置检查
索玛 监视 # 轮询 /health 并发出状态变化
索玛 搭建 检查 # 插件/应用程序设置检查
```
每个显式运行时模式都加载提供者注册表。文件提供者默认为 `./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 操作，除非工具显式设置 `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 机密、承载令牌、密码或其他凭证。
凭证存储在环境变量、配置文件、应用程序数据或上游提供者运行时中。
提供者清单在调度前进行验证。
注册中心强制执行表面选择加入、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 OAuth 设置 | 基于浏览器的 Google OAuth 发布 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_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_AUTH_ADMIN_EMAIL` | OAuth | 空 | 初始/管理员 OAuth 电子邮件。 |
| `RUST_LOG` | 否 | `info` | 日志过滤器。Stdio 模式抑制嘈杂的日志以避免破坏 JSON-RPC。 |
样本：
- [.env.example](.env.example) 用于机密、URL 和运行时环境。
- [config.soma.toml](config.soma.toml) 用于非机密默认值。
## 开发
```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-service/src/soma.rs` 中的存根客户端。
2. 将域逻辑放在 `crates/soma-service/src/app.rs` 或聚焦的服务模块中。
3. 注册原生提供者/动作元数据，以便 MCP、CLI、REST、文档和插件保持注册驱动。
4. 重新生成 MCP 模式文档、提供者曲面文档和 OpenAPI，以便生成的曲面反映提供者注册。
5. 仅为基础设施路由添加 REST 处理程序；业务动作应保持注册支持的直接路由。
6. 更新 `crates/soma-contracts/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 提供者之前是安全的。参见 [`docs/PROVIDERS.md`](docs/PROVIDERS.md)。
-_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 桥接设备、用户和 tailnet 操作。
- [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 和 homelab 日志聚合 MCP 服务器。
- [axon](https://github.com/jmagar/axon) - RAG、爬取、刮取、提取和语义搜索项目。
- [labby](https://github.com/jmagar/labby) - Homelab 控制平面和 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) |
|.json) |
| 插件 | [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) |
| 测试 | [crates/soma/tests/README.md](crates/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
连接信息
猜你喜欢
暂无推荐服务器