Soma

Soma

面向由提供方支持的 Agent 的 RMCP 运行时，支持 CLI、REST、HTTP MCP、插件和脚手架。

API 文档 — 为工作区中的每个 crate 提供 rustdoc，以及由 Redoc 渲染的 OpenAPI 参考文档；从 main 部署到 GitHub Pages。

Soma 是一款开箱即用的服务器运行时和可直接发布的二进制程序，只需编写尽可能少的自定义 Rust 代码，即可启用新的 Agent 能力。它固化了同系列每个服务器都会重新摸索的生产实践： 精简的 MCP 工具、stdio 和 Streamable HTTP 传输、CLI 功能对齐、直接 REST 路由、身份验证/OAuth、可观测性、插件打包、Web 回退、 Docker/运行时示例、生成的契约以及发布自动化。

此仓库仍可用于为重命名后的项目生成脚手架，但 Soma 现在首先是一款已发布的 运行时。默认产品使用路径是以明确模式运行 soma，将提供方文件放入 providers/（或将 SOMA_PROVIDER_DIR 指向其他位置），并让提供方注册表将这些能力投射到 MCP、 CLI、REST、OpenAPI、Palette 摘要、生成的文档和插件元数据中。 提供方清单还包含 MCP 原生的提示词、资源、任务和征求信息元数据，用于注册表契约。 脚手架则用于创建采用相同固化运行时的新可分发仓库。

30 秒上手： 安装 soma 二进制程序 -> soma status -> 在 MCP 客户端中运行 npx -y @dinglebear/soma mcp -> 通过 tools/call 调用 soma MCP 工具，并传入 {"action":"status"}。

状态： 生产级 RMCP 运行时。只有提供方声明的写入型操作才会被允许，且破坏性操作受到限制。

不适用于： 未经身份验证的公共网关、替代上游服务授权、执行任意不可信代码，或单独充当多租户安全边界。

目录

• 命名
• 能力与边界
• 安装
• 快速入门
• 客户端配置
• 运行时接口
• MCP 工具参考
• CLI 参考
• 配置
• 身份验证
• 安全与信任模型
• 架构
• 分发契约
• 开发
• 验证
• 部署
• 故障排除
• 相关服务器
• 文档
• 许可证

命名

Soma 首先是运行时产品，其次才是模板/导出源。 生成的项目会在脚手架后处理中替换这些名称，但已发布的 soma 命令才是产品行为的事实标准。

接口	Soma 值	生成项目的命名模式
仓库	dinglebear-ai/soma（以前称为 rmcp-template，之后称为 rtemplate-mcp——这两个名称仍会重定向）	dinglebear-ai/r<service>，或直接使用产品名称；较早的服务器仍使用 <service>-rmcp 名称，并通过重定向访问
Rust crate/包	soma	特定于服务的 crate 名称
规范二进制程序	soma	通常为 r<service> 或产品名称
npm 包	@dinglebear/soma	<service>-rmcp
MCP 工具	soma	通常为 <service>
环境变量前缀	SOMA_*	生成项目的服务前缀

能力与边界

路径	适用场景	你负责编写	运行时提供
即插即用提供方	你可以将某项能力描述为清单、脚本、WASM 模块、OpenAPI 操作或上游 MCP 调用。	providers/ 下包含工具、提示词、资源、环境变量需求、能力授权和界面覆盖项的文件。	MCP 工具调度、动态 CLI 命令、直接 REST 路由、架构验证、身份验证策略、刷新、OpenAPI/Palette 摘要、生成的文档和插件元数据。
静态 Rust 提供方	该能力需要原生 Rust、紧密集成或可复用的 crate。	向提供方注册表注册的 Rust 提供方/操作。	无需针对各界面重写，即可投射到相同的 MCP/CLI/REST/文档/插件。
脚手架生成的产品	你需要重命名仓库、包标识、端口、插件、Docker 标签和发布元数据。	scaffold_intent 负载或 cargo xtask scaffold 选项。	可编译的产品仓库、脚手架报告、cargo-generate 后处理，以及脚手架/导出验证检查。
自定义配置	你需要更精简的二进制文件或部署形式。	Cargo 功能选择。	由 local-adapter、server 和 full 配置共享的相同运行时 crate。

开箱即用

• 一个精简的 MCP 服务工具（soma），采用 action 分发，因此即使提供方目录不断增长，Agent 工具列表也能保持精简。
• 一个规范二进制文件：soma，提供明确的 serve、mcp 和 CLI 模式，支持 REST API、Streamable HTTP MCP、stdio MCP、可选 Web UI 和本地操作。
• 从 .json、.ts、.py、.wasm 和 .md 文件动态加载提供方，同时支持原生 Rust 提供方和上游 MCP/OpenAPI 提供方类型。除根目录文件外，还支持结构化的 providers/{tools,prompts,resources}/ 布局，其中包括基于路径的 MCP 资源（静态文件和动态 .ts 读取器），并设置路径遍历信任边界。
• 为工具、提示词、资源、任务、征询表单、环境变量要求、能力授权和界面覆盖项提供方清单契约。
• 共享验证、破坏性操作确认、身份验证/范围强制执行、响应限制、脱敏、日志记录、指标、生成的 OpenAPI、生成的提供方界面文档、插件清单、设置、诊断和发布工具。

Soma 负责运行时投射、验证、身份验证策略、打包、生成的元数据和脚手架自动化。提供方代码负责特定服务的行为和凭据。上游服务负责自身的授权和数据模型。Soma 特意禁止将凭据作为工具调用输入，也不会把提供方清单变成不受限制的远程执行边界。

安装

当 MCP 客户端需要 npx 命令时，请使用 npm 启动器。在 postinstall 期间，软件包会下载匹配的 Linux/x64 或 Windows/x64 发布归档，验证其 SHA256SUMS 条目和 GitHub 构建证明，然后在软件包内安装原生二进制文件。验证来源证明需要 GitHub CLI 2.68 或更高版本。

npx -y @dinglebear/soma mcp

开发仓库时请使用 Cargo：

cargo run --bin soma -- mcp
cargo run --bin soma -- serve

发布构建会从同一个发布组件中发布 GitHub Release 二进制文件、Docker/OCI 元数据、@dinglebear/soma npm 启动器、MCP 注册表元数据和插件包文件。

产品配置

选择所需的功能范围，无需更改提供方的编写模型。

目标	适用场景	默认配置	包含内容
本地 Agent 适配器	为放入目录的提供方或上游 API 提供轻量封装	local-adapter	在一个本地二进制文件中提供 CLI + stdio MCP。默认不包含 REST/Web 镜像。
共享 API/MCP 服务	供多个客户端或网关使用的服务	server	CLI + REST API + Streamable HTTP MCP + stdio MCP + 健康状态路由 + 支持身份验证的运行时。
完整应用平台	应用负责管理状态、任务、仪表板、工作流或面向用户的 UI	full	server，另加内嵌 Web UI、OAuth、可观测性和插件支持。
仅 CLI 或自定义本地工具	脚本、运维工具、单机工具	自定义功能集，通常从 cli 开始	CLI 解析器和共享服务层。标准打包的本地二进制文件使用 local-adapter，因此仅 CLI 产品可以精简 MCP，或调整二进制文件的功能门控。

需要自定义组合时，可使用较低层级的 Cargo 功能：

功能	用途
cli	CLI 垫片和命令解析。
mcp	MCP 工具、架构、资源、提示词和作用域层。
mcp-stdio	本地 stdio MCP 传输。
api	REST 处理程序和基于 OpenAPI 的业务路由。
auth	共享身份验证策略和 Bearer 令牌强制校验。
oauth	基于 auth 提供 Google、Authelia 和 GitHub OAuth/OIDC，以及 JWT 签发。
mcp-http	在 Axum 中挂载 Streamable HTTP MCP。
web	内嵌静态 Web UI 回退方案。
observability	指标/跟踪钩子。
plugin	插件设置/支持辅助工具。
local-adapter	轻量本地二进制文件：cli + mcp-stdio。
server	可部署的 HTTP 运行时配置：cli + api + HTTP MCP + stdio MCP。
full	完整平台配置：本地适配器、服务、Web、OAuth、可观测性和插件支持。

快速入门

直接运行产品：

git clone https://github.com/dinglebear-ai/soma
cd soma

# Full platform mode: REST API + HTTP MCP + web fallback on :40060
cargo run --bin soma -- serve

# Local binary: stdio MCP
cargo run --bin soma -- mcp

# Local binary: CLI
cargo run --bin soma -- greet --name Alice

实用的冒烟测试：

curl http://localhost:40060/health
cargo run --bin soma -- status
cargo run --bin soma -- doctor

直接调用 MCP 端点：

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。

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 界面调用：

cargo run --bin soma -- hello-local --name Alice

运行服务，并通过 REST 和 MCP 调用同一个提供方：

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/：

PROVIDER = {"name": "math-tools", "kind": "python"}

def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

如果未设置 TOOLS，模块中定义的公开函数就会成为工具。支持同步和异步函数，并会将常见的 Python 类型注解转换为输入架构。

Python 提供方文件属于受信任代码。Soma 会在刷新提供方目录时导入这些文件以发现工具，随后在一个已清除环境变量、仅包含已声明的提供方/工具环境变量的 Sidecar 中执行工具调用。目录导入时不会获取提供方环境变量；请在工具函数中读取机密信息，而不要在模块导入时读取。

提供方清单可以声明：

• 默认通过 MCP 暴露，并可通过选择加入的叠加层通过 CLI/REST 暴露的工具/操作
• 面向提供方注册表契约的 MCP 原生提示词、资源、任务和引导元数据
• 必需的环境变量和脱敏规则
• 文件系统、网络、浏览器、终端、GitHub 和环境变量能力授权
• 限制、破坏性操作元数据、示例、生成的文档、插件和 UI 元数据

支持的提供方类型包括 static-rust、openapi、ai-sdk、wasm、mcp、python、langchain 和 llamaindex。请参阅 docs/specs/dynamic-provider-runtime.md、 docs/contracts/provider-manifest.schema.json 和 docs/generated/provider-surfaces.md。

搭建新项目

当 provider-first 路径需要发展为一个拥有独立 crate 名称、二进制名称、端口、插件包、Docker 元数据、发布元数据和文档的新仓库时，请使用 cargo xtask scaffold。它可以在不改动文件的情况下生成计划，使用 cargo-generate 和 Rust 后处理器生成项目，写入 docs/scaffold-report.md，并验证生成的导出结构。

根据简短的服务名称生成计划：

cargo xtask scaffold --name myservice --category upstream-client --port auto --plan

根据 MCP scaffold_intent JSON 生成计划：

cargo xtask scaffold --intent scaffold-intent.json --plan

生成到输出父目录：

cargo xtask scaffold --intent scaffold-intent.json --apply ../generated

验证已有的生成项目：

cargo xtask scaffold --verify ../generated/myservice-mcp

打印包含路径信息的后续计划，以便调整生成的存根：

cargo xtask scaffold --adapt-plan ../generated/myservice-mcp

根据操作清单生成初始工件：

cargo xtask scaffold \
  --write-action-starters ../generated/myservice-mcp \
  --actions actions.json

添加初始操作片段：

cargo xtask scaffold \
  --intent scaffold-intent.json \
  --actions actions.json \
  --plan

操作清单示例：

{
  "actions": [
    {
      "name": "list_things",
      "description": "List visible things.",
      "scope": "read",
      "params": [
        { "name": "kind", "type": "string", "required": false }
      ]
    }
  ]
}

使用：

• 对现有 API 的精简本地适配器使用 --category upstream-client。
• 对 API + CLI + MCP + Web 默认配置使用 --category application-platform。
• 仅在迭代时需要快速静态验证的情况下使用 --no-cargo-check。

完整的搭建约定请参阅 docs/SCAFFOLD.md、docs/CARGO_GENERATE.md 和 docs/contracts/scaffold-intent.schema.json。

架构

运行时将产品行为置于 provider 注册表之后。每个外部接口都是围绕同一 provider 快照和服务运行时的精简解析器/格式化器，因此移除某个 provider 无需手动修改 MCP、CLI、REST、 OpenAPI、插件或文档代码。

ProviderRegistry
  crates/soma/application/src/provider_registry.rs
  Validates provider manifests, computes snapshots/fingerprints, indexes tools,
  prompts, resources, CLI commands, REST routes, and MCP primitives.

Provider sources
  crates/soma/application/src/providers/
  Static Rust, file-backed JSON manifests, TypeScript AI SDK sidecars, Python
  LangChain/LlamaIndex sidecars, WASM, OpenAPI-backed providers, and upstream
  MCP providers.

SomaService
  crates/soma/application/src/service.rs
  Built-in product/service logic used by the static Rust provider.

Transport shims
  crates/soma/cli/src/lib.rs        CLI parser and output formatting.
  crates/soma/mcp/src/tools.rs      MCP JSON args to service calls.
  crates/soma/api/src/api.rs        REST extractors to service calls.
  apps/soma/src/http.rs             Axum router, auth, MCP, API, web fallback.

Built-in action metadata
  crates/soma/domain/src/actions.rs
  Native action metadata, validation, cached catalog/help, and native dispatch.

精简封装规则十分严格：

1. 在接口层解析输入。
2. 调用 provider 注册表或服务运行时。
3. 返回或打印结果。

不要在 CLI、MCP、REST 处理程序或二进制入口点 （apps/soma/src/bin/soma.rs / apps/soma/src/bootstrap.rs）中放置业务规则。

运行时接口

规范二进制文件可通过一个可执行文件运行整个应用：

soma serve       # HTTP server: REST API + Streamable HTTP MCP + web fallback
soma mcp         # stdio MCP transport
soma status      # CLI command through the same binary

本地适配器模式针对插件/本地使用进行了优化：

soma mcp                # stdio MCP transport
soma greet --name Alice # CLI command
soma doctor             # operator pre-flight checks
soma watch              # poll /health and emit state changes
soma setup check        # plugin/appdata setup checks

每种显式运行时模式都会加载 provider 注册表。文件 provider 默认位于 ./providers，可通过 SOMA_PROVIDER_DIR 更改位置。CLI 启动、MCP 分发和动态 REST 路由会在执行前刷新文件 provider，随后强制执行当前 provider 快照的架构、接口、范围、能力、破坏性操作和响应限制规则。

服务器配置文件中的 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}	用于已添加 provider 工具的通用 REST 执行路由。
/v1/{provider-route}	工具提供自定义 REST 覆盖层时可选的 provider 声明式 REST 路由。
/mcp/.well-known/*	启用 OAuth 时提供的 OAuth 元数据。
/*	使用 web 构建时的嵌入式 Web UI 回退路由。

REST 仅支持直接路由：没有 /v1/soma 操作封装。MCP 仍使用一个名为 soma 的工具，并带有一个 action 参数。

MCP 工具参考

运行时提供一个精简的 MCP 工具 soma，并带有一个 action 参数。 内置操作和已添加的 provider 工具共用同一分发路径。这样既能保持 MCP 发现结果精简，也能让 provider 目录在单个工具之后不断扩展。

操作	范围	成本	传输方式	REST 路由	CLI	参数	描述
greet	soma:read	cheap	MCP + CLI + REST	POST /v1/greet	soma greet [--name NAME]	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	无	返回服务状态和配置信息。
python_environment_status	soma:write	cheap	MCP + CLI + REST	GET /v1/python/environments	soma python_environment_status	无	检查不可变 Python 环境缓存状态，不执行提供方代码。
python_environment_prune_plan	soma:write	moderate	MCP + CLI + REST	POST /v1/python/environments/prune-plan	soma python_environment_prune_plan --json '{\	stale_before_unix_seconds（必填整数），max_entries（可选整数）	规划对过期且非就绪的 Python 环境缓存条目进行有界清理。
python_environment_prune	soma:write	write	MCP + CLI + REST	POST /v1/python/environments/prune	soma python_environment_prune --json '{\	stale_before_unix_seconds（必填整数），max_entries（可选整数），confirm（必填布尔值）	对过期且非就绪的 Python 环境缓存条目执行有界清理。
python_environment_repair	soma:write	write	MCP + CLI + REST	POST /v1/python/environments/repair	soma python_environment_repair --json '{\	provider_path（必填字符串），confirm（必填布尔值）	修复一个受管 Python 提供方的不可变环境。
python_environment_update	soma:write	write	MCP + CLI + REST	POST /v1/python/environments/update	soma python_environment_update --json '{\	provider_path（必填字符串），confirm（必填布尔值）	为一个受管 Python 提供方解析、准备、验证并原子激活不可变更新。
python_worker_status	soma:write	cheap	MCP + CLI + REST	GET /v1/python/workers	soma python_worker_status	无	检查持久化 Python 工作进程的健康状况、隔离状态、重启次数以及有界的脱敏日志。
python_worker_cancel	soma:write	write	MCP + CLI + REST	POST /v1/python/workers/cancel	soma python_worker_cancel --json '{\	provider（必填字符串），confirm（必填布尔值）	通过终止进程树，取消一个正在执行的持久化 Python 调用。
python_worker_reset	soma:write	write	MCP + CLI + REST	POST /v1/python/workers/reset	soma python_worker_reset --json '{\	provider（必填字符串），confirm（必填布尔值）	清除一个持久化 Python 工作进程的崩溃循环隔离状态。
python_generation_status	soma:read	cheap	MCP + CLI + REST	GET /v1/python/generations	soma python_generation_status	无	检查当前激活的 Python 提供方代次和有界回滚历史。
python_generation_rollback	soma:write	write	MCP + CLI + REST	POST /v1/python/generations/rollback	soma python_generation_rollback --json '{\	generation_id（必填整数），confirm（必填布尔值）	原子地重新激活保留的 Python 提供方代次。
python_graduation_status	soma:read	cheap	MCP + CLI + REST	POST /v1/python/graduation/status	soma python_graduation_status --json '{\	workspace（必填字符串）	检查与摘要绑定的 Python 毕业、符合性、激活和回滚状态。
python_graduation_apply	soma:write	write	MCP + CLI + REST	POST /v1/python/graduation/apply	soma python_graduation_apply --json '{\	operation（必填字符串），workspace（必填字符串），source（可选字符串），component（可选字符串），fixtures（可选字符串），wheelhouse（可选字符串），confirm（必填布尔值）	为 Python 毕业工作区搭建脚手架、组件化、构建、验证、比较、激活或回滚。
elicit_name	soma:read	cheap	仅 MCP	-	_MCP-only_	无	请求 MCP 客户端收集姓名，然后返回个性化问候语。
scaffold_intent	soma:read	moderate	仅 MCP	-	_MCP-only_	无	通过 MCP 引导式信息收集来收集脚手架设置意图，并为 scaffold-project 技能返回 JSON。
help	public	cheap	MCP + CLI + REST	GET /v1/help	soma help	无	显示操作参考。
Python 提供方生命周期管理通过同一个精简工具公开，并提供以下明确操作：

• 环境缓存：python_environment_status、 python_environment_prune_plan、python_environment_prune、 python_environment_repair 和 python_environment_update；
• 持久工作进程：python_worker_status、python_worker_cancel 和 python_worker_reset；
• 提供方版本：python_generation_status 和 python_generation_rollback；
• 将 Python 升级为组件：python_graduation_status 和需确认的 python_graduation_apply。

内置业务操作在 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 和适配器的安全执行形式。CLI 暴露需通过每个工具的 cli 覆盖项选择启用。提供方提示词、资源、任务和引导表单属于提供方清单约定和注册表索引的一部分，默认不会同步到 CLI 或 REST。

CLI 参考

soma 二进制文件通过与 MCP 相同的注册表快照，提供运维命令和由提供方支持的操作：

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 密钥、Bearer 令牌、密码或其他凭据。凭据存放在环境变量、配置文件、appdata 或上游提供方运行时中。

分发前会验证提供方清单。注册表会强制执行各接口的启用设置、JSON Schema 输入验证、身份验证范围、声明的主机能力、破坏性操作确认、响应大小限制和结构化提供方错误。Python、LangChain、LlamaIndex 和 TypeScript 提供方文件属于受信任的本地代码；WASM 提供方通过沙盒化的 WASM 提供方路径运行；OpenAPI 和 MCP 提供方则将信任交由其配置的上游服务。

身份验证

HTTP 服务支持四种身份验证策略：

策略	适用情形	效果
回环开发	绑定到回环地址，或在回环地址上设置 SOMA_MCP_NO_AUTH=true	不使用身份验证中间件，不检查范围。
Bearer 令牌	已设置 SOMA_MCP_TOKEN	/mcp 和 /v1/* 需要 Authorization: Bearer <token>。
OAuth	设置 SOMA_MCP_AUTH_MODE=oauth，且至少配置一个提供方	通过基于浏览器的 Google、Authelia 或 GitHub 登录签发 JWT Bearer 令牌。
受信任网关	在非回环地址上设置 SOMA_NOAUTH=true	禁用本地身份验证和范围检查，因为这些工作由上游网关负责。

除非已配置 Bearer、OAuth 或受信任网关模式，否则启动保护机制会拒绝在非回环地址上进行未经过身份验证的绑定。/health、/readyz、/status 和 /openapi.json 按设计公开，只返回安全的运行时元数据。

详细的身份验证模型请参阅 docs/AUTH.md。

配置

配置值从 config.toml、本地 appdata 文件和环境变量中加载；显式设置的环境变量优先。内置的离线提供程序无需真实凭据即可运行，但生成的项目应将真实的上游／平台凭据标记为必需。

变量	必需	默认值	说明
SOMA_API_URL	否	空	已部署的平台 API 或上游服务 URL。留空时使用桩／离线行为。
SOMA_API_KEY	否	空	Bearer 令牌或上游服务 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	bearer	空	静态 Bearer 令牌。
SOMA_MCP_ALLOWED_HOSTS	否	空	额外的、以逗号分隔的 Host 标头值。
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 App 客户端 ID。
SOMA_MCP_GITHUB_CLIENT_SECRET	GitHub	空	GitHub OAuth App 客户端密钥。
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 保持为默认值。仅使用 Bearer／OAuth 身份验证并不构成此信任边界。完整的仅入站跟踪标头约定，请参阅 docs/TRACE_CONTEXT.md。

示例：

• .env.example：密钥、URL 和运行时环境变量。
• config.soma.toml：非敏感默认值。

提供程序回调路径默认为 /auth/google/callback、/auth/authelia/callback 和 /auth/github/callback；回调和范围覆盖项列于 docs/ENV.md。GitHub OAuth Apps 不提供上游刷新令牌，因此使用 GitHub 身份验证的会话不会获得本地刷新令牌，访问令牌过期后必须重新登录。提供程序选择和安全详情请参阅 docs/AUTH.md。

开发

# Build profiles
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

# Run checks
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo nextest run
cargo xtask contract-audit
cargo xtask generate-provider-surfaces --check

# Common just recipes
just dev                 # loopback HTTP server with local no-auth
just mcp                 # stdio MCP
just greet               # CLI smoke test
just doctor              # pre-flight check
just build-local         # local adapter binary
just build-full          # web assets + full platform binary
just verify              # fmt, lint, check, test
just check-docs          # generated docs/metadata current
just scaffold-contract-check
just validate-plugin

cargo xtask ci 会运行主要的本地 CI 流程。安装了 cargo-nextest、taplo 和 cargo-audit 等可选工具时，也会使用它们。

工作区布局

41 个 Cargo 成员：

路径	内容
crates/soma/*	此服务的产品代码 — domain、application、config、client、api、cli、mcp、runtime、integrations、palette、web、test-support
crates/shared/*	供其他服务使用的可复用引擎 crate — auth、mcp（client/server/proxy/gateway）、provider-core、provider-adapters、http-api、http-server、observability、openapi、self-update、traces、codemode、cli-core，以及带命名空间的可复用系列，例如 cortex/ingest-core
crates/integrations/*	上游服务桥接 — gotify、unifi
apps/soma	soma 二进制文件及其集成测试。apps/ 下唯一的 Cargo 成员 — apps/web（Next.js）和 apps/palette（资源文件）不是 Rust crate。
packages/python	pyo3 Python provider 平台（abi3-py311）
xtask	所有仓库自动化任务；scripts/*.py 是对它的轻量封装

rmcp 被精确锁定 — [workspace.dependencies] 中的 rmcp = { version = "=3.1.0", default-features = false }， 由于 TOML 无法交叉引用，因此在 rmcp-client 别名条目中也重复声明。 更新版本时需同时修改两处。

[workspace.package] 是 Rust 版本和 MSRV 的唯一准确信息来源：新成员通过 edition.workspace = true 和 rust-version.workspace = true 继承 edition = "2024" 和 rust-version = "1.97.1"。共享 crate 也会继承工作区 lint 设置，确保整个服务群的架构和模块布局策略保持一致。

客户端配置

Streamable HTTP：

{
  "mcpServers": {
    "soma": {
      "url": "http://localhost:40060/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Stdio：

{
  "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_*、工具名称、作用域 和路径替换为生成的服务名称。

插件接口

仓库在 plugins/soma 下提供一个共享的 Soma 插件包，适用于 Claude Code、Codex 和 Gemini 接口。插件清单不包含版本号； 发布工具会根据 git 状态推导版本标识。插件包可以使用本地 stdio 适配器，并包含针对 appdata 和环境文件的设置与诊断支持。

主要文档：

• docs/PLUGINS.md
• plugins/soma/.codex-plugin/README.md
• plugins/soma/skills/soma/SKILL.md
• plugins/soma/skills/scaffold-project/SKILL.md

分发约定

soma 发布组件定义于 release/components.toml。带版本号的构件 必须在 Rust 包、Cargo.lock、server.json、npm 包、生成的 OpenAPI 元数据、OCI 镜像标识符和变更日志之间保持一致。

插件清单不包含版本号。市场和插件的发布标识根据 git/包元数据推导，而 server.json 和生成的 provider 接口文档则描述当前发布的运行时接口。发布元数据前，请运行 cargo xtask check-version-sync、cargo xtask generate-provider-surfaces --check 和 cargo xtask check-docs。

Web UI

web 功能会提供由 soma-web 打包的静态导出内容。可编辑的前端源代码位于 apps/web，cargo xtask sync-web-source 会将该源代码复制到 Rust crate 包中。

常用命令：

cargo xtask build-web
cargo xtask sync-web-source
cargo xtask check-web-source-sync
pnpm -C apps/web validate

不需要人机交互界面的生成项目应使用 local-adapter、server，或不包含 web 的自定义功能集。

部署

完整平台配置旨在通过单个可部署的 soma 二进制文件运行。仓库 还包含 Docker 和 Compose 示例：

• config/Dockerfile
• docker-compose.prod.yml
• entrypoint.sh

改造生成的项目时，请核对规范二进制文件名、暴露端口、 健康检查端口、镜像标签、服务用户/组、数据卷以及必需的环境变量。脚手架验证器会检查若干仅与脚手架有关的构件，但发布镜像前仍需针对具体服务审查部署文件。

何时仅靠即插即用的提供方还不够

大多数新功能都应从提供方文件开始。只有在需要可复用的 crate 边界、更丰富的服务状态、自定义客户端、后台任务、专属包标识或经过精细调整的传输行为时，才选择原生 Rust 或脚手架生成的产品。

对于生成的产品，先打印适配配置档案的检查清单：

cargo xtask scaffold --adapt-plan ../generated/myservice-mcp

然后，为重复性操作接线生成便于审查的起步文件：

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 会检查本地配置、应用数据和连接情况。
• soma providers validate 会根据已加载的实时注册表，验证提供方清单和已编译的架构。
• soma providers inspect 会显示提供方界面、能力状态和生成的操作清单。
• soma providers list|lint|status 会检查磁盘上的即插即用提供方文件，不会加载注册表或执行任何处理程序——在运行时接触 TS/WASM/MCP/OpenAPI 提供方之前，可以安全运行。请参阅 docs/PROVIDERS.md。
• Stdio 模式会保持日志安静，以免破坏 JSON-RPC；排查启动时的嘈杂错误时，请使用 HTTP 模式或文件日志。
• 如果生成的文档不一致，请运行 cargo xtask generate-provider-surfaces --write，然后重新运行 --check 命令。

相关服务

• runifi - UniFi 控制器 REST API 桥接服务。
• rtailscale - 用于设备、用户和 tailnet 操作的 Tailscale API 桥接服务。
• unraid - Unraid 单体代码库：Python 和 Rust GraphQL MCP 服务，以及 Unraid 插件。
• rapprise - Apprise 通知扇出桥接服务，支持多种投递后端。
• rgotify - Gotify 推送通知桥接服务，支持发送通知、消息、应用和客户端。
• rarcane - 用于容器及相关资源的 Arcane Docker 管理桥接服务。
• yarr - 媒体栈桥接服务，支持 Sonarr、Radarr、Prowlarr、Plex 及相关服务。
• rytdl - 媒体下载和元数据工作流服务。
• synapse - 用于 scout 和 flux 操作的本地 Synapse 工作流服务。
• cortex - Syslog 和 homelab 日志聚合 MCP 服务。
• axon - RAG、爬取、抓取、提取和语义搜索项目。
• labby - Homelab 控制平面和 MCP 网关项目。
• lumen - 本地语义代码搜索 MCP 服务。

文档

主题	文档
架构与分层	docs/ARCHITECTURE.md、docs/PATTERNS.md
Cortex 共享 crate 拆分	docs/cortex-extraction/README.md、ADR 0014
动态提供程序运行时	docs/specs/dynamic-provider-runtime.md、docs/generated/provider-surfaces.md
提供程序清单契约	docs/contracts/provider-manifest.schema.json、docs/contracts/examples/provider-manifests
脚手架工作流	docs/SCAFFOLD.md、docs/CARGO_GENERATE.md
脚手架意图契约	docs/specs/scaffold-intent-handoff.md、docs/contracts/scaffold-intent.schema.json
MCP 操作架构	docs/MCP_SCHEMA.md
REST OpenAPI	docs/generated/openapi.json
身份验证	docs/AUTH.md
插件	docs/PLUGINS.md
发布与版本管理	release/components.toml、docs/MCP-REGISTRY-PUBLISH-GUIDE.md
自动化	xtask/README.md、scripts/README.md
测试	apps/soma/tests/README.md

验证

产品运行时门禁：

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 后处理或生成项目输出时，请运行这些门禁：

cargo xtask check-scaffold-intent-contract
cargo xtask scaffold --verify ../generated/myservice-mcp
cargo xtask check-cargo-generate

迭代时使用有针对性的检查，然后在发布前运行更全面的产品门禁以及受影响的脚手架门禁。

许可证

本项目中由 Dinglebear 原创撰写的部分依据 AGPL-3.0-only 许可。对于需要 AGPL 以外条款的组织，可提供单独的商业许可。第三方材料仍遵循其原始许可证。请参阅 LICENSING.md。