devstuff 2.17.0__py3-none-any.whl → 2.18.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.
@@ -2,6 +2,7 @@ from __future__ import annotations
2
2
 
3
3
  import errno
4
4
  import ipaddress
5
+ import os
5
6
  import re
6
7
  import sys
7
8
  from pathlib import Path
@@ -9,7 +10,7 @@ from pathlib import Path
9
10
  import click
10
11
 
11
12
  from dev_setup.catalog import CatalogError
12
- from dev_setup.mcp import http, process, stdio, token
13
+ from dev_setup.mcp import http, printconfig, process, stdio, token
13
14
  from dev_setup.mcp.core import Dispatcher, Toolbox
14
15
 
15
16
  DEFAULT_HOST = "127.0.0.1"
@@ -97,6 +98,12 @@ def _is_loopback(host: str) -> bool:
97
98
  "--list-tools", "list_tools", is_flag=True,
98
99
  help="Print the tools these flags would expose, and which gate each sits behind. Starts nothing.",
99
100
  )
101
+ @click.option(
102
+ "--print-config", "print_config", type=click.Choice(printconfig.TARGETS), default=None, metavar="TARGET",
103
+ help="Print a snippet to paste into a client, for the other flags given, and exit: claude-code (the "
104
+ "`claude mcp add` command), claude-desktop (the mcpServers JSON) or openapi (URLs and header). "
105
+ "Starts nothing, and never contains the token.",
106
+ )
100
107
  def mcp_cmd(
101
108
  use_http: bool,
102
109
  host: str | None,
@@ -108,6 +115,7 @@ def mcp_cmd(
108
115
  allow_install: bool,
109
116
  allow_functions: bool,
110
117
  list_tools: bool,
118
+ print_config: str | None,
111
119
  ) -> None:
112
120
  """Serve devstuff's tools to an MCP client (stdio) or over HTTP, MCP and OpenAPI.
113
121
 
@@ -140,6 +148,14 @@ def mcp_cmd(
140
148
  f"--allow-origin takes an origin like http://localhost:3000, not {origin!r}."
141
149
  )
142
150
 
151
+ if print_config and list_tools:
152
+ raise click.UsageError("--print-config and --list-tools each print and exit; pass one.")
153
+ if print_config:
154
+ _print_config(
155
+ print_config, use_http, host or DEFAULT_HOST, DEFAULT_PORT if port is None else port,
156
+ token_file, allow_install, allow_functions,
157
+ )
158
+ return
143
159
  if list_tools:
144
160
  _print_tools(_load(allow_install, allow_functions))
145
161
  return
@@ -163,6 +179,27 @@ def mcp_cmd(
163
179
  )
164
180
 
165
181
 
182
+ def _print_config(
183
+ target: str, use_http: bool, host: str, port: int, token_file: Path | None,
184
+ allow_install: bool, allow_functions: bool,
185
+ ) -> None:
186
+ path = Path(os.path.abspath(token_file or token.default_path()))
187
+ spec = printconfig.Spec(
188
+ launcher=printconfig.launcher(sys.argv[0], sys.executable), http=use_http, host=host, port=port,
189
+ token_file=path, allow_install=allow_install, allow_functions=allow_functions,
190
+ )
191
+ try:
192
+ rendered = printconfig.render(target, spec)
193
+ except printconfig.ConfigError as exc:
194
+ raise click.UsageError(str(exc)) from exc
195
+ click.echo(rendered.text, nl=False)
196
+ # Notes go to stderr so `--print-config … > file` is the snippet and nothing else.
197
+ for note in rendered.notes:
198
+ _warn(note)
199
+ if use_http and target != "claude-desktop" and not path.exists():
200
+ _warn(f"{path} does not exist yet: the server creates it the first time it starts.")
201
+
202
+
166
203
  def _serve_http(
167
204
  box: Toolbox, dispatcher: Dispatcher, host: str, port: int, token_file: Path | None,
168
205
  rotate: bool, allow_origins: tuple[str, ...], allow_hosts: tuple[str, ...], enabled: str,
dev_setup/mcp/core.py CHANGED
@@ -413,8 +413,9 @@ class Dispatcher:
413
413
  if method == "tools/call":
414
414
  return self._tools_call(params)
415
415
  # Everything else — `server/discover`, resources/*, prompts/*, notifications — is "method not
416
- # found". The current official client opens with `server/discover` and falls back to
417
- # `initialize` only when told it is unknown; an empty result would stall it (F-2, FR-16).
416
+ # found", which is JSON-RPC's own answer for a method a server does not implement. The current
417
+ # official client opens with `server/discover` and falls back to `initialize`. Neither real client
418
+ # *enforces* -32601 (both also fall back on `{}`, F-16), so only a raw-frame test pins it.
418
419
  raise _RpcError(-32601, f"method not found: {method}")
419
420
 
420
421
  def _initialize(self, params: Any) -> dict[str, Any]:
@@ -0,0 +1,146 @@
1
+ """`devstuff mcp --print-config TARGET`: a snippet to paste into a client (docs/specs/mcp, FR-31, F-16).
2
+
3
+ Pure: it formats what it is given and touches no file, socket or process. The one secret on the page,
4
+ the bearer token, is a *path* in every snippet — the client's own shell reads the file when the command
5
+ runs — so a snippet is safe to paste into a ticket or a chat.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import os
12
+ import shlex
13
+ from dataclasses import dataclass
14
+ from pathlib import Path
15
+
16
+ TARGETS = ("claude-code", "claude-desktop", "openapi")
17
+ NAME = "devstuff"
18
+
19
+ _WILDCARDS = ("", "0.0.0.0", "::") # "every address": a place to listen, not a place to connect
20
+
21
+
22
+ class ConfigError(ValueError):
23
+ """A snippet that cannot be printed honestly for these flags."""
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class Spec:
28
+ launcher: tuple[str, ...]
29
+ http: bool
30
+ host: str
31
+ port: int
32
+ token_file: Path
33
+ allow_install: bool
34
+ allow_functions: bool
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class Rendered:
39
+ text: str
40
+ notes: tuple[str, ...] = ()
41
+
42
+
43
+ def launcher(argv0: str, executable: str) -> tuple[str, ...]:
44
+ """How to start the devstuff that is running now, as absolute words.
45
+
46
+ A GUI application usually does not inherit the shell's `PATH`, so a bare `devstuff` would work in
47
+ a terminal and fail in Claude Desktop. A console script keeps the path it was started by (a
48
+ symlink such as `~/.local/bin/devstuff` is stable; the venv it points into is not). Anything else
49
+ — `python -m dev_setup`, the `./devstuff` wrapper — is this interpreter running the module, which
50
+ is exactly the code that is answering.
51
+ """
52
+ if argv0:
53
+ candidate = Path(argv0)
54
+ if candidate.name == "devstuff":
55
+ absolute = Path(os.path.abspath(candidate))
56
+ if absolute.is_file() and os.access(absolute, os.X_OK):
57
+ return (str(absolute),)
58
+ return (os.path.abspath(executable), "-m", "dev_setup")
59
+
60
+
61
+ def _gate_flags(spec: Spec) -> list[str]:
62
+ flags = []
63
+ if spec.allow_install:
64
+ flags.append("--allow-install")
65
+ if spec.allow_functions:
66
+ flags.append("--allow-functions")
67
+ return flags
68
+
69
+
70
+ def _connect_host(spec: Spec) -> tuple[str, tuple[str, ...]]:
71
+ if spec.host in _WILDCARDS:
72
+ shown = spec.host or "every address"
73
+ return "127.0.0.1", (
74
+ f"the server would be listening on every address ({shown}); the URL below uses 127.0.0.1, "
75
+ "which reaches it from this machine. From another machine, use this machine's own name "
76
+ "or address.",
77
+ )
78
+ return (f"[{spec.host}]" if ":" in spec.host else spec.host), ()
79
+
80
+
81
+ def _base_url(spec: Spec) -> tuple[str, tuple[str, ...]]:
82
+ if spec.port == 0:
83
+ raise ConfigError(
84
+ "--port 0 asks the OS for a port, so there is no port to write down yet. Pick a port "
85
+ "(the default is fine) and pass it to both the server and --print-config."
86
+ )
87
+ host, notes = _connect_host(spec)
88
+ return f"http://{host}:{spec.port}", notes
89
+
90
+
91
+ def _server_command(spec: Spec) -> str:
92
+ """The line that starts the server these snippets talk to, for the note on stderr."""
93
+ words = [*spec.launcher, "mcp", "--http"]
94
+ if spec.host:
95
+ words += ["--host", spec.host]
96
+ words += ["--port", str(spec.port)]
97
+ if spec.token_file:
98
+ words += ["--token-file", str(spec.token_file)]
99
+ words += _gate_flags(spec)
100
+ return shlex.join(words)
101
+
102
+
103
+ def _claude_code(spec: Spec) -> Rendered:
104
+ if not spec.http:
105
+ words = ["claude", "mcp", "add", NAME, "--", *spec.launcher, "mcp", *_gate_flags(spec)]
106
+ return Rendered(shlex.join(words) + "\n")
107
+ base, notes = _base_url(spec)
108
+ # `$(cat …)` is expanded by the shell that runs this command, so the token is read when it is
109
+ # pasted and never appears in what is printed. Quoting restarts inside `$( )`.
110
+ header = f'"Authorization: Bearer $(cat {shlex.quote(str(spec.token_file))})"'
111
+ text = f"claude mcp add --transport http {NAME} {base}/mcp --header {header}\n"
112
+ return Rendered(text, (*notes, f"this talks to a server you start yourself: {_server_command(spec)}"))
113
+
114
+
115
+ def _claude_desktop(spec: Spec) -> Rendered:
116
+ if spec.http:
117
+ raise ConfigError(
118
+ "Claude Desktop launches a command and talks to it over stdio, so there is no HTTP form to "
119
+ "print. Leave out --http."
120
+ )
121
+ command, *args = spec.launcher
122
+ entry = {"command": command, "args": [*args, "mcp", *_gate_flags(spec)]}
123
+ return Rendered(json.dumps({"mcpServers": {NAME: entry}}, indent=2) + "\n")
124
+
125
+
126
+ def _openapi(spec: Spec) -> Rendered:
127
+ if not spec.http:
128
+ raise ConfigError("the OpenAPI document is served by the HTTP server: add --http.")
129
+ base, notes = _base_url(spec)
130
+ text = (
131
+ f"Base URL: {base}\n"
132
+ f"OpenAPI URL: {base}/openapi.json\n"
133
+ f"Header: Authorization: Bearer <the contents of {spec.token_file}>\n"
134
+ )
135
+ return Rendered(text, (*notes, f"this talks to a server you start yourself: {_server_command(spec)}"))
136
+
137
+
138
+ _RENDERERS = {"claude-code": _claude_code, "claude-desktop": _claude_desktop, "openapi": _openapi}
139
+
140
+
141
+ def render(target: str, spec: Spec) -> Rendered:
142
+ try:
143
+ renderer = _RENDERERS[target]
144
+ except KeyError:
145
+ raise ConfigError(f"unknown target {target!r}; choose one of: {', '.join(TARGETS)}.") from None
146
+ return renderer(spec)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: devstuff
3
- Version: 2.17.0
3
+ Version: 2.18.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>
@@ -1212,6 +1212,24 @@ run**, so a client's configuration survives a restart. `devstuff` prints the fil
1212
1212
  | `--allow-origin ORIGIN` | Accept requests from this browser origin. Default none: a request carrying an `Origin` is refused, so a web page cannot drive the server |
1213
1213
  | `--token-file PATH` | Keep the token elsewhere |
1214
1214
 
1215
+ ### Configuring a client
1216
+
1217
+ `--print-config TARGET` prints a snippet for the other flags you give, then exits — it starts nothing, creates no
1218
+ token file and **never contains the token** (the HTTP command reads it from the file when you run it). Commands use
1219
+ the absolute path of the `devstuff` that is running, since a GUI application usually does not inherit your shell's
1220
+ `PATH`.
1221
+
1222
+ ```bash
1223
+ devstuff mcp --allow-install --print-config claude-code # claude mcp add devstuff -- /…/devstuff mcp --allow-install
1224
+ devstuff mcp --print-config claude-desktop # the mcpServers JSON for claude_desktop_config.json
1225
+ devstuff mcp --http --print-config claude-code # the --transport http … --header "…$(cat <token file>)" form
1226
+ devstuff mcp --http --port 9000 --print-config openapi # base URL, /openapi.json URL and the header to send
1227
+ ```
1228
+
1229
+ The snippet alone is on stdout (notes go to stderr), so `… --print-config claude-desktop > snippet.json` is clean.
1230
+ `claude-desktop` has no HTTP form, `openapi` needs `--http`, and `--port 0` cannot be printed. Claude Code's
1231
+ `claude mcp list` is the quickest check that a configuration works. Claude Desktop is untested here.
1232
+
1215
1233
  A non-loopback `--host` is allowed and **warned about**: there is no TLS, so the token crosses the network in the
1216
1234
  clear, and anyone holding it can use every enabled tool. To reach a loopback server from another machine, tunnel
1217
1235
  instead, with the *same* local port (the `Host` header must carry the bound port):
@@ -61,7 +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=vaP2KpccPkccLZhHS9q_0kxA-gjT4GqR-FANz_61WBE,8511
64
+ dev_setup/commands/mcp_cmd.py,sha256=UkScDupval0pHZhV1Mex6I8s9pnE7OS2Qf6zQhcQaxM,10261
65
65
  dev_setup/commands/outdated_cmd.py,sha256=afwYyq0M-tWVOk2qyXQqsdWSTK6yuFbVpbrOmMPKS_w,4757
66
66
  dev_setup/commands/profile_cmd.py,sha256=jo7al_nBwuWtzOLYKjcqEGmHp4eQrzM5s7ahv6iiGaw,18299
67
67
  dev_setup/commands/remove_cmd.py,sha256=Az0qMes4M5237c_ntQ1SemS38gTpLZy2GhSK_gUrw3s,4974
@@ -115,13 +115,14 @@ dev_setup/configure/starship/preview.py,sha256=ZaNhNA3AeHHtPnMqrJbB9XVVXDFbH1R36
115
115
  dev_setup/configure/starship/render.py,sha256=25O8w4IteVd_ELwmIWhcYAn042W6yZ--zbTMcJpzVJc,11277
116
116
  dev_setup/configure/starship/wizard.py,sha256=F3-xVQmZjYtiQAICyJXeSogjcASSsVbaP2b8YHAX9TM,28726
117
117
  dev_setup/mcp/__init__.py,sha256=a3DUEjK_mIpC4QsaPaArwKqaVvtujfzSu8WMpMh6G70,89
118
- dev_setup/mcp/core.py,sha256=MB9CbMW4q9g4Ym-kdpLSWLF92z3aV9WRF8ITVZ9zElA,19920
118
+ dev_setup/mcp/core.py,sha256=I0zNOWLByBAcpJjE1oz9Bh2VefZF9sZL88TfTENwFHo,20038
119
119
  dev_setup/mcp/http.py,sha256=w51uX-5LdgqS7M673JhGe_dHH9Oqdeg6qMkNrP6UjnU,17605
120
120
  dev_setup/mcp/openapi.py,sha256=pT8cB_RnupVDi0ZQjSx13o2LnfylDhsv4UWiL5bbIt0,5864
121
+ dev_setup/mcp/printconfig.py,sha256=3u_b4UpDwJ95u0_AfZuZuch1_-bOojdAg-08c5l6g28,5442
121
122
  dev_setup/mcp/process.py,sha256=IV203HLaCelWb89IhV73_8NWNAGglXRtXpwpHk39dD4,4752
122
123
  dev_setup/mcp/stdio.py,sha256=k-s2722_N2j92umkKo_Bq6KijfQGKFRudYVsh2H4xAk,6121
123
124
  dev_setup/mcp/token.py,sha256=Pr7MCY6FtY8g2oQWB291mMooiZY0eu659Qk3mh9auWE,3397
124
- devstuff-2.17.0.dist-info/METADATA,sha256=LOGUnnojEoYpQ1HYnUW5rKuYGVT7Hfz4IrYky9DP0Tk,97277
125
- devstuff-2.17.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
126
- devstuff-2.17.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
127
- devstuff-2.17.0.dist-info/RECORD,,
125
+ devstuff-2.18.0.dist-info/METADATA,sha256=SCgNioi3McSeKjnnliE2LTT9KbWhFCAQByKu3WuKP5M,98475
126
+ devstuff-2.18.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
127
+ devstuff-2.18.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
128
+ devstuff-2.18.0.dist-info/RECORD,,