devstuff 2.15.0__py3-none-any.whl → 2.16.0__py3-none-any.whl

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.
@@ -10,6 +10,12 @@ from dev_setup.agent.config import AgentConfig
10
10
  from dev_setup.agent.sandbox import SandboxError, Workspace
11
11
 
12
12
 
13
+ class InstallFailed(SandboxError):
14
+ """An installer ran and failed. A subclass so the local agent handles it as it always did;
15
+ the MCP server tells it apart from "unknown tool" to add the FR-13 hint (it cannot answer a
16
+ password prompt, so the client has to be told where to run the install instead)."""
17
+
18
+
13
19
  def _tool_line(tool) -> str:
14
20
  state = "installed" if tool.is_installed() else "available"
15
21
  return f"{tool.key} [{state}] {tool.description}"
@@ -141,7 +147,7 @@ def install_tool(ws: Workspace, config: AgentConfig, args: dict[str, Any]) -> st
141
147
  try:
142
148
  version = tool.install()
143
149
  except (subprocess.CalledProcessError, RuntimeError) as exc:
144
- raise SandboxError(f"installing {tool.key} failed: {exc}") from exc
150
+ raise InstallFailed(f"installing {tool.key} failed: {exc}") from exc
145
151
 
146
152
  return f"Installed {tool.name}" + (f" ({version})" if version else "")
147
153
 
dev_setup/cli.py CHANGED
@@ -33,6 +33,7 @@ def _register_commands() -> None:
33
33
  from dev_setup.commands.install_cmd import install_cmd
34
34
  from dev_setup.commands.links_cmd import links_cmd
35
35
  from dev_setup.commands.list_cmd import list_cmd
36
+ from dev_setup.commands.mcp_cmd import mcp_cmd
36
37
  from dev_setup.commands.outdated_cmd import outdated_cmd
37
38
  from dev_setup.commands.profile_cmd import profile_cmd
38
39
  from dev_setup.commands.remove_cmd import remove_cmd
@@ -61,6 +62,7 @@ def _register_commands() -> None:
61
62
  cli.add_command(links_cmd, "link")
62
63
  cli.add_command(skills_cmd, "skills")
63
64
  cli.add_command(agent_cmd, "agent")
65
+ cli.add_command(mcp_cmd, "mcp")
64
66
 
65
67
  _add_verbose_option(cli)
66
68
 
@@ -0,0 +1,90 @@
1
+ from __future__ import annotations
2
+
3
+ import sys
4
+
5
+ import click
6
+
7
+ from dev_setup.catalog import CatalogError
8
+ from dev_setup.mcp import process, stdio
9
+ from dev_setup.mcp.core import Dispatcher, Toolbox
10
+
11
+
12
+ def _warn(message: str) -> None:
13
+ click.echo(f"devstuff mcp: {message}", err=True)
14
+
15
+
16
+ def _toolbox(allow_install: bool, allow_functions: bool) -> Toolbox:
17
+ from dev_setup.agent import registry as agent_registry
18
+
19
+ return Toolbox.from_agent(
20
+ agent_registry.build(), allow_install=allow_install, allow_functions=allow_functions, warn=_warn
21
+ )
22
+
23
+
24
+ def _banner(box: Toolbox, allow_install: bool, allow_functions: bool) -> str:
25
+ gated = [
26
+ label
27
+ for label, on in (("install_tool", allow_install), ("functions", allow_functions))
28
+ if on
29
+ ]
30
+ return (
31
+ f"devstuff mcp: serving {len(box.names())} tools on stdio "
32
+ f"({'+ ' + ', '.join(gated) if gated else 'read-only; install_tool and functions are off'})"
33
+ )
34
+
35
+
36
+ @click.command("mcp")
37
+ @click.option(
38
+ "--allow-install", is_flag=True,
39
+ help="Expose install_tool, which installs a catalog tool as you. Off by default: absent and refused.",
40
+ )
41
+ @click.option(
42
+ "--allow-functions", is_flag=True,
43
+ help="Expose every `type: script` function (fn_<key>). Off by default: absent and refused.",
44
+ )
45
+ @click.option(
46
+ "--list-tools", "list_tools", is_flag=True,
47
+ help="Print the tools these flags would expose, and which gate each sits behind. Starts nothing.",
48
+ )
49
+ def mcp_cmd(allow_install: bool, allow_functions: bool, list_tools: bool) -> None:
50
+ """Serve devstuff's tools to an MCP client over stdio.
51
+
52
+ Reads JSON-RPC from stdin and answers on stdout — it is meant to be started by a client
53
+ (Claude Code, Claude Desktop), not by hand. Only read-only tools are exposed unless a flag
54
+ says otherwise, and a tool that is off does not merely hide: a call naming it is refused.
55
+
56
+ The server has no terminal. An installer that needs a password fails at once rather than
57
+ waiting for one nobody can type; run `devstuff install <key>` in a terminal for those.
58
+ """
59
+ if list_tools:
60
+ _print_tools(_load(allow_install, allow_functions))
61
+ return
62
+
63
+ # Detach first, before the fd move and before anything that could run an installer (FR-11a).
64
+ # Under a shell this forks and the original process becomes a supervisor that never returns.
65
+ process.detach()
66
+ try:
67
+ process.require_no_terminal(gated=allow_install or allow_functions, warn=_warn)
68
+ except process.TerminalReachable as exc:
69
+ click.echo(f"error: {exc}", err=True)
70
+ sys.exit(1)
71
+
72
+ box = _load(allow_install, allow_functions)
73
+ click.echo(_banner(box, allow_install, allow_functions), err=True)
74
+ sys.exit(stdio.run(Dispatcher(box)))
75
+
76
+
77
+ def _load(allow_install: bool, allow_functions: bool) -> Toolbox:
78
+ try:
79
+ return _toolbox(allow_install, allow_functions)
80
+ except CatalogError as exc:
81
+ click.echo(f"error: {exc}", err=True)
82
+ sys.exit(1)
83
+
84
+
85
+ def _print_tools(box: Toolbox) -> None:
86
+ width = max((len(n) for n in box.names()), default=0)
87
+ for name in box.names():
88
+ tool = box.get(name)
89
+ first = (tool.description.splitlines() or [""])[0]
90
+ click.echo(f"{name:<{width}} [{box.gate(name).value}] {first}")
dev_setup/mcp/core.py CHANGED
@@ -1,18 +1,39 @@
1
- """What the MCP server runs and what it will let a client reach (docs/specs/mcp).
1
+ """What the MCP server runs, what it will let a client reach, and how it answers (docs/specs/mcp).
2
2
 
3
- Pure: no I/O, no sockets, no processes. Everything here is decided from data, so the whole table
4
- is tested without a server — the reason `profile.py` and `apply_plan.py` are built the same way.
3
+ No sockets, no processes, no file descriptors: a transport hands this module text or a decoded
4
+ frame and gets text or a dict back. That is what lets gating, binding, errors, version
5
+ negotiation and the probe lifecycle be tested with hand-built frames — the reason `profile.py`
6
+ and `apply_plan.py` are built the same way.
5
7
 
6
- M-1 holds only the classification (FR-1a). Dispatch, the probe lifecycle and the JSON-RPC
7
- handling arrive in M-2 and read the same classified toolbox, so listing and calling cannot
8
- disagree about what exists (FR-3).
8
+ Three things are decided here and nowhere else:
9
+
10
+ * **What exists** (`Toolbox`): every entry is classified by what it *runs* (FR-1a) and anything
11
+ not exposed is simply absent. Listing and calling read the same object, so there is no second
12
+ path that skips the check (FR-3).
13
+ * **How a call runs** (`Dispatcher.call`): bad arguments and failing bridges become tool errors
14
+ the model can read, never protocol errors (FR-5, FR-6); mutations are serialised and reads are
15
+ never blocked (FR-8); the process-lifetime probe memos are kept honest (FR-8a).
16
+ * **What goes on the wire** (`Dispatcher.handle`): JSON-RPC 2.0 for MCP (FR-15–18).
9
17
  """
10
18
 
11
19
  from __future__ import annotations
12
20
 
21
+ import json
22
+ import re
23
+ import sys
24
+ import threading
25
+ import traceback
26
+ from collections.abc import Callable, Mapping
27
+ from dataclasses import dataclass
13
28
  from enum import StrEnum
29
+ from typing import Any
14
30
 
31
+ from dev_setup import __version__
32
+ from dev_setup.agent import bridges
15
33
  from dev_setup.agent.registry import AgentTool
34
+ from dev_setup.agent.sandbox import SandboxError
35
+
36
+ # -- Classification (FR-1a) -----------------------------------------------------------------
16
37
 
17
38
 
18
39
  class Gate(StrEnum):
@@ -64,3 +85,359 @@ def is_exposed(gate: Gate, *, allow_install: bool, allow_functions: bool) -> boo
64
85
  if gate is Gate.FUNCTION:
65
86
  return allow_functions
66
87
  return False
88
+
89
+
90
+ # -- The toolbox (FR-1, FR-16b, FR-16c) ---------------------------------------------------------
91
+
92
+ # The constraint Claude's tool API applies once a client prefixes a name (`mcp__devstuff__<key>`).
93
+ TOOL_NAME = re.compile(r"[a-zA-Z0-9_-]{1,64}")
94
+ # Names the server itself uses. `GET /tools` is an OpenAPI operation named this (FR-22), so a tool
95
+ # with the same key would produce two operations with one operationId.
96
+ RESERVED_NAMES = frozenset({"openai_tool_list"})
97
+
98
+
99
+ class UnknownTool(LookupError):
100
+ """The name is not in the toolbox — never existed, or exists behind a flag that is off.
101
+ The two are deliberately indistinguishable to a caller (FR-3)."""
102
+
103
+
104
+ class Toolbox:
105
+ """The tools a server started with these flags exposes, and the gate each sits behind."""
106
+
107
+ def __init__(self, tools: Mapping[str, AgentTool], gates: Mapping[str, Gate]) -> None:
108
+ self._tools = dict(tools)
109
+ self._gates = dict(gates)
110
+
111
+ @classmethod
112
+ def from_agent(
113
+ cls,
114
+ agent_tools: Mapping[str, AgentTool],
115
+ *,
116
+ allow_install: bool,
117
+ allow_functions: bool,
118
+ warn: Callable[[str], None],
119
+ ) -> Toolbox:
120
+ """Filter the agent's effective toolbox down to what this surface may expose.
121
+
122
+ A tool that is *expected* to be absent (a primitive, a gated tool whose flag is off) is
123
+ dropped silently. One that is absent for a reason the user should know — an entry no
124
+ classification covers, a name a client would reject — is dropped with a warning rather
125
+ than breaking the client's whole `tools/list` (FR-16b).
126
+ """
127
+ tools: dict[str, AgentTool] = {}
128
+ gates: dict[str, Gate] = {}
129
+ for key, tool in agent_tools.items():
130
+ gate = classify(tool)
131
+ if gate is Gate.PRIMITIVE:
132
+ continue
133
+ if gate is Gate.UNCLASSIFIED:
134
+ warn(
135
+ f"tool '{key}' left out: it runs '{tool.target or tool.impl}', which devstuff mcp "
136
+ "does not know how to gate, so it is not exposed"
137
+ )
138
+ continue
139
+ if not is_exposed(gate, allow_install=allow_install, allow_functions=allow_functions):
140
+ continue
141
+ if not TOOL_NAME.fullmatch(key) or key in RESERVED_NAMES:
142
+ warn(
143
+ f"tool '{key}' left out: a tool name must match [a-zA-Z0-9_-]{{1,64}} "
144
+ f"and not be reserved ({', '.join(sorted(RESERVED_NAMES))})"
145
+ )
146
+ continue
147
+ tools[key] = tool
148
+ gates[key] = gate
149
+ return cls(tools, gates)
150
+
151
+ def names(self) -> list[str]:
152
+ return list(self._tools)
153
+
154
+ def get(self, name: str) -> AgentTool | None:
155
+ return self._tools.get(name)
156
+
157
+ def gate(self, name: str) -> Gate:
158
+ return self._gates[name]
159
+
160
+ def input_schema(self, tool: AgentTool) -> dict[str, Any]:
161
+ """FR-16c: `required` omitted when empty (older JSON Schema drafts reject `[]`) and extra
162
+ properties forbidden, so a client's schema check agrees with `bind()`'s own rule."""
163
+ schema = tool.to_schema()["function"]["parameters"]
164
+ out: dict[str, Any] = {"type": "object", "properties": schema["properties"]}
165
+ if schema.get("required"):
166
+ out["required"] = schema["required"]
167
+ out["additionalProperties"] = False
168
+ return out
169
+
170
+ def describe(self) -> list[dict[str, Any]]:
171
+ """The MCP `tools/list` entries."""
172
+ return [
173
+ {
174
+ "name": key,
175
+ "title": tool.name,
176
+ "description": tool.description,
177
+ "inputSchema": self.input_schema(tool),
178
+ }
179
+ for key, tool in self._tools.items()
180
+ ]
181
+
182
+
183
+ # -- Results (FR-7) --------------------------------------------------------------------------
184
+
185
+
186
+ @dataclass(frozen=True)
187
+ class ToolResult:
188
+ """What a call produced. `note` is advisory and kept *out of* `text` so a JSON array in `text`
189
+ stays parseable (FR-7): MCP carries it as a second text item, REST as its own field."""
190
+
191
+ is_error: bool
192
+ text: str
193
+ note: str = ""
194
+
195
+
196
+ INSTALL_NOTE = "an install is in progress; this may change"
197
+
198
+
199
+ def to_mcp_result(result: ToolResult) -> dict[str, Any]:
200
+ content = [{"type": "text", "text": result.text}]
201
+ if result.note:
202
+ content.append({"type": "text", "text": result.note})
203
+ return {"content": content, "isError": result.is_error}
204
+
205
+
206
+ def _install_hint(key: str) -> str:
207
+ # FR-13. Appended to *every* install failure, not keyed on sudo's wording: under -v the error
208
+ # is only "exit code 1" and sudo's line never reaches the result (F-13).
209
+ return (
210
+ f" If this needed a password, it cannot be answered here (the server has no terminal): "
211
+ f"run `devstuff install {key}` in a terminal."
212
+ )
213
+
214
+
215
+ # -- Dispatch (FR-3, FR-5, FR-6, FR-8, FR-8a) ----------------------------------------------------
216
+
217
+
218
+ def _invoke(tool: AgentTool, bound: dict[str, Any]) -> str:
219
+ """Run one bound call. No workspace, no agent config (FR-4, F-5)."""
220
+ if tool.impl == "function":
221
+ return bridges.run_function(None, None, tool.target or "", bound) # type: ignore[arg-type]
222
+ bridge = bridges.get(tool.target or "")
223
+ if bridge is None: # unreachable while test_every_bridge_has_a_gate holds
224
+ raise SandboxError(f"no bridge named '{tool.target}'")
225
+ return bridge(None, None, bound) # type: ignore[arg-type]
226
+
227
+
228
+ def _log_to_stderr(message: str) -> None:
229
+ sys.stderr.write(message.rstrip("\n") + "\n")
230
+
231
+
232
+ def _forget_probes() -> None:
233
+ from dev_setup import generic
234
+
235
+ generic.forget_probes()
236
+
237
+
238
+ class Dispatcher:
239
+ """Runs calls against a `Toolbox` and speaks JSON-RPC for them.
240
+
241
+ `run`, `forget` and `log_error` are injectable so the state machine below is tested with a
242
+ fake machine; the defaults are the real bridges, `generic.forget_probes` and stderr.
243
+ """
244
+
245
+ def __init__(
246
+ self,
247
+ toolbox: Toolbox,
248
+ *,
249
+ run: Callable[[AgentTool, dict[str, Any]], str] = _invoke,
250
+ forget: Callable[[], None] = _forget_probes,
251
+ log_error: Callable[[str], None] = _log_to_stderr,
252
+ ) -> None:
253
+ self.toolbox = toolbox
254
+ self._run = run
255
+ self._forget = forget
256
+ self._log_error = log_error
257
+ # FR-8: one mutation at a time, across *both* gated classes — apt's lock and shared
258
+ # prefixes do not care which flag started the install.
259
+ self._mutation = threading.Lock()
260
+ # FR-8a: the state below is guarded by `_state`. `_mutations` is bumped when a gated call
261
+ # starts and again when it ends, so a read that sees it unchanged saw no mutation at all.
262
+ self._state = threading.Lock()
263
+ self._readers = 0
264
+ self._mutations = 0
265
+ self._running = 0
266
+
267
+ # -- one call ---------------------------------------------------------------------------
268
+
269
+ def call(self, name: str, arguments: dict[str, Any] | None = None) -> ToolResult:
270
+ """Run a tool. Raises `UnknownTool` for a name that is absent or gated off; everything
271
+ else — bad arguments, a bridge that fails, one that crashes — is a `ToolResult`."""
272
+ tool = self.toolbox.get(name)
273
+ if tool is None:
274
+ raise UnknownTool(name)
275
+ try:
276
+ bound = tool.bind(arguments or {})
277
+ except ValueError as exc:
278
+ return ToolResult(True, str(exc))
279
+
280
+ if self.toolbox.gate(name) is Gate.READ_ONLY:
281
+ return self._read(tool, bound)
282
+ return self._mutate(tool, bound)
283
+
284
+ def _execute(self, tool: AgentTool, bound: dict[str, Any]) -> ToolResult:
285
+ """One run of one bridge, with every failure turned into a result (FR-6)."""
286
+ try:
287
+ return ToolResult(False, self._run(tool, bound))
288
+ except bridges.InstallFailed as exc:
289
+ return ToolResult(True, str(exc) + _install_hint(str(bound.get("key", "<key>"))))
290
+ except SandboxError as exc:
291
+ return ToolResult(True, str(exc))
292
+ except SystemExit as exc:
293
+ # A bridge that exits would end its worker thread without ever answering the client.
294
+ return ToolResult(True, f"{tool.key} exited unexpectedly (status {exc.code})")
295
+ except Exception as exc:
296
+ self._log_error(f"{tool.key}: {traceback.format_exc()}")
297
+ first = (str(exc).splitlines() or [""])[0]
298
+ return ToolResult(True, f"{type(exc).__name__}: {first}" if first else type(exc).__name__)
299
+
300
+ def _mutate(self, tool: AgentTool, bound: dict[str, Any]) -> ToolResult:
301
+ with self._mutation:
302
+ with self._state:
303
+ self._mutations += 1
304
+ self._running += 1
305
+ try:
306
+ return self._execute(tool, bound)
307
+ finally:
308
+ # In `finally`: a failure part-way may already have changed the machine, and a
309
+ # memo that says otherwise would be served until the process exits (FR-8a.2).
310
+ try:
311
+ self._forget()
312
+ finally:
313
+ with self._state:
314
+ self._mutations += 1
315
+ self._running -= 1
316
+
317
+ def _read(self, tool: AgentTool, bound: dict[str, Any]) -> ToolResult:
318
+ """Run a read-only tool: never blocked by a mutation, never served stale (FR-8a)."""
319
+ with self._state:
320
+ new_burst = self._readers == 0
321
+ self._readers += 1
322
+ try:
323
+ if new_burst:
324
+ # Outside `_state`: clearing takes the lock of any probe still running, and that wait
325
+ # must not stall every other request's bookkeeping. A concurrent reader that joins in
326
+ # the gap at worst re-probes; it can never be handed a half-cleared memo.
327
+ self._forget()
328
+ result, straddled, installing = self._read_once(tool, bound)
329
+ if straddled and not installing and not result.is_error:
330
+ # A mutation began and ended during this read, so it may hold one memo from before
331
+ # and one from after. The mutation is finished, so one clean re-run is exact.
332
+ self._forget()
333
+ result, straddled, installing = self._read_once(tool, bound)
334
+ if (straddled or installing) and not result.is_error:
335
+ result = ToolResult(False, result.text, INSTALL_NOTE)
336
+ return result
337
+ finally:
338
+ with self._state:
339
+ self._readers -= 1
340
+
341
+ def _read_once(self, tool: AgentTool, bound: dict[str, Any]) -> tuple[ToolResult, bool, bool]:
342
+ with self._state:
343
+ before = self._mutations
344
+ result = self._execute(tool, bound)
345
+ with self._state:
346
+ return result, self._mutations != before, self._running > 0
347
+
348
+ # -- JSON-RPC (FR-15 … FR-18) -------------------------------------------------------------
349
+
350
+ def handle_text(self, text: str) -> str | None:
351
+ """One frame of text in, one frame of text out (None for a notification)."""
352
+ try:
353
+ frame = json.loads(text)
354
+ except ValueError:
355
+ return _dump(_error(None, -32700, "parse error"))
356
+ reply = self.handle(frame)
357
+ return None if reply is None else _dump(reply)
358
+
359
+ def handle(self, frame: Any) -> dict[str, Any] | None:
360
+ """One decoded frame in, one reply out. Never raises."""
361
+ if not isinstance(frame, dict):
362
+ # A batch is a JSON array (FR-18); anything else that is not an object is invalid too.
363
+ what = "batch requests are not supported" if isinstance(frame, list) else "invalid request"
364
+ return _error(None, -32600, what)
365
+ # A notification is the *absence* of the `id` key. Never a falsy value: Claude Code sends an
366
+ # integer 0 for `initialize` and an empty-looking id must still be answered (FR-16a).
367
+ notification = "id" not in frame
368
+ rid = frame.get("id")
369
+ method = frame.get("method")
370
+ if not isinstance(method, str):
371
+ return _error(None if notification else rid, -32600, "invalid request: no method")
372
+ try:
373
+ result = self._method(method, frame.get("params"))
374
+ except _RpcError as exc:
375
+ reply = _error(rid, exc.code, exc.message)
376
+ else:
377
+ reply = {"jsonrpc": "2.0", "id": rid, "result": result}
378
+ return None if notification else reply
379
+
380
+ def _method(self, method: str, params: Any) -> dict[str, Any]:
381
+ if method == "initialize":
382
+ return self._initialize(params)
383
+ if method == "ping":
384
+ return {}
385
+ if method == "tools/list":
386
+ return {"tools": self.toolbox.describe()}
387
+ if method == "tools/call":
388
+ return self._tools_call(params)
389
+ # Everything else — `server/discover`, resources/*, prompts/*, notifications — is "method not
390
+ # found". The current official client opens with `server/discover` and falls back to
391
+ # `initialize` only when told it is unknown; an empty result would stall it (F-2, FR-16).
392
+ raise _RpcError(-32601, f"method not found: {method}")
393
+
394
+ def _initialize(self, params: Any) -> dict[str, Any]:
395
+ wanted = params.get("protocolVersion") if isinstance(params, dict) else None
396
+ # Echo a version we support; otherwise answer with our own latest and let the client decide.
397
+ # Never refuse a session over a version (FR-17).
398
+ version = wanted if wanted in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0]
399
+ return {
400
+ "protocolVersion": version,
401
+ "capabilities": {"tools": {}},
402
+ "serverInfo": {"name": "devstuff", "version": __version__},
403
+ }
404
+
405
+ def _tools_call(self, params: Any) -> dict[str, Any]:
406
+ if not isinstance(params, dict) or not isinstance(params.get("name"), str):
407
+ raise _RpcError(-32602, "invalid params: 'name' (a string) is required")
408
+ arguments = params.get("arguments")
409
+ if arguments is None:
410
+ arguments = {}
411
+ if not isinstance(arguments, dict):
412
+ raise _RpcError(-32602, "invalid params: 'arguments' must be an object")
413
+ name = params["name"]
414
+ try:
415
+ return to_mcp_result(self.call(name, arguments))
416
+ except UnknownTool:
417
+ raise _RpcError(-32602, f"unknown tool: {name}") from None
418
+
419
+
420
+ # Newest first. The only version the real client was measured to send is 2025-11-25 (F-2, F-3).
421
+ PROTOCOL_VERSIONS = ("2025-11-25",)
422
+
423
+
424
+ class _RpcError(Exception):
425
+ def __init__(self, code: int, message: str) -> None:
426
+ super().__init__(message)
427
+ self.code = code
428
+ self.message = message
429
+
430
+
431
+ def error_text(rid: Any, code: int, message: str) -> str:
432
+ """A ready-to-send error frame, for a transport that must answer before a frame is parsed."""
433
+ return _dump(_error(rid, code, message))
434
+
435
+
436
+ def _error(rid: Any, code: int, message: str) -> dict[str, Any]:
437
+ return {"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": message}}
438
+
439
+
440
+ def _dump(frame: dict[str, Any]) -> str:
441
+ # ensure_ascii escapes U+2028 and friends as well as newlines, so a frame can never contain
442
+ # a character any line-oriented reader might split on (FR-19).
443
+ return json.dumps(frame, separators=(",", ":"))
@@ -0,0 +1,120 @@
1
+ """FR-11a: give the server no controlling terminal (docs/specs/mcp, F-11, SD-12).
2
+
3
+ A `/dev/null` stdin is not "no terminal": `sudo` opens `/dev/tty` directly and prompted on the
4
+ user's terminal even with fd 0 closed off (F-11). An installer waiting on a password nobody can
5
+ type would hang the client's request, so the server detaches at the *process* level, before the
6
+ fd move and before any tool can run.
7
+
8
+ `os.setsid()` does it when a client spawned the server. A shell starting `devstuff mcp --http`
9
+ makes the process a group leader, where `setsid` fails with `EPERM`; then the process forks, the
10
+ child calls `setsid` and is the server, and the original stays behind as a thin supervisor that
11
+ forwards signals and mirrors the exit status — so Ctrl-C and a closed terminal still stop it even
12
+ though it no longer owns the terminal.
13
+
14
+ The alternative, `start_new_session=True` on each of the six subprocess call sites, is the
15
+ per-call-site audit FR-11 already refuses to depend on: the next `subprocess` anyone writes would
16
+ silently reopen it.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import errno
22
+ import os
23
+ import signal
24
+ from collections.abc import Callable
25
+
26
+
27
+ class TerminalReachable(RuntimeError):
28
+ """The server could not give up its controlling terminal and may run an installer."""
29
+
30
+
31
+ def detach(
32
+ *,
33
+ setsid: Callable[[], object] = os.setsid,
34
+ fork: Callable[[], int] = os.fork,
35
+ supervise: Callable[[int], object] | None = None,
36
+ ) -> str:
37
+ """Leave the controlling terminal. Returns how: `"setsid"`, `"forked"` (this is the server
38
+ child), or — only when a test injects `supervise` — `"supervisor"`. The real supervisor never
39
+ returns; it exits with the server's status."""
40
+ try:
41
+ setsid()
42
+ return "setsid"
43
+ except OSError as exc:
44
+ if exc.errno != errno.EPERM:
45
+ raise # not the group-leader case: do not paper over an unexpected failure
46
+ pid = fork()
47
+ if pid == 0:
48
+ setsid() # the child is not a group leader, so this one cannot fail with EPERM
49
+ return "forked"
50
+ (supervise or _supervise)(pid)
51
+ return "supervisor"
52
+
53
+
54
+ def _supervise(child: int) -> None:
55
+ """Forward signals to the server and exit with its status. Never returns."""
56
+ # This process keeps no copy of the client's stdio: the server child owns the channel, and a
57
+ # supervisor holding the pipe open would keep a peer from seeing EOF when the server exits.
58
+ for fd in (0, 1):
59
+ try:
60
+ os.close(fd)
61
+ except OSError:
62
+ pass
63
+
64
+ def forward(signum: int, _frame: object) -> None:
65
+ # SIGHUP is what a closing terminal sends. The server is in its own session and would never
66
+ # see it, so it would be orphaned and keep running: it is turned into the polite stop.
67
+ target = signal.SIGTERM if signum == signal.SIGHUP else signum
68
+ try:
69
+ os.kill(child, target)
70
+ except ProcessLookupError:
71
+ pass
72
+
73
+ for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
74
+ signal.signal(sig, forward)
75
+
76
+ while True:
77
+ try:
78
+ _, status = os.waitpid(child, 0)
79
+ break
80
+ except InterruptedError:
81
+ continue
82
+ except ChildProcessError:
83
+ os._exit(1)
84
+ code = os.waitstatus_to_exitcode(status)
85
+ # A signalled child reads as 128+N, the shell's convention, so a caller can tell it from a status.
86
+ os._exit(code if code >= 0 else 128 - code)
87
+
88
+
89
+ def terminal_reachable(*, open_: Callable[..., int] = os.open) -> bool:
90
+ """Can this process open `/dev/tty`? `O_NOCTTY` so asking never acquires one as a side effect."""
91
+ try:
92
+ fd = open_("/dev/tty", os.O_RDWR | os.O_NOCTTY)
93
+ except OSError:
94
+ return False # ENXIO (no controlling terminal), ENOENT (a container) — either way, none
95
+ try:
96
+ os.close(fd)
97
+ except OSError:
98
+ pass
99
+ return True
100
+
101
+
102
+ def require_no_terminal(
103
+ *,
104
+ gated: bool,
105
+ warn: Callable[[str], None],
106
+ reachable: Callable[[], bool] | None = None,
107
+ ) -> None:
108
+ """Verify the detach worked, and fail closed (FR-11a.3).
109
+
110
+ With a gate flag on, the server can run an installer, so a reachable terminal is a refusal to
111
+ start — nothing that can prompt for a password starts while one is reachable. Read-only, there
112
+ is nothing that prompts, so it warns and continues."""
113
+ if not (reachable or terminal_reachable)():
114
+ return
115
+ if gated:
116
+ raise TerminalReachable(
117
+ "could not detach from the controlling terminal, and --allow-install/--allow-functions "
118
+ "can run an installer that would prompt on it; refusing to start"
119
+ )
120
+ warn("still attached to a controlling terminal (read-only tools never prompt, so continuing)")
dev_setup/mcp/stdio.py ADDED
@@ -0,0 +1,158 @@
1
+ """The stdio transport: newline-delimited JSON-RPC over a private channel (docs/specs/mcp).
2
+
3
+ The protocol owns stdout, and devstuff writes to stdout from places nobody can audit for good: the
4
+ Rich console, `_run`'s verbose branch, `function_runner`, and every child process (F-1). So the
5
+ channel is moved at the *descriptor* level, before any tool can run — private `dup`s of the real
6
+ stdin and stdout, then fd 1 pointed at stderr and fd 0 at `/dev/null`. After that there is no path
7
+ by which a stray byte can reach the client: stdout has no way to *be* the protocol.
8
+
9
+ Requests run on their own threads, because a read must not wait behind an install that takes
10
+ minutes (FR-8, FR-8a). Replies are written under one lock, one line each.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import os
16
+ import signal
17
+ import sys
18
+ import threading
19
+ from dataclasses import dataclass
20
+ from typing import BinaryIO
21
+
22
+ from dev_setup import verbose
23
+ from dev_setup.mcp.core import Dispatcher, error_text
24
+
25
+ MAX_FRAME = 1024 * 1024 # FR-18: a request over 1 MiB is refused
26
+
27
+
28
+ @dataclass
29
+ class Channel:
30
+ """The client's end of the conversation, on descriptors nothing else holds."""
31
+
32
+ rfile: BinaryIO
33
+ wfile: BinaryIO
34
+
35
+
36
+ def isolate_stdio() -> Channel:
37
+ """Move the protocol onto private descriptors and repoint the standard ones (FR-11).
38
+
39
+ The private fds are not inheritable (PEP 446 makes `os.dup` results so), so no child can read
40
+ from or write to the channel; fd 0 and fd 1 stay inheritable, so a child that reads stdin sees
41
+ EOF and one that writes stdout lands on stderr.
42
+ """
43
+ for stream in (sys.stdout, sys.stderr):
44
+ try:
45
+ stream.flush()
46
+ except (OSError, ValueError):
47
+ pass
48
+ in_fd = os.dup(0)
49
+ out_fd = os.dup(1)
50
+ devnull = os.open(os.devnull, os.O_RDONLY)
51
+ os.dup2(devnull, 0)
52
+ os.close(devnull)
53
+ os.dup2(2, 1)
54
+ # Unbuffered out: a reply is written whole and at once, and there is no buffer left holding a
55
+ # frame a dead client never took (which would be flushed, and fail, again at interpreter exit).
56
+ return Channel(os.fdopen(in_fd, "rb"), os.fdopen(out_fd, "wb", buffering=0))
57
+
58
+
59
+ class _Shutdown(Exception):
60
+ """Raised by the first SIGINT/SIGTERM to break the main thread out of a blocking read."""
61
+
62
+
63
+ def serve(
64
+ dispatcher: Dispatcher, rfile: BinaryIO, wfile: BinaryIO, *, max_frame: int = MAX_FRAME
65
+ ) -> int:
66
+ """Read frames until EOF (or a shutdown), answer each, and return the exit status.
67
+
68
+ On the way out it waits for every request still running: an installer killed half-way is worse
69
+ than one waited for (FR-30), and a reply to a call that was already accepted is still owed.
70
+ """
71
+ write_lock = threading.Lock()
72
+ workers: list[threading.Thread] = []
73
+
74
+ def reply(text: str) -> None:
75
+ view = memoryview(text.encode("utf-8") + b"\n")
76
+ with write_lock:
77
+ try:
78
+ while view: # a raw file may take less than all of it
79
+ written = wfile.write(view)
80
+ view = view[written:] if written else view
81
+ wfile.flush()
82
+ except (OSError, ValueError):
83
+ # The client has gone. The next read says so (EOF); until then there is nobody to
84
+ # tell, and a write error must never take the loop down.
85
+ pass
86
+
87
+ def work(line: bytes) -> None:
88
+ try:
89
+ text = line.decode("utf-8")
90
+ except UnicodeDecodeError:
91
+ out: str | None = error_text(None, -32700, "parse error: not valid UTF-8")
92
+ else:
93
+ verbose.log(f"mcp ← {_clip(text)}")
94
+ out = dispatcher.handle_text(text)
95
+ if out is not None:
96
+ verbose.trace(f"mcp → {_clip(out)}")
97
+ reply(out)
98
+
99
+ try:
100
+ while True:
101
+ line = rfile.readline(max_frame + 1)
102
+ if not line:
103
+ break # EOF
104
+ if len(line) > max_frame and not line.endswith(b"\n"):
105
+ _discard_line(rfile)
106
+ reply(error_text(None, -32600, f"request too large (limit {max_frame} bytes)"))
107
+ continue
108
+ if not line.strip():
109
+ continue
110
+ workers = [w for w in workers if w.is_alive()]
111
+ worker = threading.Thread(target=work, args=(line,), name="mcp-request")
112
+ workers.append(worker)
113
+ worker.start()
114
+ except _Shutdown:
115
+ pass
116
+
117
+ while True:
118
+ try:
119
+ for worker in workers:
120
+ worker.join()
121
+ break
122
+ except _Shutdown:
123
+ continue # a first signal that arrived late: still wait; a second one exits at once
124
+ return 0
125
+
126
+
127
+ def _discard_line(rfile: BinaryIO) -> None:
128
+ """Drop the rest of an over-long line, so its tail is not read as the next frame."""
129
+ while True:
130
+ chunk = rfile.readline(64 * 1024)
131
+ if not chunk or chunk.endswith(b"\n"):
132
+ return
133
+
134
+
135
+ def _clip(text: str, limit: int = 300) -> str:
136
+ text = text.rstrip("\n")
137
+ return text if len(text) <= limit else text[:limit] + f"… (+{len(text) - limit} chars)"
138
+
139
+
140
+ def run(dispatcher: Dispatcher) -> int:
141
+ """Isolate stdio, install the shutdown signals, and serve until the client goes away.
142
+
143
+ The first SIGINT/SIGTERM stops reading new requests and lets the running ones finish; a second
144
+ exits immediately (FR-30).
145
+ """
146
+ channel = isolate_stdio()
147
+ received = 0
148
+
149
+ def on_signal(signum: int, _frame: object) -> None:
150
+ nonlocal received
151
+ received += 1
152
+ if received > 1:
153
+ os._exit(128 + signum)
154
+ raise _Shutdown
155
+
156
+ signal.signal(signal.SIGINT, on_signal)
157
+ signal.signal(signal.SIGTERM, on_signal)
158
+ return serve(dispatcher, channel.rfile, channel.wfile)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: devstuff
3
- Version: 2.15.0
3
+ Version: 2.16.0
4
4
  Summary: Development environment setup CLI for Linux
5
5
  Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
6
6
  Author-email: Sawyer <sawyerksu@gmail.com>
@@ -1159,6 +1159,33 @@ confirmation.
1159
1159
 
1160
1160
  ---
1161
1161
 
1162
+ ## MCP server (`devstuff mcp`)
1163
+
1164
+ `devstuff mcp` serves devstuff's tools to an MCP client over **stdio**. It is started *by* the client, not by
1165
+ hand. Register it with Claude Code:
1166
+
1167
+ ```bash
1168
+ claude mcp add devstuff -- devstuff mcp # read-only tools only
1169
+ claude mcp add devstuff -- devstuff mcp --allow-install # also install_tool
1170
+ ```
1171
+
1172
+ | Flag | Effect |
1173
+ |---|---|
1174
+ | *(none)* | `list_tools`, `search_catalog`, `tool_info`, `outdated`, `profile_diff` — nothing that changes the machine |
1175
+ | `--allow-install` | adds `install_tool`, which installs a catalog tool as you |
1176
+ | `--allow-functions` | adds every `type: script` function as `fn_<key>` |
1177
+ | `--list-tools` | print what these flags would expose, and which gate each tool sits behind; starts nothing |
1178
+
1179
+ A tool whose flag is off is not hidden but **absent and refused**: a call naming it is answered as an unknown tool.
1180
+ Workspace tools (`read_file`, `run_command`, …) never exist here — the client already has files and a shell.
1181
+
1182
+ The server has **no terminal**: an installer that needs a `sudo` password fails at once with a message telling the
1183
+ client to run `devstuff install <key>` in a terminal, rather than waiting for a password nobody can type.
1184
+ Logs (`-v`, `-vv`) go to stderr. HTTP and OpenAPI front ends are still to come; see
1185
+ [`docs/specs/mcp/`](docs/specs/mcp/).
1186
+
1187
+ ---
1188
+
1162
1189
  ## Agent
1163
1190
 
1164
1191
  `devstuff agent` opens an interactive session with a **local** model (via [Ollama](https://ollama.com))
@@ -7,7 +7,7 @@ dev_setup/apply_plan.py,sha256=L_ZmSGnjM7T1hKT7RLXSvCZgjbRpX_AaTKg5N9fp1zs,8474
7
7
  dev_setup/base.py,sha256=j2EQ5gzeGgtveWQN_BgbLcZianMENJ7PQy8EQ9J9MPE,1946
8
8
  dev_setup/bundles.py,sha256=h-WdjwNI82SQCgXiJ-EoiwuI81umb09Q0NNUYyzH1FI,2285
9
9
  dev_setup/catalog.py,sha256=PrimTBUYoh8cW9QYhXUxP8qSMeK51kzQjUoPEGD9EBw,6530
10
- dev_setup/cli.py,sha256=M4si1b2yZ44Y3zfdwF-D0v__ZhDnemLl8vLrFKonWDg,3320
10
+ dev_setup/cli.py,sha256=KHdraEvcUf1IqSLkGjXyChSccBduPPvxvNefWfL4qzg,3407
11
11
  dev_setup/doctor.py,sha256=1shwNLT5wFxiGT5oBVqbF478B7lcHVwT_e50aFb2I20,16962
12
12
  dev_setup/function_runner.py,sha256=08F6jvB9-oOyE5ivYtRjnL16JTGsfRnkpvkjSVrJhsM,6957
13
13
  dev_setup/functions.schema.json,sha256=VVdpH3xWsdbtqw47S1QqpBcs4O9wd3XZ_s0Q3sGwv0Q,6220
@@ -28,7 +28,7 @@ dev_setup/updates.py,sha256=p9_nbfaX_73hE71kr5ZDZA5o85T9XTR0mjbo15f950I,6046
28
28
  dev_setup/verbose.py,sha256=N3U9JAYOvFwdd8DT6W7Pqq6RCIUfbcQnPsm0O1TnvQY,5003
29
29
  dev_setup/agent/__init__.py,sha256=znrgxUCr_y0Qp-f41S6EaTv-hoTYwoZ9mOMLVge-IJg,226
30
30
  dev_setup/agent/approval.py,sha256=DNPV5iM_UpCx39xFzCu8kyr03tjfyfD7iVcTfQMJRwY,3630
31
- dev_setup/agent/bridges.py,sha256=eTn5Sj9OET_o8Ntctub6DJjndM8bjywDeEbjYrdtDPE,7541
31
+ dev_setup/agent/bridges.py,sha256=m1e5bYLib8jwvi7uKvOQwnuKv6sG3f98uhZjzWSoyfs,7858
32
32
  dev_setup/agent/catalog.py,sha256=yh4x50GuUwwk6IaESDbosbTU4ehCsITUCWG0-BuAAFk,6313
33
33
  dev_setup/agent/completion.py,sha256=BhreXV0MwyMejAFmXe6gX6h64nTH713RIy-Dy0KK-Ig,1854
34
34
  dev_setup/agent/config.py,sha256=a0vagUWyKd1MOBsdJeNGVRlAGZdqfozPRNJyNxXN16Q,5970
@@ -61,6 +61,7 @@ dev_setup/commands/help_cmd.py,sha256=O2dnhqsMZx5tVHdJVixixCJwc9TYlKdlZ2vYYPApl0
61
61
  dev_setup/commands/install_cmd.py,sha256=YgVm8r2RevoSrfBBAvZpDmL0NOQFdOGTFp3aIx-9xwo,8519
62
62
  dev_setup/commands/links_cmd.py,sha256=kvnoBXdM9QWRZRIwWgnmWqVkOYE7AZxywFTQD5_Uwv4,4924
63
63
  dev_setup/commands/list_cmd.py,sha256=Env6bwAmREDek4L-ZB2CIfvLT4PgaKcz5sQKJ1GhL8g,2913
64
+ dev_setup/commands/mcp_cmd.py,sha256=JPPIvSYXWHHwg9IZA2KsZ0KeIc1kD-X_iVsc231Fn58,3291
64
65
  dev_setup/commands/outdated_cmd.py,sha256=afwYyq0M-tWVOk2qyXQqsdWSTK6yuFbVpbrOmMPKS_w,4757
65
66
  dev_setup/commands/profile_cmd.py,sha256=jo7al_nBwuWtzOLYKjcqEGmHp4eQrzM5s7ahv6iiGaw,18299
66
67
  dev_setup/commands/remove_cmd.py,sha256=Az0qMes4M5237c_ntQ1SemS38gTpLZy2GhSK_gUrw3s,4974
@@ -114,8 +115,10 @@ dev_setup/configure/starship/preview.py,sha256=ZaNhNA3AeHHtPnMqrJbB9XVVXDFbH1R36
114
115
  dev_setup/configure/starship/render.py,sha256=25O8w4IteVd_ELwmIWhcYAn042W6yZ--zbTMcJpzVJc,11277
115
116
  dev_setup/configure/starship/wizard.py,sha256=F3-xVQmZjYtiQAICyJXeSogjcASSsVbaP2b8YHAX9TM,28726
116
117
  dev_setup/mcp/__init__.py,sha256=a3DUEjK_mIpC4QsaPaArwKqaVvtujfzSu8WMpMh6G70,89
117
- dev_setup/mcp/core.py,sha256=b79cJAM3W6qLMGW110UlX7KI5JbplO3ptfVEeiUDFc0,2598
118
- devstuff-2.15.0.dist-info/METADATA,sha256=8ekogNHBXp0qG0rp5g3iTPCwNSvzLV2361ajMO55Vz8,93743
119
- devstuff-2.15.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
120
- devstuff-2.15.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
121
- devstuff-2.15.0.dist-info/RECORD,,
118
+ dev_setup/mcp/core.py,sha256=5IlKkPXDUsdyKVbpSw3yDjkmY_92hdXlAOdK_a7SXsA,18898
119
+ dev_setup/mcp/process.py,sha256=IV203HLaCelWb89IhV73_8NWNAGglXRtXpwpHk39dD4,4752
120
+ dev_setup/mcp/stdio.py,sha256=lCd0RIt5dpGR4hWcezm4glwM-_Z2fBZB24JlmjqDF0Q,5753
121
+ devstuff-2.16.0.dist-info/METADATA,sha256=7qsx0pAYrjY7rMRT0_nvoVzHES8qhmbVSGb7aPn2WiQ,95104
122
+ devstuff-2.16.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
123
+ devstuff-2.16.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
124
+ devstuff-2.16.0.dist-info/RECORD,,