@sammorrowdrums/mcpi-ext 1.0.0 → 1.0.1
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 +402 -217
- package/dist/mcp/client-factory.d.ts +1 -1
- package/dist/mcp/client-factory.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,277 +1,479 @@
|
|
|
1
1
|
# mcpi-ext
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/@sammorrowdrums/mcpi)
|
|
4
3
|
[](https://www.npmjs.com/package/@sammorrowdrums/mcpi-ext)
|
|
4
|
+
[](https://www.npmjs.com/package/@sammorrowdrums/mcpi)
|
|
5
5
|
[](https://www.npmjs.com/package/@sammorrowdrums/tool-cli)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
An extension for [mcpi](https://github.com/SamMorrowDrums/mcpi) that gives an agent three ways to
|
|
8
|
+
reach [MCP](https://modelcontextprotocol.io/) servers — **skills**, **tool-cli**, and **code mode** —
|
|
9
|
+
behind a single authorization boundary, so every call is authorized, audited, and gated in one place.
|
|
10
|
+
|
|
11
|
+
Each mechanism exists to spend only the context tokens a task actually needs. A large MCP server can
|
|
12
|
+
publish hundreds of tools; loading all of their schemas into every request is expensive and degrades
|
|
13
|
+
tool selection. These three mechanisms let the agent discover and call tools progressively instead.
|
|
14
|
+
|
|
15
|
+
- **[Skills](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/skills.md)** — the server
|
|
16
|
+
publishes a documented workflow that unlocks a curated tool set on demand.
|
|
17
|
+
- **[tool-cli](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/tool-cli.md)** — a shell
|
|
18
|
+
on-ramp for progressive discovery: servers → tools → schema → call.
|
|
19
|
+
- **[Code mode](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/code-mode.md)** —
|
|
20
|
+
sandboxed JavaScript that chains read-only tool calls inside a V8 isolate.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Quick start
|
|
25
|
+
|
|
26
|
+
Verified against **mcpi 0.85.0** and **tool-cli 1.0.2** — the current releases, and also the
|
|
27
|
+
minimum supported versions: mcpi-ext declares a peer floor of `@sammorrowdrums/mcpi >=0.85.0
|
|
28
|
+
<1.0.0`, and requires `@sammorrowdrums/tool-cli` v1 for the bridge contract. Any mcpi-ext `1.x`
|
|
29
|
+
works; the commands below pin the current one.
|
|
30
|
+
|
|
31
|
+
### 1. Check Node
|
|
32
|
+
|
|
33
|
+
Node.js `>=22.13.0`. Node 22 and 24 are both covered by CI.
|
|
8
34
|
|
|
9
35
|
```sh
|
|
10
|
-
|
|
11
|
-
mcpi --extension $(npm root -g)/@sammorrowdrums/mcpi-ext/dist/index.js \
|
|
12
|
-
--mcp-config ~/.config/mcpi-ext/mcp.json
|
|
36
|
+
node --version
|
|
13
37
|
```
|
|
14
38
|
|
|
15
|
-
|
|
39
|
+
### 2. Install mcpi and tool-cli globally
|
|
16
40
|
|
|
17
|
-
|
|
41
|
+
`mcpi` and `tool-cli` are commands you run, so they belong on your `PATH`:
|
|
18
42
|
|
|
19
|
-
|
|
43
|
+
```sh
|
|
44
|
+
npm install -g @sammorrowdrums/mcpi@0.85.0 @sammorrowdrums/tool-cli@1.0.2
|
|
45
|
+
```
|
|
20
46
|
|
|
21
|
-
|
|
22
|
-
>
|
|
23
|
-
> _They are wrong._
|
|
24
|
-
>
|
|
25
|
-
> _MCP doesn't have a context problem. It has an imagination problem. The protocol already contains everything you need — `skill://` resources, tool annotations, `outputSchema`, progressive discovery. The pieces are all there, lying in the open like runes on a hillside. You just have to read them._
|
|
26
|
-
>
|
|
27
|
-
> _What follows is the story of three who did._
|
|
47
|
+
To track the newest releases instead of the pinned pair, use `@latest`:
|
|
28
48
|
|
|
29
|
-
|
|
49
|
+
```sh
|
|
50
|
+
npm install -g @sammorrowdrums/mcpi@latest @sammorrowdrums/tool-cli@latest
|
|
51
|
+
```
|
|
30
52
|
|
|
31
|
-
|
|
53
|
+
### 3. Install the extension through mcpi
|
|
32
54
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
| 1 — Skills | **The Skill Dealer** | `skill://` resources gate tools via `allowed-tools` |
|
|
36
|
-
| 2 — tool-cli | **The Nuclear Football** | CLI progressive discovery via shell |
|
|
37
|
-
| 3 — Code Mode | **Codey C. Maude** | Always-on sandboxed JS with read-only MCP dispatch |
|
|
55
|
+
Do **not** install mcpi-ext globally and point `--extension` at it by hand. mcpi manages extension
|
|
56
|
+
packages itself, records them in its settings, and can update them later:
|
|
38
57
|
|
|
39
|
-
|
|
58
|
+
```sh
|
|
59
|
+
mcpi install npm:@sammorrowdrums/mcpi-ext
|
|
60
|
+
```
|
|
40
61
|
|
|
41
|
-
|
|
62
|
+
That takes the newest `1.x`, which is what most people want. To pin an exact version for a
|
|
63
|
+
reproducible setup, name it — this page documents `1.0.1`:
|
|
42
64
|
|
|
43
|
-
|
|
65
|
+
```sh
|
|
66
|
+
mcpi install npm:@sammorrowdrums/mcpi-ext@1.0.1
|
|
67
|
+
```
|
|
44
68
|
|
|
45
|
-
|
|
69
|
+
Confirm it registered:
|
|
46
70
|
|
|
47
|
-
|
|
71
|
+
```sh
|
|
72
|
+
mcpi list
|
|
73
|
+
```
|
|
48
74
|
|
|
49
|
-
|
|
75
|
+
```
|
|
76
|
+
User packages:
|
|
77
|
+
npm:@sammorrowdrums/mcpi-ext@1.0.1
|
|
78
|
+
~/.cache/mcpi/npm/node_modules/@sammorrowdrums/mcpi-ext
|
|
79
|
+
```
|
|
50
80
|
|
|
51
|
-
|
|
81
|
+
`mcpi install` writes to `~/.config/mcpi/settings.json`. Add `-l` to install into the current
|
|
82
|
+
project's `.mcpi/settings.json` instead. Once a package is listed there, mcpi loads it on every
|
|
83
|
+
run — you never pass `--extension` for it again.
|
|
52
84
|
|
|
53
|
-
|
|
85
|
+
### 4. Configure MCP servers
|
|
54
86
|
|
|
55
|
-
|
|
87
|
+
Create `~/.config/mcpi-ext/mcp.json`. That is the default path; `--mcp-config <path>` overrides it,
|
|
88
|
+
and a missing file is not an error — mcpi-ext simply starts with zero servers.
|
|
56
89
|
|
|
57
|
-
|
|
90
|
+
Keep your token **out of this file**. Write it to a private env file instead, created with
|
|
91
|
+
restrictive permissions from the start so the token is never briefly world-readable:
|
|
58
92
|
|
|
59
|
-
|
|
93
|
+
```sh
|
|
94
|
+
mkdir -p ~/.config/mcpi-ext
|
|
95
|
+
chmod 700 ~/.config/mcpi-ext
|
|
96
|
+
(umask 077 && gh auth token | sed 's/^/GITHUB_PERSONAL_ACCESS_TOKEN=/' > ~/.config/mcpi-ext/github-mcp.env)
|
|
97
|
+
chmod 600 ~/.config/mcpi-ext/github-mcp.env
|
|
98
|
+
ls -l ~/.config/mcpi-ext/github-mcp.env # expect -rw-------
|
|
99
|
+
```
|
|
60
100
|
|
|
61
|
-
|
|
101
|
+
Substitute your own token for `gh auth token` if you are not using the GitHub CLI. The file is plain
|
|
102
|
+
`KEY=VALUE` lines, read by Docker itself — never parsed by mcpi-ext.
|
|
62
103
|
|
|
63
|
-
|
|
104
|
+
Then have Docker read it, substituting your real home directory for `/home/you` — arguments are
|
|
105
|
+
passed to the process directly and are **not** shell-expanded, so `~` and `$HOME` will not work
|
|
106
|
+
here:
|
|
64
107
|
|
|
65
|
-
|
|
108
|
+
```json
|
|
109
|
+
{
|
|
110
|
+
"mcpServers": {
|
|
111
|
+
"github": {
|
|
112
|
+
"type": "stdio",
|
|
113
|
+
"command": "docker",
|
|
114
|
+
"args": [
|
|
115
|
+
"run",
|
|
116
|
+
"--rm",
|
|
117
|
+
"-i",
|
|
118
|
+
"--env-file",
|
|
119
|
+
"/home/you/.config/mcpi-ext/github-mcp.env",
|
|
120
|
+
"ghcr.io/github/github-mcp-server:latest",
|
|
121
|
+
"stdio"
|
|
122
|
+
]
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
```
|
|
66
127
|
|
|
67
|
-
|
|
128
|
+
> **Why not just `export` the token?** MCP stdio servers do not inherit your shell environment. The
|
|
129
|
+
> MCP SDK spawns them with a fixed safe set — `HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM`, `USER` on
|
|
130
|
+
> POSIX — plus whatever the server entry declares explicitly. An exported
|
|
131
|
+
> `GITHUB_PERSONAL_ACCESS_TOKEN` never reaches the server. `mcp.json` also performs no `${VAR}`
|
|
132
|
+
> expansion: values are used literally. `--env-file` is therefore the way to supply a secret without
|
|
133
|
+
> writing it into `mcp.json`, and it keeps the token in one `chmod 600` file you can rotate.
|
|
134
|
+
>
|
|
135
|
+
> An `"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "..." }` block does work, but it puts a live
|
|
136
|
+
> credential in a config file that is easy to copy, sync, or commit by accident.
|
|
137
|
+
>
|
|
138
|
+
> **Not using Docker?** A server you run directly gets the same restricted environment, so it cannot
|
|
139
|
+
> read an exported token either. Supply credentials through whatever mechanism that server already
|
|
140
|
+
> supports for reading a secret from a file. If you need a wrapper script for local development, see
|
|
141
|
+
> the [server developer guide](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/server-developer-guide.md#supplying-credentials-to-a-local-server).
|
|
68
142
|
|
|
69
|
-
|
|
70
|
-
📦 [**Standalone package →**](https://github.com/SamMorrowDrums/tool-cli) — `ToolProvider` interface, server, and implementor guidance for other languages.
|
|
143
|
+
Both `stdio` (spawns a process) and `remote` (Streamable HTTP) servers are supported:
|
|
71
144
|
|
|
72
|
-
|
|
145
|
+
```json
|
|
146
|
+
{
|
|
147
|
+
"mcpServers": {
|
|
148
|
+
"github": { "...": "..." },
|
|
149
|
+
"my-remote-server": {
|
|
150
|
+
"type": "remote",
|
|
151
|
+
"url": "https://my-mcp-server.example.com/mcp",
|
|
152
|
+
"headers": { "Authorization": "Bearer ..." }
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
```
|
|
73
157
|
|
|
74
|
-
|
|
158
|
+
A `stdio` entry takes `command`, optional `args`, `env`, and `cwd`. A `remote` entry takes `url` and
|
|
159
|
+
optional `headers`. Any other shape is rejected at startup with the offending path.
|
|
75
160
|
|
|
76
|
-
|
|
161
|
+
### 5. Run
|
|
77
162
|
|
|
78
|
-
|
|
163
|
+
```sh
|
|
164
|
+
mcpi --provider github-copilot --model claude-opus-5 \
|
|
165
|
+
--mcp-config ~/.config/mcpi-ext/mcp.json \
|
|
166
|
+
--mcp-skills-extension
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
`--mcp-config` and `--mcp-skills-extension` are registered by mcpi-ext, so they exist only once the
|
|
170
|
+
extension is installed. `--mcp-skills-extension` is **opt-in** and off by default; see
|
|
171
|
+
[Skills support](#skills-support) before enabling it. Drop it unless you are talking to a server that
|
|
172
|
+
implements the draft.
|
|
173
|
+
|
|
174
|
+
### 6. Authenticate the model provider
|
|
79
175
|
|
|
80
|
-
|
|
176
|
+
Providers are authenticated inside mcpi, not through this extension. On first run, use the `/login`
|
|
177
|
+
slash command:
|
|
81
178
|
|
|
82
|
-
|
|
179
|
+
```
|
|
180
|
+
/login github-copilot
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
`/login` opens mcpi's provider authentication flow — OAuth where the provider supports it, otherwise
|
|
184
|
+
an API key prompt — and stores the credential for later sessions. Run bare `/login` to pick a
|
|
185
|
+
provider from a list. If a session later reports an expired credential, mcpi tells you to run
|
|
186
|
+
`/login <provider>` again. `github-copilot` defaults to the `claude-opus-5` model, so
|
|
187
|
+
`--model claude-opus-5` above is explicit rather than required.
|
|
83
188
|
|
|
84
|
-
|
|
189
|
+
### Upgrading from pi or from mcpi before 0.85
|
|
85
190
|
|
|
86
|
-
|
|
191
|
+
mcpi 0.85.0 no longer reads the legacy `~/.pi/agent` directory, and it **refuses to start** while
|
|
192
|
+
that directory exists rather than silently ignoring your history:
|
|
87
193
|
|
|
88
|
-
|
|
194
|
+
```
|
|
195
|
+
Error: mcpi no longer reads legacy pi config paths.
|
|
196
|
+
```
|
|
89
197
|
|
|
90
|
-
|
|
198
|
+
Nothing is moved for you. Migrate by hand:
|
|
199
|
+
|
|
200
|
+
| Legacy | New |
|
|
201
|
+
| ----------------------- | ------------------------------------------------------------------ |
|
|
202
|
+
| `~/.pi/agent` | `~/.local/state/mcpi` (sessions in `~/.local/state/mcpi/sessions`) |
|
|
203
|
+
| package / binary caches | recreate under `~/.cache/mcpi` |
|
|
204
|
+
|
|
205
|
+
Caches are disposable — delete rather than move them. Alternatively set `MCPI_CODING_AGENT_DIR` to an
|
|
206
|
+
already-migrated directory. Settings live at `~/.config/mcpi/settings.json`; mcpi-ext's own MCP
|
|
207
|
+
config is separate, at `~/.config/mcpi-ext/mcp.json`.
|
|
208
|
+
|
|
209
|
+
---
|
|
91
210
|
|
|
92
|
-
|
|
211
|
+
## What your MCP server actually gives you
|
|
212
|
+
|
|
213
|
+
The three mechanisms have different requirements. Only one of them depends on the server, so it is
|
|
214
|
+
worth being precise about which you get.
|
|
215
|
+
|
|
216
|
+
| Mechanism | Requires | Works with the official GitHub MCP server? |
|
|
217
|
+
| ------------- | ----------------------------------------------------- | ------------------------------------------ |
|
|
218
|
+
| **tool-cli** | any MCP server | **Yes** |
|
|
219
|
+
| **Code mode** | tools annotated `readOnlyHint: true`, not destructive | **Yes**, for the read-only subset |
|
|
220
|
+
| **Skills** | a server that publishes skills (see below) | **No** — it publishes none today |
|
|
221
|
+
|
|
222
|
+
Measured against `ghcr.io/github/github-mcp-server:latest` (server `v1.12.0`, protocol `2026-07-28`)
|
|
223
|
+
with the default toolset: **45 tools**, of which **26** are read-only and non-destructive and so
|
|
224
|
+
dispatchable from code mode. None declare an `outputSchema`, so code mode gives each one a permissive
|
|
225
|
+
internal survival schema and an `unknown` return type. The server does **not** declare the
|
|
226
|
+
`io.modelcontextprotocol/skills` extension, so it contributes **no skills** — mcpi-ext logs the
|
|
227
|
+
negotiation result and falls back to legacy `skill://` discovery, which also finds none.
|
|
228
|
+
|
|
229
|
+
> **Image tags.** Use `ghcr.io/github/github-mcp-server:latest`. A `skill-discovery` tag was
|
|
230
|
+
> referenced by earlier revisions of this document; **it does not exist** on the registry. Published
|
|
231
|
+
> tags are `latest`, `main`, `nightly`, and `v0.1.0`. The trailing `stdio` argument above is correct
|
|
232
|
+
> for `:latest`, which has an entrypoint; `:v0.1.0` has none and already includes `stdio` in its
|
|
233
|
+
> command, so passing it again fails to start.
|
|
234
|
+
|
|
235
|
+
### Skills support
|
|
236
|
+
|
|
237
|
+
Skills require an MCP server that publishes them by one of two contracts:
|
|
238
|
+
|
|
239
|
+
1. **[SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640)** — the
|
|
240
|
+
server declares the `io.modelcontextprotocol/skills` extension and serves `skills/list`. This is
|
|
241
|
+
a **live Draft** on the MCP Extensions Track: open, unratified, and still changing. mcpi-ext pins
|
|
242
|
+
revision `753b9f2be43e07fdd070e535d75f190cff14beea` and is gated **off** by default, which is why
|
|
243
|
+
`--mcp-skills-extension` (or `{"experimental": {"skillsExtension": true}}` in `mcp.json`) is
|
|
244
|
+
required to enable it. With the gate off, the extension is never advertised at `initialize`, so
|
|
245
|
+
no server can negotiate it.
|
|
246
|
+
2. **Legacy `skill://` resources** — the server lists `skill://` URIs among its resources. This is
|
|
247
|
+
the compatibility fallback, used only when a server declares no extension.
|
|
248
|
+
|
|
249
|
+
The two are never mixed on one server. A server that declares the extension is served by the
|
|
250
|
+
extension path alone, even when its listing is empty.
|
|
251
|
+
|
|
252
|
+
The eight-skill GitHub reference implementation used to develop and test this client — 8 skills over
|
|
253
|
+
a 31-tool schema set — is **not a public distribution**. It is not published to GHCR, the MCP
|
|
254
|
+
Registry, or any other registry or public image tag, and there is no branch or SHA you can pull. It
|
|
255
|
+
remains local-only and can only be produced from the exact compatible source checkout. Treat it as
|
|
256
|
+
the tested reference implementation pending upstream adoption and public distribution; the official
|
|
257
|
+
server may implement skills in future, at which point they will work here with no change to this
|
|
258
|
+
extension.
|
|
259
|
+
|
|
260
|
+
If you already have a compatible GitHub MCP server checkout, you can build and tag it locally and
|
|
261
|
+
point `mcp.json` at that local tag — see
|
|
262
|
+
[running a custom server from a local image](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/server-developer-guide.md#running-a-custom-server-from-a-local-image)
|
|
263
|
+
in the developer guide. That path is for contributors with the source in hand; it does not make any
|
|
264
|
+
custom image available to pull.
|
|
265
|
+
|
|
266
|
+
To use skills today, point mcpi-ext at your own server implementing either contract. The
|
|
267
|
+
[server developer guide](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/server-developer-guide.md)
|
|
268
|
+
covers what to publish.
|
|
93
269
|
|
|
94
270
|
---
|
|
95
271
|
|
|
96
|
-
##
|
|
272
|
+
## Verifying your install
|
|
97
273
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
no sequence to try them in. Every facility states its own availability, so an unavailable one is
|
|
102
|
-
listed with the reason rather than silently omitted.
|
|
274
|
+
Three prompts, one per mechanism. Each names the tool call you should actually see in the agent's
|
|
275
|
+
transcript — if you see prose describing a call instead of the call itself, the mechanism is not
|
|
276
|
+
working.
|
|
103
277
|
|
|
104
|
-
|
|
105
|
-
alongside them because most real tasks need it.
|
|
278
|
+
### Code mode — works with zero MCP servers
|
|
106
279
|
|
|
107
|
-
|
|
108
|
-
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
|
|
109
|
-
| [Skills](#i-the-skill-dealer) | a documented domain workflow — sequencing, conventions, and a curated tool set |
|
|
110
|
-
| [Code mode](#iii-codey-c-maude) | exact computation or control flow, sandboxed with no filesystem, network, or process access |
|
|
111
|
-
| [tool-cli](#ii-the-nuclear-football) | reaching a specific MCP tool, or discovering what exists — run through the host bash tool |
|
|
112
|
-
| bash + external programs | touching the real machine: files, git, build tools, data pipelines, artifacts that persist |
|
|
280
|
+
> Using code mode, compute the number of days between 2026-01-01 and 2026-09-07.
|
|
113
281
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
error-prone. A skill enables the tools it declares only after the grant is approved.
|
|
282
|
+
Expect a **`code_execute`** tool call returning `249`. This needs no MCP server at all, so it is the
|
|
283
|
+
fastest check that the extension loaded. If it reports code mode unavailable, see
|
|
284
|
+
[isolated-vm](#code-mode-needs-isolated-vm).
|
|
118
285
|
|
|
119
|
-
|
|
120
|
-
joining results, math. 876 issues across 9 pages, counting labels per issue, summing into a
|
|
121
|
-
histogram — that's a loop with state, and one sandbox execution does it. Available even with zero
|
|
122
|
-
MCP servers connected, because pure computation needs no server.
|
|
286
|
+
With servers connected, exercise MCP dispatch:
|
|
123
287
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
Also the way to discover what's on a server you haven't used before. It is a program, not a tool:
|
|
127
|
-
the agent invokes the bash tool with a `tool-cli ...` command. It is advertised as available only
|
|
128
|
-
after bash is active and the local server completes an authenticated compatible v1 handshake;
|
|
129
|
-
inherited credentials are masked and usage docs remain withheld on startup, timeout, auth, or
|
|
130
|
-
major-version failure.
|
|
288
|
+
> Using code mode, list the open issues on github/github-mcp-server and count how many carry each
|
|
289
|
+
> label.
|
|
131
290
|
|
|
132
|
-
|
|
133
|
-
|
|
291
|
+
Expect **`code_search`** (finding dispatchable tools) then **`code_execute`** looping over paginated
|
|
292
|
+
results.
|
|
134
293
|
|
|
135
|
-
###
|
|
294
|
+
### tool-cli — works with any MCP server
|
|
136
295
|
|
|
137
|
-
tool-cli
|
|
138
|
-
|
|
139
|
-
a single bash command rather than two rival approaches.
|
|
296
|
+
> Use tool-cli to list the MCP servers available, then show the schema for the GitHub server's
|
|
297
|
+
> `search_repositories` tool.
|
|
140
298
|
|
|
141
|
-
|
|
299
|
+
Expect **`bash`** tool calls running `tool-cli` — for example `tool-cli --help`, then
|
|
300
|
+
`tool-cli github`, then `tool-cli github search_repositories`. There is no `tool-cli` entry in the
|
|
301
|
+
agent's tool registry: it is a program invoked through mcpi's bash tool. A response containing
|
|
302
|
+
`<tool_cli>` markup, or a transcript of a command that no bash call ran, is a hallucination.
|
|
142
303
|
|
|
143
|
-
|
|
144
|
-
and keyword to find clusters. Computation across many pages — this is what sandboxes are for.
|
|
304
|
+
### Skills — needs a server that publishes them
|
|
145
305
|
|
|
146
|
-
|
|
147
|
-
through `jq` to eyeball specific fields. Quick, ad-hoc, composable.
|
|
306
|
+
> List the skills available, then load the one for issue triage.
|
|
148
307
|
|
|
149
|
-
|
|
150
|
-
|
|
308
|
+
Expect a **`load_skill`** tool call. Loading prompts you to approve the skill's tool grant; the
|
|
309
|
+
declared tools stay locked until you approve. With no skills discovered, the agent should tell you
|
|
310
|
+
so — the routing section reports skills as unavailable with the reason rather than omitting them.
|
|
151
311
|
|
|
152
|
-
|
|
153
|
-
|
|
312
|
+
### Confirming what loaded
|
|
313
|
+
|
|
314
|
+
At startup mcpi-ext reports connected servers and discovered tool counts, and — when
|
|
315
|
+
`--mcp-skills-extension` is on — logs the pinned draft revision and the per-server negotiation
|
|
316
|
+
result. It always emits an `<execution_routing>` prompt section stating each facility's availability
|
|
317
|
+
and, when unavailable, why.
|
|
154
318
|
|
|
155
319
|
---
|
|
156
320
|
|
|
157
|
-
##
|
|
321
|
+
## Four facilities, three MCP mechanisms
|
|
158
322
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
T2["tool-cli\n(Tier 2 — Football)"]
|
|
164
|
-
T3["code_search / code_execute\n(Tier 3 — Code Mode)"]
|
|
165
|
-
MCM["McpClientManager\n(split MCP v2 client — stdio & Streamable HTTP)"]
|
|
166
|
-
T1 --> MCM
|
|
167
|
-
T2 --> MCM
|
|
168
|
-
T3 --> MCM
|
|
169
|
-
end
|
|
170
|
-
MCM --> S1["MCP Server"]
|
|
171
|
-
MCM --> S2["MCP Server"]
|
|
172
|
-
MCM --> S3["MCP Server"]
|
|
173
|
-
```
|
|
323
|
+
Skills, tool-cli, and code mode are the three ways this extension reaches MCP. The
|
|
324
|
+
`<execution_routing>` section describes a **fourth** facility alongside them — the host's own
|
|
325
|
+
**bash** tool — because most real tasks need it and mis-routing to a sandbox that cannot write files
|
|
326
|
+
is a common failure.
|
|
174
327
|
|
|
175
|
-
|
|
328
|
+
bash is not an MCP mechanism. It is the substrate: the only facility that can create, modify, or
|
|
329
|
+
inspect files, run the host's real programs, and leave artifacts behind. It is also how tool-cli is
|
|
330
|
+
invoked, which is why the two compose so closely — fetching MCP data and then filtering it with `jq`
|
|
331
|
+
or writing it to disk is one bash command, not two rival approaches.
|
|
176
332
|
|
|
177
|
-
|
|
333
|
+
| Facility | Suits work that is… |
|
|
334
|
+
| --------- | ------------------------------------------------------------------------------------------- |
|
|
335
|
+
| bash | touching the real machine: files, git, build tools, data pipelines, artifacts that persist |
|
|
336
|
+
| Code mode | exact computation or control flow, sandboxed with no filesystem, network, or process access |
|
|
337
|
+
| Skills | a documented domain workflow — sequencing, conventions, and a curated tool set |
|
|
338
|
+
| tool-cli | reaching a specific MCP tool, or discovering what exists — run through the host bash tool |
|
|
178
339
|
|
|
179
|
-
|
|
340
|
+
The section sorts facilities **by task shape, not by rank**. None is a default, none outranks
|
|
341
|
+
another, and there is no order to try them in. The list is alphabetical by identifier purely so the
|
|
342
|
+
emitted bytes stay stable between turns and never invalidate the prompt cache.
|
|
180
343
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
- **Resource operations use the same policy** — tool-cli can list templates and read ordinary text/binary resources, while every `skill://` URI and SEP-2640-declared resource remains isolated; skill reads are origin-bound, and a discovery pass cannot authorize a skill-load read.
|
|
185
|
-
- **Every decision is audited** — allowed and denied operations alike are recorded with their source (`proxy`, `code-mode`, `tool-cli`, `skill-discovery`, `skill-load`).
|
|
344
|
+
Every facility states its own availability. An unavailable one is listed **with its reason** rather
|
|
345
|
+
than silently dropped, and "we could not tell" is reported as `unknown` rather than collapsed into
|
|
346
|
+
"absent".
|
|
186
347
|
|
|
187
|
-
|
|
348
|
+
### With zero MCP servers connected
|
|
188
349
|
|
|
189
|
-
|
|
350
|
+
The extension still loads and still emits `<execution_routing>`. Code mode remains available, because
|
|
351
|
+
pure computation needs no server. Skills report as unavailable with the reason that none were
|
|
352
|
+
discovered. tool-cli starts its bridge but has no upstream to reach. Nothing errors, and a missing
|
|
353
|
+
`mcp.json` is treated as an empty server list rather than a failure.
|
|
190
354
|
|
|
191
|
-
|
|
355
|
+
### Code mode needs isolated-vm
|
|
192
356
|
|
|
193
|
-
|
|
357
|
+
Code mode uses the optional [`isolated-vm`](https://github.com/laverdet/isolated-vm) native addon. It
|
|
358
|
+
ships prebuilt binaries for Linux (x64, arm64), macOS (Apple Silicon), and Windows (x64), so the
|
|
359
|
+
usual install is a download. Where no prebuild matches — Intel macOS, for instance — npm compiles it
|
|
360
|
+
from source and needs a C++ toolchain.
|
|
194
361
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
362
|
+
If the addon is unavailable for any reason, **installation still succeeds and the extension still
|
|
363
|
+
loads**. Code mode reports itself unavailable with the specific cause, and skills, tool-cli, and
|
|
364
|
+
execution routing continue to work. Code mode never falls back to `node:vm`: that would silently
|
|
365
|
+
downgrade an isolate boundary to same-process execution and hand sandboxed code the host realm.
|
|
198
366
|
|
|
199
|
-
|
|
367
|
+
To skip the addon deliberately: `npm install --omit=optional`.
|
|
200
368
|
|
|
201
|
-
|
|
369
|
+
---
|
|
202
370
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
"
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
"env": {
|
|
219
|
-
"GITHUB_PERSONAL_ACCESS_TOKEN": "xxx"
|
|
220
|
-
}
|
|
221
|
-
}
|
|
222
|
-
}
|
|
223
|
-
}
|
|
371
|
+
## Architecture
|
|
372
|
+
|
|
373
|
+
```mermaid
|
|
374
|
+
flowchart TD
|
|
375
|
+
subgraph mcpi["mcpi (agent)"]
|
|
376
|
+
LS["load_skill<br/>(skills)"]
|
|
377
|
+
BASH["bash → tool-cli<br/>(tool-cli)"]
|
|
378
|
+
CM["code_search / code_execute<br/>(code mode)"]
|
|
379
|
+
end
|
|
380
|
+
LS --> POL["McpPolicy<br/>(authorization boundary)"]
|
|
381
|
+
BASH --> POL
|
|
382
|
+
CM --> POL
|
|
383
|
+
POL --> MCM["McpClientManager<br/>(MCP client — stdio & Streamable HTTP)"]
|
|
384
|
+
MCM --> S1["MCP Server"]
|
|
385
|
+
MCM --> S2["MCP Server"]
|
|
224
386
|
```
|
|
225
387
|
|
|
226
|
-
|
|
388
|
+
All three mechanisms route back through the extension process, and every one of them crosses the same
|
|
389
|
+
authorization boundary — `McpPolicy` — exactly once. Even when the model writes sandboxed JavaScript
|
|
390
|
+
or shells out to `tool-cli`, the actual MCP call is authorized and dispatched by that one object.
|
|
391
|
+
|
|
392
|
+
- **Every tool invocation appears in the agent log** — skills, tool-cli one-shots, and code mode
|
|
393
|
+
sandbox calls alike. Full observability without instrumentation.
|
|
394
|
+
- **Human-in-the-loop happens at one point.** `McpPolicy` reads tool annotations and gates
|
|
395
|
+
non-read-only calls through user confirmation, whichever mechanism initiated them. A tool unlocked
|
|
396
|
+
by an approved skill grant is not re-prompted.
|
|
397
|
+
- **Code mode is refused, not prompted.** A non-read-only tool called from the sandbox is denied
|
|
398
|
+
outright rather than escalated to a confirmation. Visibility is not authority.
|
|
399
|
+
- **Undiscovered and gated tools never reach upstream.** The policy verifies the tool exists in the
|
|
400
|
+
discovered set and is not skill-gated _before_ contacting the server, so naming a hidden tool over
|
|
401
|
+
the authenticated bridge socket fails at the boundary.
|
|
402
|
+
- **Resource reads use the same policy.** tool-cli can list templates and read ordinary text and
|
|
403
|
+
binary resources, while every `skill://` URI and SEP-2640-declared skill resource stays isolated.
|
|
404
|
+
Skill reads are origin-bound, and a discovery pass cannot authorize a skill-load read.
|
|
405
|
+
- **Every decision is audited** — allowed and denied alike, recorded with the source that made it
|
|
406
|
+
(`proxy`, `code-mode`, `tool-cli`, `skill-discovery`, `skill-load`, `skills-extension`).
|
|
407
|
+
|
|
408
|
+
### Skills never execute anything
|
|
409
|
+
|
|
410
|
+
Nothing in a skill is executed. A SKILL.md body is content, not commands: helper code and
|
|
411
|
+
instructions telling the host to run something are text the model reads, never actions the extension
|
|
412
|
+
performs. A skill's declared tools stay **inert until you approve the grant**, and the grant is bound
|
|
413
|
+
to the server, the resource URI, and a hash of the tool list — so a server that widens `allowed-tools`
|
|
414
|
+
or rotates its content after approval is re-prompted rather than inheriting the old answer.
|
|
415
|
+
|
|
416
|
+
### tool-cli bridge credentials are session-scoped
|
|
417
|
+
|
|
418
|
+
tool-cli reaches the extension over an authenticated local bridge, not a shared service. On
|
|
419
|
+
`session_start` the bridge binds a **random port** and generates a fresh **32-byte session token**;
|
|
420
|
+
both are torn down on `session_shutdown`. `TOOL_CLI_PORT` and `TOOL_CLI_TOKEN` are exposed to the
|
|
421
|
+
agent's bash environment **only after** an authenticated, compatible bridge-v1 handshake succeeds —
|
|
422
|
+
inherited values are masked until then, and startup, auth, timeout, or major-version failures
|
|
423
|
+
withhold the usage docs entirely and report an actionable reason.
|
|
424
|
+
|
|
425
|
+
Stdio MCP child servers are spawned with the SDK's safe environment plus their explicit
|
|
426
|
+
configuration, with every `TOOL_CLI_*` variable stripped — so a child server cannot inherit this
|
|
427
|
+
session's bridge credentials, even when mcpi was started from another mcpi session.
|
|
428
|
+
|
|
429
|
+
### Protocol and defaults
|
|
430
|
+
|
|
431
|
+
mcpi-ext uses `@modelcontextprotocol/client@2.0.0` in automatic version-negotiation mode. It probes
|
|
432
|
+
the released **`2026-07-28`** protocol with `server/discover`, then falls back to the legacy
|
|
433
|
+
`initialize` handshake for servers that predate it. The connection log reports the negotiated era.
|
|
434
|
+
|
|
435
|
+
- Tool and skill-resource lists follow cursors automatically, with a 64-page safety limit.
|
|
436
|
+
- Results without a server-provided `ttlMs` are immediately stale (`defaultCacheTtlMs: 0`). Explicit
|
|
437
|
+
server cache hints are honoured in the SDK's in-memory cache; no persistent or shared cache is
|
|
438
|
+
configured.
|
|
439
|
+
- Tool-list change handling is enabled. Modern servers may use a `subscriptions/listen` stream where
|
|
440
|
+
advertised; legacy servers use list-changed notifications. Durable subscription resume and live
|
|
441
|
+
skill-resource refresh are not exposed.
|
|
442
|
+
- Modern `input_required` flows support explicit form input, decline, and cancel in interactive
|
|
443
|
+
sessions. Headless and URL elicitation fail with an actionable error rather than auto-approving.
|
|
227
444
|
|
|
228
|
-
|
|
445
|
+
---
|
|
229
446
|
|
|
230
|
-
|
|
447
|
+
## Documentation
|
|
448
|
+
|
|
449
|
+
- [Skills](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/skills.md) — deferred gating,
|
|
450
|
+
the two discovery contracts, SEP-2640 integrity model, approval binding.
|
|
451
|
+
- [tool-cli](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/tool-cli.md) — bridge
|
|
452
|
+
architecture, progressive discovery, resources, shell composability.
|
|
453
|
+
- [Code mode](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/code-mode.md) — sandbox
|
|
454
|
+
isolation, catalog provenance, dispatch eligibility.
|
|
455
|
+
- [Server developer guide](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/server-developer-guide.md)
|
|
456
|
+
— what to publish so your MCP server works well with all three mechanisms.
|
|
457
|
+
- [Releasing](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/releasing.md) — trusted
|
|
458
|
+
publishing and release preflight.
|
|
459
|
+
- [AGENTS.md](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/AGENTS.md) — contributor tooling,
|
|
460
|
+
dev loop, and architecture detail.
|
|
461
|
+
- [DECISIONS.md](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/DECISIONS.md) — the decision
|
|
462
|
+
log behind these mechanisms.
|
|
231
463
|
|
|
232
|
-
|
|
233
|
-
{
|
|
234
|
-
"mcpServers": {
|
|
235
|
-
"github": { "...": "..." },
|
|
236
|
-
"my-remote-server": {
|
|
237
|
-
"type": "remote",
|
|
238
|
-
"url": "https://my-mcp-server.example.com/mcp",
|
|
239
|
-
"headers": {
|
|
240
|
-
"Authorization": "Bearer xxx"
|
|
241
|
-
}
|
|
242
|
-
}
|
|
243
|
-
}
|
|
244
|
-
}
|
|
245
|
-
```
|
|
464
|
+
---
|
|
246
465
|
|
|
247
|
-
|
|
466
|
+
## Screenshots
|
|
248
467
|
|
|
249
|
-
|
|
250
|
-
mode. It first probes the released `2026-07-28` protocol with `server/discover`, then
|
|
251
|
-
falls back to the legacy `initialize` handshake when a server does not support the
|
|
252
|
-
modern era. The connection log reports the negotiated era.
|
|
468
|
+
|
|
253
469
|
|
|
254
|
-
-
|
|
255
|
-
limit.
|
|
256
|
-
- Results without a server-provided `ttlMs` are immediately stale
|
|
257
|
-
(`defaultCacheTtlMs: 0`). Explicit server cache hints are still honored in the
|
|
258
|
-
SDK's in-memory cache; mcpi-ext does not configure a persistent or shared cache.
|
|
259
|
-
- Tool-list change handling is enabled. On modern servers the SDK may open a
|
|
260
|
-
`subscriptions/listen` stream when the capability is advertised; legacy servers
|
|
261
|
-
continue to use list-changed notifications. General subscription management,
|
|
262
|
-
durable subscription resume, and live skill-resource refresh are not exposed.
|
|
263
|
-
- Modern `input_required` flows support explicit form input, decline, and cancel in
|
|
264
|
-
interactive mcpi sessions. Headless and URL elicitation fail with an actionable
|
|
265
|
-
error rather than approving automatically.
|
|
470
|
+
|
|
266
471
|
|
|
267
|
-
|
|
472
|
+
|
|
268
473
|
|
|
269
|
-
|
|
270
|
-
mcpi --extension $(npm root -g)/@sammorrowdrums/mcpi-ext/dist/index.js \
|
|
271
|
-
--mcp-config ~/.config/mcpi-ext/mcp.json
|
|
272
|
-
```
|
|
474
|
+
---
|
|
273
475
|
|
|
274
|
-
|
|
476
|
+
## Local development
|
|
275
477
|
|
|
276
478
|
```sh
|
|
277
479
|
git clone https://github.com/SamMorrowDrums/mcpi-ext.git
|
|
@@ -281,57 +483,40 @@ npm run build
|
|
|
281
483
|
npm test
|
|
282
484
|
```
|
|
283
485
|
|
|
284
|
-
|
|
486
|
+
Run mcpi against your local build with `--extension`, which loads a file directly and bypasses the
|
|
487
|
+
settings-managed package above. This is the one case where `--extension` is the right tool:
|
|
285
488
|
|
|
286
489
|
```sh
|
|
287
490
|
mcpi --extension ./dist/index.js --mcp-config ~/.config/mcpi-ext/mcp.json
|
|
288
491
|
```
|
|
289
492
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
## Project Structure
|
|
493
|
+
### Project structure
|
|
293
494
|
|
|
294
495
|
```
|
|
295
496
|
src/
|
|
296
497
|
index.ts Extension entry point (lifecycle hooks, wiring)
|
|
297
498
|
mcp/ MCP client management (connections, discovery) + McpPolicy
|
|
298
499
|
routing/ Execution-facility descriptors, prompt section, host seam
|
|
299
|
-
skills/ Skill registry, discovery, gating, tool proxies
|
|
500
|
+
skills/ Skill registry, discovery, gating, tool proxies, SEP-2640
|
|
300
501
|
tool-cli/ tool-cli RPC server, provider, bridge handshake, prompt
|
|
301
502
|
code-mode/ V8 sandbox executor, lazy isolated-vm adapter, type hints
|
|
302
503
|
test-servers/ Test MCP servers (weather, echo, skills fixtures)
|
|
303
|
-
docs/
|
|
304
|
-
images/
|
|
504
|
+
docs/ Mechanism documentation
|
|
505
|
+
images/ Screenshots
|
|
305
506
|
scripts/ Integration, smoke, and release-check scripts
|
|
306
507
|
tsconfig.json Development build (compiles tests and fixture servers)
|
|
307
508
|
tsconfig.build.json Published build (no tests, fixtures, or source maps)
|
|
308
509
|
```
|
|
309
510
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
Node.js `>=22.13.0`. Node 22 and 24 are both covered by CI.
|
|
313
|
-
|
|
314
|
-
Code Mode needs the optional [`isolated-vm`](https://github.com/laverdet/isolated-vm)
|
|
315
|
-
native addon. It ships prebuilt binaries for Linux (x64, arm64), macOS
|
|
316
|
-
(Apple Silicon), and Windows (x64), so the usual install is a download rather than a
|
|
317
|
-
compile. Where no prebuild matches — Intel macOS, for instance — npm compiles it from
|
|
318
|
-
source and needs a C++ toolchain.
|
|
319
|
-
|
|
320
|
-
If the addon is unavailable for any reason, installation still succeeds and the
|
|
321
|
-
extension still loads. Code Mode reports itself unavailable with the specific cause,
|
|
322
|
-
and skills, tool-cli, and execution routing continue to work. Code Mode never falls
|
|
323
|
-
back to `node:vm`: that would silently downgrade an isolate boundary to same-process
|
|
324
|
-
execution and hand sandboxed code the host realm.
|
|
325
|
-
|
|
326
|
-
To skip the addon deliberately, install with `npm install --omit=optional`.
|
|
511
|
+
See [AGENTS.md](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/AGENTS.md) for the full dev loop.
|
|
327
512
|
|
|
328
513
|
## Releasing
|
|
329
514
|
|
|
330
|
-
Published to npm by
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
515
|
+
Published to npm by
|
|
516
|
+
[`.github/workflows/publish.yml`](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/.github/workflows/publish.yml)
|
|
517
|
+
using npm trusted publishing — a GitHub Release triggers it, OIDC authenticates it, and no
|
|
518
|
+
`NPM_TOKEN` exists anywhere in this repository. See
|
|
519
|
+
[docs/releasing.md](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/releasing.md).
|
|
335
520
|
|
|
336
521
|
## License
|
|
337
522
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { Client, type DiscoverResult, type ElicitRequestParams, type ElicitResult, type Implementation, type ListChangedHandlers, type ProtocolEra, type ServerCapabilities } from "@modelcontextprotocol/client";
|
|
2
2
|
export declare const MCP_CLIENT_IDENTITY: {
|
|
3
3
|
readonly name: "@sammorrowdrums/mcpi-ext";
|
|
4
|
-
readonly version: "1.0.
|
|
4
|
+
readonly version: "1.0.1";
|
|
5
5
|
};
|
|
6
6
|
export declare const MCP_CLIENT_POLICY: {
|
|
7
7
|
readonly listMaxPages: 64;
|
|
@@ -2,7 +2,7 @@ import { Client, SUPPORTED_PROTOCOL_VERSIONS, } from "@modelcontextprotocol/clie
|
|
|
2
2
|
import { SKILLS_EXTENSION_NAME, SKILLS_EXTENSION_REVISION, SKILLS_EXTENSION_STATUS, } from "../skills/sep2640/spec.js";
|
|
3
3
|
export const MCP_CLIENT_IDENTITY = {
|
|
4
4
|
name: "@sammorrowdrums/mcpi-ext",
|
|
5
|
-
version: "1.0.
|
|
5
|
+
version: "1.0.1",
|
|
6
6
|
};
|
|
7
7
|
export const MCP_CLIENT_POLICY = {
|
|
8
8
|
listMaxPages: 64,
|