@yawlabs/mcp 0.58.0 → 0.58.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +140 -133
- package/dist/chunk-C3WU6HAG.js +381 -0
- package/dist/index.js +366 -641
- package/dist/team-sync-4JF5LBRB.js +31 -0
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -1,15 +1,17 @@
|
|
|
1
|
-
# @yawlabs/
|
|
1
|
+
# @yawlabs/mcp
|
|
2
2
|
|
|
3
3
|
One install. All your MCP servers. Managed from the cloud.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Yaw MCP (the `yaw-mcp` CLI, package `@yawlabs/mcp`) is an MCP server that fronts every other MCP server you use. Install it once per AI client (Claude Code, Claude Desktop, Cursor, VS Code) and your servers come from your [yaw.sh/mcp](https://yaw.sh/mcp) account instead of a hand-edited `mcpServers` block. It earns its keep when you hit any of these:
|
|
6
6
|
|
|
7
7
|
- **More than one client or more than one machine.** Add a server once on the dashboard; every client/device picks it up on the next poll. No copy-paste of the same JSON into four config files, no per-machine drift.
|
|
8
8
|
- **Tool-context bloat.** The `dispatch` meta-tool ranks your installed servers against the task at hand and loads only the top match(es). A 30-server account stays at a handful of tools in context at any moment instead of surfacing hundreds by default.
|
|
9
|
-
- **API tokens you'd rather not sit in disk configs.** Credentials live encrypted on mcp
|
|
10
|
-
- **A trust signal before you activate.** Every scored server renders with its A
|
|
9
|
+
- **API tokens you'd rather not sit in disk configs.** Credentials live encrypted on yaw.sh/mcp and inject at spawn time. Rotate once -- every client picks up the new value. Revoke the yaw.sh/mcp token and every install stops working.
|
|
10
|
+
- **A trust signal before you activate.** Every scored server renders with its A-F compliance grade in `discover`. Set `YAW_MCP_MIN_COMPLIANCE=B` to refuse anything below.
|
|
11
11
|
|
|
12
|
-
If you use one client on one machine with a handful of servers, `claude mcp add` or hand-editing `mcp.json` is fine
|
|
12
|
+
If you use one client on one machine with a handful of servers, `claude mcp add` or hand-editing `mcp.json` is fine -- yaw-mcp's value shows up when that setup stops scaling.
|
|
13
|
+
|
|
14
|
+
> **Renamed from `@yawlabs/mcph`** (0.58.0). The old binary `mcph`, env-var prefix `MCPH_*`, config dir `~/.mcph/`, and guide file `MCPH.md` are all renamed -- see [CHANGELOG](./CHANGELOG.md) for the full migration list. The `mcph` package is deprecated with a pointer here.
|
|
13
15
|
|
|
14
16
|
## How it works
|
|
15
17
|
|
|
@@ -18,76 +20,78 @@ Your MCP client (Claude Code, Cursor, etc.)
|
|
|
18
20
|
|
|
|
19
21
|
| single stdio connection
|
|
20
22
|
v
|
|
21
|
-
@yawlabs/
|
|
23
|
+
@yawlabs/mcp
|
|
22
24
|
| | |
|
|
23
25
|
v v v
|
|
24
|
-
GitHub Slack Stripe
|
|
26
|
+
GitHub Slack Stripe <- your MCP servers (local or remote)
|
|
25
27
|
```
|
|
26
28
|
|
|
27
|
-
1. You add servers on [mcp
|
|
28
|
-
2.
|
|
29
|
+
1. You add servers on [yaw.sh/mcp](https://yaw.sh/mcp) (name, command, args, env vars)
|
|
30
|
+
2. yaw-mcp pulls your config on startup
|
|
29
31
|
3. You use a handful of meta-tools to control which servers' tools are loaded in the current session:
|
|
30
|
-
- **`mcp_connect_dispatch`**
|
|
31
|
-
- **`mcp_connect_discover`**
|
|
32
|
-
- **`mcp_connect_activate`**
|
|
33
|
-
- **`mcp_connect_deactivate`**
|
|
34
|
-
- **`mcp_connect_install`**
|
|
35
|
-
- **`mcp_connect_import`**
|
|
36
|
-
- **`mcp_connect_health`**
|
|
37
|
-
- **`mcp_connect_suggest`**
|
|
38
|
-
- **`mcp_connect_read_tool`**
|
|
39
|
-
- **`mcp_connect_exec`**
|
|
40
|
-
- **`mcp_connect_bundles`**
|
|
32
|
+
- **`mcp_connect_dispatch`** -- describe a task in plain English; yaw-mcp picks the right server, loads its tools, and exposes them. The fast path when you know what you want.
|
|
33
|
+
- **`mcp_connect_discover`** -- list all installed servers, optionally ranked by relevance to a context string. Auto-loads the top match when one server clearly wins.
|
|
34
|
+
- **`mcp_connect_activate`** -- load specific servers' tools by namespace.
|
|
35
|
+
- **`mcp_connect_deactivate`** -- unload a server and remove its tools from context.
|
|
36
|
+
- **`mcp_connect_install`** -- install a new MCP server on your yaw.sh/mcp account.
|
|
37
|
+
- **`mcp_connect_import`** -- bulk-import servers from an existing client config (`claude_desktop_config.json`, `mcp.json`, etc.).
|
|
38
|
+
- **`mcp_connect_health`** -- show call counts, error rates, and latency per loaded server.
|
|
39
|
+
- **`mcp_connect_suggest`** -- surface recurring multi-server workflows yaw-mcp has learned from persisted pack history. When you repeatedly use `gh` -> `linear` -> `slack` for the same kind of task, `suggest` lists the pattern with a ready-to-run `activate` call so you can load the whole pack at once.
|
|
40
|
+
- **`mcp_connect_read_tool`** -- return a single tool's schema + docs without activating its server. Reads 1-2 schemas instead of loading a whole catalog when the model only needs a couple of tools from a big server.
|
|
41
|
+
- **`mcp_connect_exec`** -- run a short declarative pipeline of tool calls in one round-trip. Steps name namespaced tools + args; `{"$ref": "<stepId>[.path]"}` markers splice prior outputs into later inputs. No eval -- only dot/bracket path resolution. Capped at 16 steps.
|
|
42
|
+
- **`mcp_connect_bundles`** -- list curated multi-server presets (DevOps incident, PR review, growth stack, data ops, etc.) and/or match them against your current config. Pair it with `mcp_connect_activate` to load a whole bundle at once.
|
|
41
43
|
|
|
42
|
-
Installing a server puts it on your account; loading it brings its tools into the current session's context.
|
|
44
|
+
Installing a server puts it on your account; loading it brings its tools into the current session's context. yaw-mcp loads servers lazily so your context window stays clean.
|
|
43
45
|
|
|
44
|
-
Ranking is two-stage when the backend has a Voyage embeddings key configured: a local BM25 pass narrows to a shortlist, then a `/api/connect/rerank` call semantically reorders. With no key on the backend it gracefully degrades to BM25-only
|
|
46
|
+
Ranking is two-stage when the backend has a Voyage embeddings key configured: a local BM25 pass narrows to a shortlist, then a `/api/connect/rerank` call semantically reorders. With no key on the backend it gracefully degrades to BM25-only -- `dispatch` and `discover(context)` keep working, just with slightly weaker ranking on ambiguous queries.
|
|
45
47
|
|
|
46
|
-
On top of the ranker,
|
|
48
|
+
On top of the ranker, yaw-mcp applies three client-side signals to dispatch scores:
|
|
47
49
|
|
|
48
|
-
- **Health-aware**: servers that have recently failed to load or have high error rates get down-ranked. Never boosts above raw
|
|
49
|
-
- **Learning**: servers that have succeeded before get a small (+10% max) nudge, so the router remembers what's been useful. Success counts persist across restarts via `~/.
|
|
50
|
-
- **Sampling tiebreak**: when the top two candidates are within 10% of each other and your client supports [MCP sampling](https://modelcontextprotocol.io/specification/server/sampling),
|
|
50
|
+
- **Health-aware**: servers that have recently failed to load or have high error rates get down-ranked. Never boosts above raw -- "all else equal, prefer the one that works".
|
|
51
|
+
- **Learning**: servers that have succeeded before get a small (+10% max) nudge, so the router remembers what's been useful. Success counts persist across restarts via `~/.yaw-mcp/state.json` (opt out with `YAW_MCP_DISABLE_PERSISTENCE=1`).
|
|
52
|
+
- **Sampling tiebreak**: when the top two candidates are within 10% of each other and your client supports [MCP sampling](https://modelcontextprotocol.io/specification/server/sampling), yaw-mcp asks your client's LLM to pick. Uses the model you're already running -- no extra provider key, no extra cost to yaw-mcp.
|
|
51
53
|
|
|
52
54
|
## Install
|
|
53
55
|
|
|
54
56
|
### One command (recommended)
|
|
55
57
|
|
|
56
58
|
```bash
|
|
57
|
-
npx -y @yawlabs/
|
|
59
|
+
npx -y @yawlabs/mcp@latest install <claude-code|claude-desktop|cursor|vscode> --token mcp_pat_your_token_here
|
|
58
60
|
```
|
|
59
61
|
|
|
60
62
|
This:
|
|
61
63
|
|
|
62
|
-
1. Edits the chosen client's config file (correct path for your OS, correct JSON shape) to launch
|
|
63
|
-
2. Writes your token to `~/.
|
|
64
|
+
1. Edits the chosen client's config file (correct path for your OS, correct JSON shape) to launch yaw-mcp.
|
|
65
|
+
2. Writes your token to `~/.yaw-mcp/config.json` so every other client you install picks it up automatically -- no need to copy the token into each client's `env` block.
|
|
64
66
|
3. On Windows, wraps `npx` in `cmd /c` (without this, MCP clients hit `ENOENT` on the `npx.cmd` shim).
|
|
65
67
|
|
|
66
|
-
Run it once per client. To rotate the token later, run `install` again with `--token`
|
|
68
|
+
Run it once per client. To rotate the token later, run `install` again with `--token` -- both files get rewritten.
|
|
67
69
|
|
|
68
70
|
Helpful flags:
|
|
69
71
|
|
|
70
|
-
- `--scope user|project|local`
|
|
71
|
-
- `--dry-run`
|
|
72
|
-
- `--force` / `--skip`
|
|
73
|
-
- `--no-
|
|
72
|
+
- `--scope user|project|local` -- which file to write (Claude Code + Cursor support project/local; VS Code is workspace-only; Claude Desktop is user-only).
|
|
73
|
+
- `--dry-run` -- print the diff and exit without writing.
|
|
74
|
+
- `--force` / `--skip` -- overwrite or leave an existing `mcp.hosting` entry. Without either, yaw-mcp prompts (TTY) or refuses (non-TTY).
|
|
75
|
+
- `--no-yaw-mcp-config` -- write only the client config; leave `~/.yaw-mcp/config.json` untouched.
|
|
74
76
|
|
|
75
77
|
Or install into every detected client at once:
|
|
76
78
|
|
|
77
79
|
```bash
|
|
78
|
-
|
|
79
|
-
|
|
80
|
+
yaw-mcp install --list # read-only: detect clients + show install state per scope
|
|
81
|
+
yaw-mcp install --all --token mcp_pat_... # one-shot: install into every user-scope client on this machine
|
|
80
82
|
```
|
|
81
83
|
|
|
82
|
-
`--list` never writes (no token needed). `--all` installs into every client whose user-scope target is resolvable on this OS
|
|
84
|
+
`--list` never writes (no token needed). `--all` installs into every client whose user-scope target is resolvable on this OS -- Claude Desktop is skipped on Linux, VS Code is skipped unless `--project-dir` is given (it's workspace-only). Aggregate exit code is non-zero if any sub-install fails.
|
|
83
85
|
|
|
84
86
|
Or [edit the JSON by hand](#manual-install) if you'd rather.
|
|
85
87
|
|
|
86
|
-
|
|
88
|
+
> The launch entry written into each client's config is still keyed as `"mcp.hosting"` for backwards compatibility with existing installs. The CLI, package, env vars, and config dir all moved to `yaw-mcp`; the JSON key is the one user-visible thing that didn't.
|
|
89
|
+
|
|
90
|
+
### Diagnose problems -- `yaw-mcp doctor`
|
|
87
91
|
|
|
88
92
|
```bash
|
|
89
|
-
npx -y @yawlabs/
|
|
90
|
-
npx -y @yawlabs/
|
|
93
|
+
npx -y @yawlabs/mcp@latest doctor # human-readable report
|
|
94
|
+
npx -y @yawlabs/mcp@latest doctor --json # machine-readable snapshot for pipelines
|
|
91
95
|
```
|
|
92
96
|
|
|
93
97
|
Prints the loaded config files, your token's source + fingerprint (last 4 chars), the API base URL, installed clients, env overrides, persisted learning state, flaky-namespace reliability rollup, shell-history "shadow" hits (CLIs you run that an MCP server could replace), and an upgrade check against the npm registry. Exits `0` healthy / `1` no token / `2` warnings (e.g. world-readable token file). Paste the text output into a support ticket; the `--json` blob is the same data as a structured snapshot, so dashboards and CI scripts can `jq` instead of parsing the text layout.
|
|
@@ -95,73 +99,73 @@ Prints the loaded config files, your token's source + fingerprint (last 4 chars)
|
|
|
95
99
|
### Other CLI subcommands
|
|
96
100
|
|
|
97
101
|
```bash
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
102
|
+
yaw-mcp servers [<namespace-filter>] [--json] # list servers; optional substring filter on namespace
|
|
103
|
+
yaw-mcp bundles [list|match] [--json] # browse curated multi-server bundles (PR review, DevOps incident, etc.)
|
|
104
|
+
yaw-mcp reset-learning # clear cross-session learning history (~/.yaw-mcp/state.json)
|
|
105
|
+
yaw-mcp completion <bash|zsh|fish|powershell> # print shell completion script
|
|
106
|
+
yaw-mcp upgrade [--run] [--json] # show (or execute) the command that bumps @yawlabs/mcp
|
|
107
|
+
yaw-mcp compliance <target> [--publish] # run the compliance suite against an MCP server
|
|
108
|
+
yaw-mcp --version # print version
|
|
105
109
|
```
|
|
106
110
|
|
|
107
|
-
Every CLI that reads state has a `--json` mode for pipeline use. `
|
|
111
|
+
Every CLI that reads state has a `--json` mode for pipeline use. `yaw-mcp servers` hits the backend; `yaw-mcp bundles list` and `yaw-mcp completion` are fully static (no network, no token). `yaw-mcp bundles match` partitions the curated set against your enabled servers so you see the same ready-to-activate vs. partially-installed view the LLM-facing `mcp_connect_bundles` meta-tool produces.
|
|
108
112
|
|
|
109
113
|
To wire up shell completion:
|
|
110
114
|
|
|
111
115
|
```bash
|
|
112
116
|
# bash
|
|
113
|
-
|
|
117
|
+
yaw-mcp completion bash > ~/.local/share/bash-completion/completions/yaw-mcp
|
|
114
118
|
|
|
115
119
|
# zsh (must be on $fpath, then rebuild compinit)
|
|
116
|
-
|
|
120
|
+
yaw-mcp completion zsh > "${fpath[1]}/_yaw-mcp"
|
|
117
121
|
|
|
118
122
|
# fish
|
|
119
|
-
|
|
123
|
+
yaw-mcp completion fish > ~/.config/fish/completions/yaw-mcp.fish
|
|
120
124
|
|
|
121
125
|
# powershell
|
|
122
|
-
|
|
126
|
+
yaw-mcp completion powershell >> $PROFILE
|
|
123
127
|
```
|
|
124
128
|
|
|
125
129
|
### Getting your token
|
|
126
130
|
|
|
127
|
-
1. Sign up at [mcp
|
|
128
|
-
2. Go to **Settings >
|
|
129
|
-
3. Create a token
|
|
130
|
-
4. Pass it to `
|
|
131
|
+
1. Sign up at [yaw.sh/mcp](https://yaw.sh/mcp)
|
|
132
|
+
2. Go to **Settings > Tokens**
|
|
133
|
+
3. Create a token -- it starts with `mcp_pat_`
|
|
134
|
+
4. Pass it to `yaw-mcp install` as shown above
|
|
131
135
|
|
|
132
136
|
### Manual install
|
|
133
137
|
|
|
134
138
|
If you'd rather edit the config files yourself, the JSON shapes are:
|
|
135
139
|
|
|
136
|
-
**Claude Code, Cursor, Claude Desktop**
|
|
140
|
+
**Claude Code, Cursor, Claude Desktop** -- top-level key `mcpServers`:
|
|
137
141
|
|
|
138
142
|
```json
|
|
139
143
|
{
|
|
140
144
|
"mcpServers": {
|
|
141
145
|
"mcp.hosting": {
|
|
142
146
|
"command": "npx",
|
|
143
|
-
"args": ["-y", "@yawlabs/
|
|
147
|
+
"args": ["-y", "@yawlabs/mcp@latest"]
|
|
144
148
|
}
|
|
145
149
|
}
|
|
146
150
|
}
|
|
147
151
|
```
|
|
148
152
|
|
|
149
|
-
**VS Code**
|
|
153
|
+
**VS Code** -- top-level key `servers` (NOT `mcpServers`) in `.vscode/mcp.json`:
|
|
150
154
|
|
|
151
155
|
```json
|
|
152
156
|
{
|
|
153
157
|
"servers": {
|
|
154
158
|
"mcp.hosting": {
|
|
155
159
|
"command": "npx",
|
|
156
|
-
"args": ["-y", "@yawlabs/
|
|
160
|
+
"args": ["-y", "@yawlabs/mcp@latest"]
|
|
157
161
|
}
|
|
158
162
|
}
|
|
159
163
|
}
|
|
160
164
|
```
|
|
161
165
|
|
|
162
|
-
**Windows**
|
|
166
|
+
**Windows** -- `command: "cmd", args: ["/c", "npx", "-y", "@yawlabs/mcp@latest"]` (the `cmd /c` wrapper is required because `npx.cmd` is a shim).
|
|
163
167
|
|
|
164
|
-
Then put your token in `~/.
|
|
168
|
+
Then put your token in `~/.yaw-mcp/config.json` so yaw-mcp picks it up at startup:
|
|
165
169
|
|
|
166
170
|
```json
|
|
167
171
|
{
|
|
@@ -170,11 +174,11 @@ Then put your token in `~/.mcph/config.json` so mcph picks it up at startup:
|
|
|
170
174
|
}
|
|
171
175
|
```
|
|
172
176
|
|
|
173
|
-
Or set `
|
|
177
|
+
Or set `YAW_MCP_TOKEN` in the client's `env` block -- both work.
|
|
174
178
|
|
|
175
179
|
## Adding servers
|
|
176
180
|
|
|
177
|
-
On [mcp
|
|
181
|
+
On [yaw.sh/mcp](https://yaw.sh/mcp), add each MCP server you want to orchestrate:
|
|
178
182
|
|
|
179
183
|
| Field | Description |
|
|
180
184
|
|-------|-------------|
|
|
@@ -188,7 +192,7 @@ On [mcp.hosting](https://mcp.hosting), add each MCP server you want to orchestra
|
|
|
188
192
|
|
|
189
193
|
## Usage
|
|
190
194
|
|
|
191
|
-
### Fast path
|
|
195
|
+
### Fast path -- `dispatch`
|
|
192
196
|
|
|
193
197
|
When you know what you want to do, skip the discover/load dance:
|
|
194
198
|
|
|
@@ -197,8 +201,8 @@ When you know what you want to do, skip the discover/load dance:
|
|
|
197
201
|
|
|
198
202
|
[mcp_connect_dispatch is called with intent="create a GitHub issue for the login bug"]
|
|
199
203
|
|
|
200
|
-
Dispatched "create a GitHub issue for the login bug"
|
|
201
|
-
gh (score 4.32): Loaded "gh"
|
|
204
|
+
Dispatched "create a GitHub issue for the login bug" -- loaded top 1 of 1 matching server.
|
|
205
|
+
gh (score 4.32): Loaded "gh" -- 24 tools: gh_create_issue, gh_list_prs, ...
|
|
202
206
|
|
|
203
207
|
[gh_create_issue is then called, returns the new issue]
|
|
204
208
|
```
|
|
@@ -212,9 +216,9 @@ gh (score 4.32): Loaded "gh" — 24 tools: gh_create_issue, gh_list_prs, ...
|
|
|
212
216
|
|
|
213
217
|
Installed MCP servers:
|
|
214
218
|
|
|
215
|
-
gh
|
|
216
|
-
slack
|
|
217
|
-
stripe
|
|
219
|
+
gh -- GitHub [ready] (local)
|
|
220
|
+
slack -- Slack [ready] (local)
|
|
221
|
+
stripe -- Stripe [ready] (local)
|
|
218
222
|
|
|
219
223
|
0 loaded in this session, 0 tools in context.
|
|
220
224
|
```
|
|
@@ -222,7 +226,7 @@ Installed MCP servers:
|
|
|
222
226
|
```
|
|
223
227
|
> Load my GitHub server
|
|
224
228
|
|
|
225
|
-
Loaded "gh"
|
|
229
|
+
Loaded "gh" -- 24 tools: gh_create_issue, gh_list_prs, ...
|
|
226
230
|
```
|
|
227
231
|
|
|
228
232
|
You can load multiple at once: `> Load GitHub and Slack`. Tools are namespaced as `{namespace}_{original_tool_name}` to prevent collisions. The tool list updates automatically via `tools/list_changed`.
|
|
@@ -235,34 +239,34 @@ Unloaded "gh". Tools removed from context.
|
|
|
235
239
|
|
|
236
240
|
Servers also auto-unload after ~10 tool calls to other servers, so context stays clean even if you forget. The threshold is adaptive per-namespace: a server that's been called in bursts recently gets more patience (up to +20) before it's unloaded, so heavily-used servers don't get torn down mid-task. Long-idle servers still unload at the baseline.
|
|
237
241
|
|
|
238
|
-
## `.
|
|
242
|
+
## `.yaw-mcp/` config directory
|
|
239
243
|
|
|
240
|
-
|
|
244
|
+
yaw-mcp stores its config under a `.yaw-mcp/` directory -- mirroring the `.git/`, `.vscode/`, `.claude/` convention so everything related to yaw-mcp (config, project guide, future additions) lives under one predictable folder you can grep, gitignore, or blow away atomically. yaw-mcp reads `config.json` from three optional locations (highest precedence first):
|
|
241
245
|
|
|
242
246
|
| Scope | Path | Holds |
|
|
243
247
|
|-------|------|-------|
|
|
244
|
-
| **local** | `<project>/.
|
|
245
|
-
| **project** | `<project>/.
|
|
246
|
-
| **global** | `~/.
|
|
248
|
+
| **local** | `<project>/.yaw-mcp/config.local.json` | Machine-local override; `gitignore` it. Token allowed. |
|
|
249
|
+
| **project** | `<project>/.yaw-mcp/config.json` | Shared with the team via git. Token NOT allowed (warned). |
|
|
250
|
+
| **global** | `~/.yaw-mcp/config.json` | Personal default for every project. Token allowed. |
|
|
247
251
|
|
|
248
|
-
The project `.
|
|
252
|
+
The project `.yaw-mcp/` is found by walking UP from the current directory until a `.yaw-mcp/` is found, stopping just before `$HOME` (exclusive) so a `.yaw-mcp/` sitting at `$HOME` is treated as user-global only and never double-loaded as project.
|
|
249
253
|
|
|
250
254
|
Full schema:
|
|
251
255
|
|
|
252
256
|
```jsonc
|
|
253
257
|
{
|
|
254
|
-
// Schema version.
|
|
255
|
-
// readable. Newer versions log a warning so an old
|
|
256
|
-
// miss new fields.
|
|
258
|
+
// Schema version. yaw-mcp emits version 1; older fields stay
|
|
259
|
+
// readable. Newer versions log a warning so an old yaw-mcp can't
|
|
260
|
+
// silently miss new fields.
|
|
257
261
|
"version": 1,
|
|
258
262
|
|
|
259
|
-
// Personal access token from mcp
|
|
260
|
-
// env
|
|
263
|
+
// Personal access token from yaw.sh/mcp -> Settings -> Tokens.
|
|
264
|
+
// env YAW_MCP_TOKEN still wins over the file value.
|
|
261
265
|
"token": "mcp_pat_your_token_here",
|
|
262
266
|
|
|
263
|
-
// API base override
|
|
264
|
-
// Defaults to https://mcp.
|
|
265
|
-
"apiBase": "https://mcp
|
|
267
|
+
// API base override -- point yaw-mcp at a self-hosted backend or staging.
|
|
268
|
+
// Defaults to https://yaw.sh/mcp. env YAW_MCP_URL still wins.
|
|
269
|
+
"apiBase": "https://yaw.sh/mcp",
|
|
266
270
|
|
|
267
271
|
// Project profile: which namespaces are allowed.
|
|
268
272
|
"servers": ["gh", "pg", "linear"],
|
|
@@ -272,106 +276,109 @@ Full schema:
|
|
|
272
276
|
}
|
|
273
277
|
```
|
|
274
278
|
|
|
275
|
-
**Comments are allowed** (line `//` and block `/*
|
|
279
|
+
**Comments are allowed** (line `//` and block `/* ... */`) -- handy for documenting a shared `config.json` checked into git.
|
|
276
280
|
|
|
277
281
|
**Resolution:**
|
|
278
282
|
|
|
279
|
-
- **Token**
|
|
280
|
-
- **apiBase**
|
|
281
|
-
- **servers** allow-list
|
|
282
|
-
- **blocked** deny-list
|
|
283
|
-
- Malformed files log a warning and fall through
|
|
284
|
-
- On POSIX,
|
|
283
|
+
- **Token** -- `YAW_MCP_TOKEN` env > local > global. (`token` in the project file is ignored and warned: it'd get committed to git.)
|
|
284
|
+
- **apiBase** -- `YAW_MCP_URL` env > local > project > global > `https://yaw.sh/mcp`.
|
|
285
|
+
- **servers** allow-list -- local wins if set, else project, else global (most-specific scope overrides).
|
|
286
|
+
- **blocked** deny-list -- UNION across every scope that sets it (fail-safe on deny).
|
|
287
|
+
- Malformed files log a warning and fall through -- fail-open so a typo doesn't brick the session.
|
|
288
|
+
- On POSIX, yaw-mcp warns if the file contains a token and is readable by group/other; run `chmod 600 ~/.yaw-mcp/config.json` to silence it.
|
|
285
289
|
|
|
286
|
-
**Token rotation**:
|
|
290
|
+
**Token rotation**: yaw-mcp reads its config at startup. After editing `~/.yaw-mcp/config.json`, restart the MCP client (or kill yaw-mcp; the client respawns it).
|
|
287
291
|
|
|
288
292
|
`mcp_connect_health` shows which file(s) are currently applied.
|
|
289
293
|
|
|
290
|
-
## Project guide
|
|
294
|
+
## Project guide -- `YAW-MCP.md`
|
|
291
295
|
|
|
292
|
-
Drop a `
|
|
296
|
+
Drop a `YAW-MCP.md` next to `config.json` inside either `.yaw-mcp/` and yaw-mcp surfaces its contents to your client via a `yaw-mcp://guide` MCP resource. The meta-tool descriptions (`discover`, `dispatch`) tell the model to read this resource first, so project-specific routing conventions ("use the `gh` server for GitHub, not bash") and credential guidance ("keys go in the dashboard, not `.mcp.json`") stick without the user restating them every session.
|
|
293
297
|
|
|
294
298
|
| Scope | Path | Purpose |
|
|
295
299
|
|-------|------|---------|
|
|
296
|
-
| **user** | `~/.
|
|
297
|
-
| **project** | `<project>/.
|
|
300
|
+
| **user** | `~/.yaw-mcp/YAW-MCP.md` | Personal defaults that apply everywhere (your preferred tools, credential conventions). |
|
|
301
|
+
| **project** | `<project>/.yaw-mcp/YAW-MCP.md` | Project-specific guidance shared via git (which servers are load-bearing, project idioms). |
|
|
298
302
|
|
|
299
|
-
When both exist, the project guide is appended after the user guide with a `---` separator so project-specific rules get the final word in the reader's attention. A missing or empty file is silently skipped
|
|
303
|
+
When both exist, the project guide is appended after the user guide with a `---` separator so project-specific rules get the final word in the reader's attention. A missing or empty file is silently skipped -- if neither file exists, the `yaw-mcp://guide` resource isn't listed at all.
|
|
300
304
|
|
|
301
305
|
## Elicitation for missing credentials
|
|
302
306
|
|
|
303
|
-
When a server fails to start with stderr like `GITHUB_TOKEN is required` and your client advertises the MCP [elicitation](https://modelcontextprotocol.io/specification/server/elicitation) capability,
|
|
307
|
+
When a server fails to start with stderr like `GITHUB_TOKEN is required` and your client advertises the MCP [elicitation](https://modelcontextprotocol.io/specification/server/elicitation) capability, yaw-mcp prompts you for the missing value inline and retries the load. Values stay in-memory for the current yaw-mcp session only -- persist them in the yaw.sh/mcp dashboard if you want them across restarts.
|
|
304
308
|
|
|
305
309
|
### Errors come with deep-links
|
|
306
310
|
|
|
307
|
-
When a load fails (missing token, runtime not on PATH, server crashes on init),
|
|
311
|
+
When a load fails (missing token, runtime not on PATH, server crashes on init), yaw-mcp emits a message ending with `-> Edit at https://yaw.sh/mcp/dashboard/connect#server-<id>`. Most LLMs render that as a clickable link, and the dashboard scrolls to and highlights the matching card so you find the right server in one click.
|
|
308
312
|
|
|
309
313
|
## Config sync
|
|
310
314
|
|
|
311
|
-
|
|
315
|
+
yaw-mcp polls [yaw.sh/mcp](https://yaw.sh/mcp) every 60 seconds for config changes. When you add, remove, or modify a server on the dashboard, yaw-mcp picks it up automatically -- no restart needed.
|
|
312
316
|
|
|
313
317
|
### Multi-device sync
|
|
314
318
|
|
|
315
|
-
Because every
|
|
319
|
+
Because every yaw-mcp install reads the same account's server list, the same token gives you the same servers across every machine. Install yaw-mcp on a second laptop with the same `mcp_pat_...`, and within 60 seconds it sees the same GitHub/Slack/Stripe/etc. servers you configured from the first. Tokens, environment variables, and credentials stay in the dashboard -- you don't have to sync a JSON file across machines, copy secrets into a dotfile repo, or re-paste an API key per device.
|
|
316
320
|
|
|
317
|
-
Rotate a credential in one place (the dashboard), every machine picks up the new value on the next poll. Revoke a token in Settings
|
|
321
|
+
Rotate a credential in one place (the dashboard), every machine picks up the new value on the next poll. Revoke a token in Settings -> Tokens, every install stops working immediately (the token is the only thing authenticating the config pull). This is why `~/.yaw-mcp/config.json` holds a token, not a server list -- the server list is the cloud's concern.
|
|
318
322
|
|
|
319
323
|
## Environment variables
|
|
320
324
|
|
|
321
325
|
| Variable | Required | Description |
|
|
322
326
|
|----------|----------|-------------|
|
|
323
|
-
| `
|
|
324
|
-
| `
|
|
327
|
+
| `YAW_MCP_TOKEN` | Yes (or in `~/.yaw-mcp/config.json`) | Personal access token from yaw.sh/mcp. Env wins over `~/.yaw-mcp/config.json`. |
|
|
328
|
+
| `YAW_MCP_URL` | No | API URL (default: `https://yaw.sh/mcp`). Env wins over `apiBase` in `config.json`. |
|
|
325
329
|
| `LOG_LEVEL` | No | Log verbosity: `debug`, `info`, `warn`, `error` (default: `info`) |
|
|
326
|
-
| `
|
|
327
|
-
| `
|
|
328
|
-
| `
|
|
329
|
-
| `
|
|
330
|
-
| `
|
|
331
|
-
| `
|
|
332
|
-
| `
|
|
330
|
+
| `YAW_MCP_POLL_INTERVAL` | No | Config-poll interval in seconds. `0` disables polling (config fetched once at startup). Default: `60` |
|
|
331
|
+
| `YAW_MCP_AUTO_ACTIVATE` | No | When `discover` is called with a context string and one server clearly wins, auto-load it. Set to `0` to disable. Default: enabled |
|
|
332
|
+
| `YAW_MCP_AUTO_UPGRADE` | No | When yaw-mcp starts as a server, runs a non-blocking background check for a newer global-npm install and upgrades quietly. Set to `0` to disable. Default: enabled. |
|
|
333
|
+
| `YAW_MCP_SERVER_CAP` | No | Hard cap on concurrently activated servers. Default: `6`. Set to `0` to disable. |
|
|
334
|
+
| `YAW_MCP_PRUNE_RESPONSES` | No | Conservative response pruning (redact large file blobs etc. before returning to the client). Set to `0` or `false` to disable. Default: enabled. |
|
|
335
|
+
| `YAW_MCP_DISABLE_PERSISTENCE` | No | Set to `1` or `true` to keep learning + pack-history scoped to the current process -- nothing loaded at start, nothing written on shutdown. Intended for ephemeral / shared environments (CI, containers). Default: cross-session persistence enabled at `~/.yaw-mcp/state.json`. |
|
|
336
|
+
| `YAW_MCP_AUTO_LOAD` | No | Set to `1` or `true` to pre-activate the top recurring pack (from persisted pack-history) on startup -- no LLM round-trip required. Skips silently when history is empty or no pack's namespaces are all installed. Default: off. Requires persistence to be enabled. |
|
|
337
|
+
| `YAW_MCP_MIN_COMPLIANCE` | No | Minimum compliance grade (`A`, `B`, `C`, `D`, or `F`, case-insensitive) an installed server must report before `mcp_connect_activate` will load it. Ungraded servers always pass (don't punish unknown). `discover()` annotates below-grade servers in place and shows a "Compliance filter active" header when set. Invalid values log a warning and disable the filter. Default: unset (no filter). |
|
|
333
338
|
| `MCP_CONNECT_TIMEOUT` | No | Connection timeout in ms for upstream servers (default: `15000`) |
|
|
334
|
-
| `MCP_CONNECT_IDLE_THRESHOLD` | No | Baseline for idle auto-unload (default: `10`). The per-namespace adaptive cap is `[5, 50]`
|
|
339
|
+
| `MCP_CONNECT_IDLE_THRESHOLD` | No | Baseline for idle auto-unload (default: `10`). The per-namespace adaptive cap is `[5, 50]` -- bursty namespaces extend past the baseline, long-idle ones unload at it. |
|
|
340
|
+
|
|
341
|
+
> Legacy `MCPH_*` env vars are no longer read. If a script still sets `MCPH_TOKEN`, rename it to `YAW_MCP_TOKEN`. The migration is in [CHANGELOG](./CHANGELOG.md) under 0.58.0.
|
|
335
342
|
|
|
336
343
|
## Runtime detection
|
|
337
344
|
|
|
338
|
-
On startup,
|
|
345
|
+
On startup, yaw-mcp probes your machine for `node`, `npx`, `python`, `uvx`, and `docker` and reports the snapshot to yaw.sh/mcp. The dashboard uses this to warn before you add a catalog server whose runtime isn't installed (e.g., adding the Sentry server when Python isn't on your PATH). No prompt, no LLM round-trip -- just a yellow banner on the Add Server form.
|
|
339
346
|
|
|
340
|
-
The detection is best-effort: each probe has a 3-second timeout and missing runtimes are recorded as absent rather than blocking startup.
|
|
347
|
+
The detection is best-effort: each probe has a 3-second timeout and missing runtimes are recorded as absent rather than blocking startup. yaw-mcp itself only requires Node.js -- every other runtime is optional and only matters for servers that need it.
|
|
341
348
|
|
|
342
349
|
### Automatic `uv` bootstrap
|
|
343
350
|
|
|
344
|
-
The popular Python-based MCP servers (`sqlite`, `time`, `sentry`, and other uvx-launched entries) all launch via Astral's `uv`/`uvx`.
|
|
351
|
+
The popular Python-based MCP servers (`sqlite`, `time`, `sentry`, and other uvx-launched entries) all launch via Astral's `uv`/`uvx`. yaw-mcp ships its own bootstrap for these: on first encounter with a `uv`/`uvx` command, if the binary isn't on your PATH, yaw-mcp lazily downloads Astral's standalone `uv` release, verifies the sha256, and caches it under the platform-appropriate cache dir. Subsequent loads reuse the cached binary. If you already have `uv` installed, yaw-mcp uses your version and never downloads.
|
|
345
352
|
|
|
346
|
-
`uvx ARGS` is always rewritten to `uv tool run ARGS` at spawn time
|
|
353
|
+
`uvx ARGS` is always rewritten to `uv tool run ARGS` at spawn time -- so only `uv` needs to be reachable, not `uvx` separately. Fixes Windows setups where one was on PATH and the other wasn't.
|
|
347
354
|
|
|
348
355
|
## Trust & security
|
|
349
356
|
|
|
350
|
-
MCP servers are third-party code that you choose to run, and
|
|
357
|
+
MCP servers are third-party code that you choose to run, and yaw-mcp launches them on your machine or calls them over the network. We don't sandbox arbitrary code and we're not an antivirus -- that's your OS and network. What yaw-mcp gives you is **visibility and a gate**:
|
|
351
358
|
|
|
352
|
-
- **Compliance grades (A
|
|
353
|
-
- **Source transparency**
|
|
354
|
-
- **Credentials stay encrypted at rest on mcp
|
|
355
|
-
- **Response pruning**
|
|
356
|
-
- **Namespace isolation**
|
|
359
|
+
- **Compliance grades (A-F)** -- the `@yawlabs/mcp-compliance` suite runs 88 behavioral tests against an MCP server and reports a grade. yaw.sh/mcp publishes grades for catalog servers; `yaw-mcp servers` shows them, and `mcp_connect_discover` surfaces them inline on every listing (e.g., `github -- GitHub [ready] [A]`). Set `YAW_MCP_MIN_COMPLIANCE=B` (or any grade) and `mcp_connect_activate` will refuse to load anything below the floor -- the refusal message spells out the grade and the env var to unset. Ungraded servers always pass (don't punish unknown), so audit unknowns yourself with `yaw-mcp compliance <target>` before you rely on them.
|
|
360
|
+
- **Source transparency** -- `yaw-mcp servers` and the yaw.sh/mcp dashboard show the exact `command`, `args`, and `url` each server launches with. Nothing is hidden or wrapped -- if a server is `npx -y @example/foo` you see that, and you can trace it back to npm / GitHub / the remote endpoint before installing.
|
|
361
|
+
- **Credentials stay encrypted at rest on yaw.sh/mcp** -- API tokens and other secrets you paste into a server's `env` block are encrypted on the backend and injected at spawn time. They don't sit in a committed `.env` file or a client config JSON, and they are never logged. Revoke the yaw.sh/mcp token (Settings -> Tokens) and every install loses access on the next poll.
|
|
362
|
+
- **Response pruning** -- `YAW_MCP_PRUNE_RESPONSES` (on by default) redacts large file-blob-shaped content before it reaches your LLM. This cuts the easiest form of cross-server prompt injection (stuffing a giant payload into a tool reply to swamp the model's context) and reduces accidental token burn. Set to `0` to disable.
|
|
363
|
+
- **Namespace isolation** -- tools are namespace-prefixed (`gh_create_issue`, never bare `create_issue`), so a server can't impersonate tools from another server it has no business touching. `mcp_connect_read_tool` lets you inspect a tool's schema without loading its server, so you can decide before any code runs.
|
|
357
364
|
|
|
358
|
-
**What
|
|
365
|
+
**What yaw-mcp does not try to solve.** yaw-mcp does not prevent a server you deliberately installed from doing harmful things inside its own process. It doesn't block outbound network traffic, firewall DNS, analyze source, or pin package hashes. A malicious server you chose to run can call any URL your machine can reach; cross-server prompt injection through tool output is a fundamentally model-layer problem that no orchestrator fully fixes. The defenses that matter for those threats live at the layer below yaw-mcp:
|
|
359
366
|
|
|
360
|
-
- Review the command (`npx -y @scope/pkg`, a remote URL,
|
|
361
|
-
- Run
|
|
362
|
-
- Keep the mcp
|
|
367
|
+
- Review the command (`npx -y @scope/pkg`, a remote URL, ...) before adding a server. If you don't recognize it, run `yaw-mcp compliance <target>` against it first.
|
|
368
|
+
- Run yaw-mcp and its spawned servers under a restricted OS user or inside a container if you're handling sensitive data. yaw-mcp stays out of your sandbox's way -- a restricted user will block egress just like it would for anything else.
|
|
369
|
+
- Keep the yaw.sh/mcp token scoped to the devices that need it. Rotate with `yaw-mcp install <client> --token ...`; every client picks up the new value.
|
|
363
370
|
- Prefer graded servers when the alternatives are otherwise equivalent. A server that can't pass the compliance suite on basic spec conformance is a worse choice than one that does.
|
|
364
371
|
|
|
365
|
-
If you find a security issue in
|
|
372
|
+
If you find a security issue in yaw-mcp itself, report it via [GitHub's private vulnerability reporting](https://github.com/YawLabs/mcp/security/advisories/new) -- details in [`SECURITY.md`](./SECURITY.md).
|
|
366
373
|
|
|
367
374
|
## Requirements
|
|
368
375
|
|
|
369
376
|
- Node.js 18+
|
|
370
|
-
-
|
|
377
|
+
- A [yaw.sh/mcp](https://yaw.sh/mcp) account
|
|
371
378
|
|
|
372
379
|
## Links
|
|
373
380
|
|
|
374
|
-
- [mcp
|
|
375
|
-
- [@yawlabs/mcp-compliance](https://www.npmjs.com/package/@yawlabs/mcp-compliance)
|
|
376
|
-
- [CHANGELOG](./CHANGELOG.md)
|
|
377
|
-
- [GitHub](https://github.com/YawLabs/
|
|
381
|
+
- [yaw.sh/mcp](https://yaw.sh/mcp) -- Dashboard and server management
|
|
382
|
+
- [@yawlabs/mcp-compliance](https://www.npmjs.com/package/@yawlabs/mcp-compliance) -- Test your MCP servers for spec compliance
|
|
383
|
+
- [CHANGELOG](./CHANGELOG.md) -- Release notes (0.58.0 is the rename from `@yawlabs/mcph`)
|
|
384
|
+
- [GitHub](https://github.com/YawLabs/mcp) -- Source code and issues
|