soma

# Soma

`Soma` is a batteries-included RMCP server runtime and shipping binary
for bringing new agent capabilities online with as little custom Rust as
possible. It locks in the production patterns that every server in the family
keeps rediscovering: one compact MCP tool, stdio and Streamable HTTP transports,
CLI parity, direct REST routes, auth/OAuth, observability, plugin packaging,
web fallback, Docker/runtime samples, generated contracts, and release
automation.

The repository can still scaffold a renamed project, but Soma is now a shipped
runtime first. The default product path is to run `soma` in an explicit mode,
drop provider files into `providers/` (or point `SOMA_PROVIDER_DIR`
elsewhere), and let the provider registry project those capabilities across MCP,
CLI, REST, OpenAPI, Palette summaries, generated docs, and plugin metadata.
Provider manifests also carry MCP-native prompt, resource, task, and elicitation
metadata for the registry contract. Scaffolding is the path for creating a new
distributable repo with the same locked-in runtime.

**30-second path:** install the `soma` binary -> `soma status` ->
`npx -y soma-rmcp mcp` from an MCP client -> call the `soma` MCP tool through
`tools/call` with `{"action":"status"}`.

**Status:** production RMCP runtime. Write-capable provider actions are
allowed only when the provider declares them and destructive actions are gated.

**Not for:** an unauthenticated public gateway, a replacement for upstream
service authorization, arbitrary untrusted code execution, or a multi-tenant
security boundary by itself.

## Contents

- [Naming](#naming)
- [Capabilities And Boundaries](#capabilities-and-boundaries)
- [Install](#install)
- [Quickstart](#quickstart)
- [Client Configuration](#client-configuration)
- [Runtime Surfaces](#runtime-surfaces)
- [MCP Tool Reference](#mcp-tool-reference)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Authentication](#authentication)
- [Safety And Trust Model](#safety-and-trust-model)
- [Architecture](#architecture)
- [Distribution Contract](#distribution-contract)
- [Development](#development)
- [Verification](#verification)
- [Deployment](#deployment)
- [Troubleshooting](#troubleshooting)
- [Related Servers](#related-servers)
- [Documentation](#documentation)
- [License](#license)

## Naming

Soma is the runtime product first and the template/export source second.
Generated projects replace these names during scaffold post-processing, but the
shipped `soma` command is the source of truth for product behavior.

| Surface | Soma value | Generated-project pattern |
|---|---|---|
| Repository | `dinglebear-ai/soma` | `<service>-rmcp` or a documented product exception |
| Rust crate/package | `soma` | service-specific crate names |
| Canonical binary | `soma` | usually `r<service>` or the product name |
| npm package | `soma-rmcp` | `<service>-rmcp` |
| MCP tool | `soma` | usually `<service>` |
| Env prefix | `SOMA_*` | generated service prefix |

## Capabilities And Boundaries

| Path | Use when | You author | Runtime supplies |
|---|---|---|---|
| Drop-in provider | You can describe a capability as a manifest, script, WASM module, OpenAPI operation, or upstream MCP call. | Files under `providers/` with tools, prompts, resources, env needs, capability grants, and surface overlays. | MCP tool dispatch, dynamic CLI commands, direct REST routes, schema validation, auth policy, refresh, OpenAPI/Palette summaries, generated docs, and plugin metadata. |
| Static Rust provider | The capability needs native Rust, tight integration, or reusable crates. | A Rust provider/action registered with the provider registry. | The same MCP/CLI/REST/docs/plugin projection without per-surface rewrites. |
| Scaffolded product | You need a renamed repository, package identity, ports, plugins, Docker labels, and release metadata. | A `scaffold_intent` payload or `cargo xtask scaffold` options. | A compiling product repo, scaffold report, cargo-generate post-processing, and scaffold/export verification checks. |
| Custom profile | You need a narrower binary or deployment shape. | Cargo feature selection. | The same runtime crates behind `local-adapter`, `server`, and `full` profiles. |

## Batteries Included

- One compact MCP service tool (`soma`) with `action` dispatch, so agent tool
  lists stay small even as provider catalogs grow.
- One canonical binary: `soma` with explicit `serve`, `mcp`, and CLI modes for
  REST API, Streamable HTTP MCP, stdio MCP, optional web UI, and local actions.
- Dynamic provider loading from `.json`, `.ts`, `.py`, `.wasm`, and `.md`
  files, plus native Rust providers and upstream MCP/OpenAPI provider kinds.
  A structured `providers/{tools,prompts,resources}/` layout is supported
  alongside root-level files, including path-derived MCP resources (static
  files and dynamic `.ts` readers) with a path-traversal trust boundary.
- Provider manifest contracts for tools, prompts, resources, tasks,
  elicitation forms, env requirements, capability grants, and surface overlays.
- Shared validation, destructive-action confirmation, auth/scope enforcement,
  response limits, redaction, logging, metrics, generated OpenAPI, generated
  provider surface docs, plugin manifests, setup, doctor, and release tooling.

Soma owns the runtime projection, validation, auth policy, packaging, generated
metadata, and scaffold automation. Provider code owns service-specific behavior
and credentials. Upstream services own their own authorization and data model.
Soma deliberately refuses to make credentials part of tool-call input and does
not turn provider manifests into an unrestricted remote execution boundary.

## Install

Use the npm launcher when an MCP client expects an `npx` command. The package is
a launcher for the Rust binary; install `soma` first or set `SOMA_BIN` to its
absolute path.

```bash
npx -y soma-rmcp mcp
```

Use Cargo while developing the repo:

```bash
cargo run --bin soma -- mcp
cargo run --bin soma -- serve
```

Release builds publish GitHub Release binaries, Docker/OCI metadata, the
`soma-rmcp` npm launcher, MCP registry metadata, and plugin package files from
the same release component.

## Product Profiles

Choose the amount of surface area you want without changing the provider authoring
model.

| Target | Best fit | Default profile | Includes |
|---|---|---|---|
| Local agent adapter | Thin wrapper over dropped providers or an upstream API | `local-adapter` | CLI + stdio MCP in one local binary. No REST/Web mirror by default. |
| Shared API/MCP server | Service used by multiple clients or a gateway | `server` | CLI + REST API + Streamable HTTP MCP + stdio MCP + health/status routes + auth-capable runtime. |
| Full application platform | App owns state, jobs, dashboards, workflows, or human UI | `full` | `server` plus embedded web UI, OAuth, observability, and plugin support. |
| CLI-only or custom local tool | Scripts, operator utilities, one-machine tools | Custom feature set, usually starting from `cli` | CLI parser and shared service layer. The stock packaged local binary uses `local-adapter`, so CLI-only products may prune MCP or adjust binary feature gates. |

Lower-level Cargo features are available when you need a custom shape:

| Feature | Purpose |
|---|---|
| `cli` | CLI shim and command parsing. |
| `mcp` | MCP tool, schema, resource, prompt, and scope layers. |
| `mcp-stdio` | Local stdio MCP transport. |
| `api` | REST handlers and OpenAPI-backed business routes. |
| `auth` | Shared auth policy and bearer-token enforcement. |
| `oauth` | Google, Authelia, and GitHub OAuth/OIDC plus JWT issuance on top of `auth`. |
| `mcp-http` | Streamable HTTP MCP mounted in Axum. |
| `web` | Embedded static web UI fallback. |
| `observability` | Metrics/tracing hooks. |
| `plugin` | Plugin setup/support helpers. |
| `local-adapter` | Lean local binary: `cli` + `mcp-stdio`. |
| `server` | Deployable HTTP runtime profile: `cli` + `api` + HTTP MCP + stdio MCP. |
| `full` | Complete platform profile: local adapter, server, web, OAuth, observability, and plugin support. |

## Quickstart

Run the product as-is:

```bash
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
```

Useful smoke checks:

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

Call the MCP endpoint directly:

```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"}}}'
```

## Drop In A Provider

The fastest path for a new server is provider-first. Add a provider manifest or
module to `providers/`, then run the same binary. Use `SOMA_PROVIDER_DIR`
when the provider catalog should live outside the working directory.

```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
```

Call it through the dynamic CLI s