pmcp-server-toolkit 0.1.0

Runtime library for config-driven MCP servers — auth, secrets, static resources/prompts, [[tools]] synthesizer, code-mode wiring
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# pmcp-server-toolkit

Runtime library for config-driven MCP servers — auth, secrets, static resources/prompts, `[[tools]]` synthesizer, code-mode wiring.

**Status:** 0.1.0 — early access. Public API may evolve as DX matures across Phases 84–89.

## What this crate is

`pmcp-server-toolkit` lifts the operational glue that pmcp-run servers share into the public SDK, so a `main.rs` can wire a config-driven MCP server in ~15 lines. The crate is organised as a flat module set (Phase 83 decision D-15):

- `auth` — `AuthProvider` implementations (`StaticAuthProvider`, `BearerAuthProvider`).
- `secrets` — `SecretsProvider` trait + env/AWS implementations and the `SecretValue` newtype that never leaks via `Debug`/`Display`/`Serialize`.
- `config` — `ServerConfig` types with `#[serde(deny_unknown_fields)]` strictness.
- `prompts` — `StaticPromptHandler` adapter for static prompt templates.
- `resources` — `StaticResourceHandler` adapter for shipped resources.
- `tools` — `synthesize_from_config` builder turning `[[tools]]` config rows into `ToolInfo` + `Arc<dyn ToolHandler>` pairs.
- `sql` — `SqlConnector` trait + dialect enum for backend-agnostic SQL toolkits.
- `builder_ext` — `ServerBuilderExt` trait adding `tools_from_config` / `code_mode_from_config` to `pmcp::ServerBuilder`.
- `code_mode` *(feature `code-mode`, default-on)* — re-exports from `pmcp-code-mode` plus toolkit-side wiring (`executor_from_config`, `assemble_code_mode_prompt`).
- `http` *(feature `http`)* — OpenAPI/REST backend connector + outgoing `[backend.auth]` providers (`HttpAuthProvider`), including the `oauth_passthrough` relay.
- `error` — `ToolkitError` enum and the crate-level `Result<T>` alias.

### `oauth_passthrough` trust boundary (WR-04)

The `http` module's `oauth_passthrough` `[backend.auth]` variant relays a **client-controlled** credential into an **operator-controlled** destination, and the trust posture must be explicit:

- The **MCP client controls the forwarded token VALUE** — it is the raw inbound `Authorization` header the client sent, captured by the binary's token-capture provider and forwarded verbatim (a bare token is prefixed with `Bearer `).
- The **operator controls the destination header NAME** — `target_header` is fixed in the committed config; the client cannot redirect the token elsewhere.

Forwarding the client's own credential to the backend is the **intended** SSO-passthrough behavior — use it only when the backend should receive the MCP client's own identity. The `HeaderValue::try_from` control-character rejection is the protection against header injection. For a server-side service credential, use a static variant (`bearer` / `oauth2_client_credentials`) instead.

## What this crate is NOT

- **Not a DynamoDB toolkit.** Phase 83 dropped `ddb` / `dynamo-config` from the feature matrix (D-14). Use `pmcp-tasks` for DynamoDB-backed task storage.
- **Not a generic OpenAPI / JavaScript runtime.** The `openapi-code-mode`, `js-runtime`, and `mcp-code-mode` features stay in `pmcp-code-mode` and are not re-exported via the toolkit (D-14).
- **Not WASM-ready in 0.1.0.** No `wasm32-*` target support yet — Phase 83 RESEARCH §"Open Questions" #3 defers WASM until Phase 84+.

## Quickstart

The eventual Shape C target is a ~15-line `main.rs` that loads a config TOML and ships a working MCP server with synthesized tools, static prompts/resources, and code-mode wiring. Phase 86 owns the runnable example; until then the API sketch is:

```rust,ignore
use pmcp::ServerBuilder;
use pmcp_server_toolkit::{builder_ext::ServerBuilderExt, config::ServerConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ServerConfig::from_toml_path("config.toml")?;
    let server = ServerBuilder::new()
        .tools_from_config(&config)?
        .code_mode_from_config(&config)?
        .build();
    server.serve_stdio().await
}
```

## Design context

For the architectural responsibility map, review notes, and locked decisions, see [`.claude/skills/spike-findings-rust-mcp-sdk/SKILL.md`](../../.claude/skills/spike-findings-rust-mcp-sdk/SKILL.md) and the `.planning/phases/83-toolkit-core-lift-pmcp-server-toolkit/` design log.