devstuff 2.16.0__tar.gz → 2.18.0__tar.gz

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.
Files changed (257) hide show
  1. {devstuff-2.16.0 → devstuff-2.18.0}/CHANGELOG.md +12 -0
  2. {devstuff-2.16.0 → devstuff-2.18.0}/CLAUDE.md +24 -1
  3. {devstuff-2.16.0 → devstuff-2.18.0}/PKG-INFO +54 -3
  4. {devstuff-2.16.0 → devstuff-2.18.0}/README.md +53 -2
  5. {devstuff-2.16.0 → devstuff-2.18.0}/docs/ROADMAP.md +2 -2
  6. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/README.md +1 -1
  7. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/mcp/development-plan.md +5 -3
  8. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/mcp/specifications.md +67 -3
  9. {devstuff-2.16.0 → devstuff-2.18.0}/pyproject.toml +3 -1
  10. devstuff-2.18.0/src/dev_setup/commands/mcp_cmd.py +257 -0
  11. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/mcp/core.py +29 -2
  12. devstuff-2.18.0/src/dev_setup/mcp/http.py +422 -0
  13. devstuff-2.18.0/src/dev_setup/mcp/openapi.py +139 -0
  14. devstuff-2.18.0/src/dev_setup/mcp/printconfig.py +146 -0
  15. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/mcp/stdio.py +10 -3
  16. devstuff-2.18.0/src/dev_setup/mcp/token.py +85 -0
  17. devstuff-2.18.0/tests/integration/test_mcp_claude.py +167 -0
  18. devstuff-2.18.0/tests/integration/test_mcp_conformance.py +312 -0
  19. devstuff-2.18.0/tests/mcp_http_support.py +121 -0
  20. devstuff-2.18.0/tests/mcp_process_support.py +76 -0
  21. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_mcp_core.py +2 -1
  22. devstuff-2.18.0/tests/test_mcp_http.py +481 -0
  23. devstuff-2.18.0/tests/test_mcp_http_cmd.py +255 -0
  24. devstuff-2.18.0/tests/test_mcp_openapi.py +356 -0
  25. devstuff-2.18.0/tests/test_mcp_printconfig.py +299 -0
  26. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_mcp_stdio.py +0 -5
  27. devstuff-2.18.0/tests/test_mcp_token.py +118 -0
  28. devstuff-2.18.0/uv.lock +1479 -0
  29. devstuff-2.16.0/src/dev_setup/commands/mcp_cmd.py +0 -90
  30. devstuff-2.16.0/uv.lock +0 -577
  31. {devstuff-2.16.0 → devstuff-2.18.0}/.claude/skills/run-stuff/SKILL.md +0 -0
  32. {devstuff-2.16.0 → devstuff-2.18.0}/.claude/skills/run-stuff/smoke.sh +0 -0
  33. {devstuff-2.16.0 → devstuff-2.18.0}/.github/codex/review.md +0 -0
  34. {devstuff-2.16.0 → devstuff-2.18.0}/.github/workflows/agent.yml +0 -0
  35. {devstuff-2.16.0 → devstuff-2.18.0}/.github/workflows/bump.yml +0 -0
  36. {devstuff-2.16.0 → devstuff-2.18.0}/.github/workflows/ci.yml +0 -0
  37. {devstuff-2.16.0 → devstuff-2.18.0}/.github/workflows/publish.yml +0 -0
  38. {devstuff-2.16.0 → devstuff-2.18.0}/.github/workflows/test-installs.yml +0 -0
  39. {devstuff-2.16.0 → devstuff-2.18.0}/.gitignore +0 -0
  40. {devstuff-2.16.0 → devstuff-2.18.0}/AGENTS.md +0 -0
  41. {devstuff-2.16.0 → devstuff-2.18.0}/dev/Dockerfile +0 -0
  42. {devstuff-2.16.0 → devstuff-2.18.0}/dev/Dockerfile.ci +0 -0
  43. {devstuff-2.16.0 → devstuff-2.18.0}/dev/Makefile +0 -0
  44. {devstuff-2.16.0 → devstuff-2.18.0}/dev/docker-compose.yml +0 -0
  45. {devstuff-2.16.0 → devstuff-2.18.0}/devstuff +0 -0
  46. {devstuff-2.16.0 → devstuff-2.18.0}/docs/github-agent.md +0 -0
  47. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/agent/development-plan.md +0 -0
  48. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/agent/specifications.md +0 -0
  49. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/agent/stack-decisions.md +0 -0
  50. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/ansible-config/development-plan.md +0 -0
  51. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/ansible-config/specifications.md +0 -0
  52. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/ansible-config/stack-decisions.md +0 -0
  53. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/bat-config/development-plan.md +0 -0
  54. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/bat-config/specifications.md +0 -0
  55. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/bat-config/stack-decisions.md +0 -0
  56. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/commitizen-config/development-plan.md +0 -0
  57. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/commitizen-config/specifications.md +0 -0
  58. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/commitizen-config/stack-decisions.md +0 -0
  59. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/docker-config/development-plan.md +0 -0
  60. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/docker-config/specifications.md +0 -0
  61. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/docker-config/stack-decisions.md +0 -0
  62. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/lazygit-config/development-plan.md +0 -0
  63. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/lazygit-config/specifications.md +0 -0
  64. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/lazygit-config/stack-decisions.md +0 -0
  65. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/mcp/stack-decisions.md +0 -0
  66. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/outdated/development-plan.md +0 -0
  67. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/outdated/specifications.md +0 -0
  68. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/outdated/stack-decisions.md +0 -0
  69. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/plan-and-progress/specifications.md +0 -0
  70. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/precommit-config/development-plan.md +0 -0
  71. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/precommit-config/specifications.md +0 -0
  72. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/precommit-config/stack-decisions.md +0 -0
  73. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/profile/development-plan.md +0 -0
  74. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/profile/specifications.md +0 -0
  75. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/profile/stack-decisions.md +0 -0
  76. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/profile-apply/development-plan.md +0 -0
  77. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/profile-apply/specifications.md +0 -0
  78. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/profile-apply/stack-decisions.md +0 -0
  79. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/starship-config/development-plan.md +0 -0
  80. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/starship-config/specifications.md +0 -0
  81. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/starship-config/stack-decisions.md +0 -0
  82. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/uv-backbone/development-plan.md +0 -0
  83. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/uv-backbone/specifications.md +0 -0
  84. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/uv-backbone/stack-decisions.md +0 -0
  85. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/verbose-mode/development-plan.md +0 -0
  86. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/verbose-mode/specifications.md +0 -0
  87. {devstuff-2.16.0 → devstuff-2.18.0}/docs/specs/verbose-mode/stack-decisions.md +0 -0
  88. {devstuff-2.16.0 → devstuff-2.18.0}/install.sh +0 -0
  89. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/__init__.py +0 -0
  90. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/__main__.py +0 -0
  91. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/__init__.py +0 -0
  92. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/approval.py +0 -0
  93. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/bridges.py +0 -0
  94. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/catalog.py +0 -0
  95. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/completion.py +0 -0
  96. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/config.py +0 -0
  97. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/loop.py +0 -0
  98. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/ollama.py +0 -0
  99. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/preflight.py +0 -0
  100. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/primitives.py +0 -0
  101. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/registry.py +0 -0
  102. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/sandbox.py +0 -0
  103. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/session.py +0 -0
  104. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/transcript.py +0 -0
  105. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent/wizard.py +0 -0
  106. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent_tools.schema.json +0 -0
  107. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/agent_tools.yaml +0 -0
  108. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/apply_exec.py +0 -0
  109. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/apply_plan.py +0 -0
  110. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/base.py +0 -0
  111. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/bundles/ai-agents.yaml +0 -0
  112. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/bundles/ai-local.yaml +0 -0
  113. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/bundles/devops.yaml +0 -0
  114. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/bundles/essentials.yaml +0 -0
  115. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/bundles/languages.yaml +0 -0
  116. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/bundles/python.yaml +0 -0
  117. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/bundles.py +0 -0
  118. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/catalog.py +0 -0
  119. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/cli.py +0 -0
  120. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/__init__.py +0 -0
  121. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/_plan.py +0 -0
  122. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/add_cmd.py +0 -0
  123. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/agent_cmd.py +0 -0
  124. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/catalog_cmd.py +0 -0
  125. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/configure_cmd.py +0 -0
  126. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/delete_cmd.py +0 -0
  127. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/docs_cmd.py +0 -0
  128. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/doctor_cmd.py +0 -0
  129. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/functions_cmd.py +0 -0
  130. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/help_cmd.py +0 -0
  131. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/install_cmd.py +0 -0
  132. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/links_cmd.py +0 -0
  133. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/list_cmd.py +0 -0
  134. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/outdated_cmd.py +0 -0
  135. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/profile_cmd.py +0 -0
  136. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/remove_cmd.py +0 -0
  137. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/run_cmd.py +0 -0
  138. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/skills_cmd.py +0 -0
  139. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/commands/update_cmd.py +0 -0
  140. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/__init__.py +0 -0
  141. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/ansible/__init__.py +0 -0
  142. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/ansible/detect.py +0 -0
  143. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/ansible/model.py +0 -0
  144. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/ansible/render.py +0 -0
  145. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/ansible/validate.py +0 -0
  146. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/ansible/wizard.py +0 -0
  147. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/bat/__init__.py +0 -0
  148. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/bat/detect.py +0 -0
  149. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/bat/model.py +0 -0
  150. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/bat/preview.py +0 -0
  151. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/bat/render.py +0 -0
  152. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/bat/wizard.py +0 -0
  153. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/commitizen/__init__.py +0 -0
  154. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/commitizen/detect.py +0 -0
  155. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/commitizen/model.py +0 -0
  156. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/commitizen/render.py +0 -0
  157. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/commitizen/validate.py +0 -0
  158. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/commitizen/wizard.py +0 -0
  159. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/docker/__init__.py +0 -0
  160. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/docker/detect.py +0 -0
  161. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/docker/model.py +0 -0
  162. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/docker/render.py +0 -0
  163. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/docker/validate.py +0 -0
  164. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/docker/wizard.py +0 -0
  165. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/lazygit/__init__.py +0 -0
  166. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/lazygit/detect.py +0 -0
  167. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/lazygit/model.py +0 -0
  168. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/lazygit/render.py +0 -0
  169. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/lazygit/validate.py +0 -0
  170. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/lazygit/wizard.py +0 -0
  171. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/precommit/__init__.py +0 -0
  172. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/precommit/detect.py +0 -0
  173. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/precommit/model.py +0 -0
  174. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/precommit/render.py +0 -0
  175. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/precommit/validate.py +0 -0
  176. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/precommit/wizard.py +0 -0
  177. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/reptyr/__init__.py +0 -0
  178. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/reptyr/wizard.py +0 -0
  179. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/starship/__init__.py +0 -0
  180. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/starship/fonts.py +0 -0
  181. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/starship/icons.py +0 -0
  182. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/starship/model.py +0 -0
  183. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/starship/preview.py +0 -0
  184. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/starship/render.py +0 -0
  185. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/configure/starship/wizard.py +0 -0
  186. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/doctor.py +0 -0
  187. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/function_runner.py +0 -0
  188. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/functions.schema.json +0 -0
  189. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/functions.yaml +0 -0
  190. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/functions_catalog.py +0 -0
  191. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/functions_registry.py +0 -0
  192. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/generic.py +0 -0
  193. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/links.schema.json +0 -0
  194. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/links.yaml +0 -0
  195. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/links_catalog.py +0 -0
  196. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/links_registry.py +0 -0
  197. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/mcp/__init__.py +0 -0
  198. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/mcp/process.py +0 -0
  199. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/profile.py +0 -0
  200. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/registry.py +0 -0
  201. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/snapshot.py +0 -0
  202. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/tools.yaml +0 -0
  203. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/ui.py +0 -0
  204. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/updates.py +0 -0
  205. {devstuff-2.16.0 → devstuff-2.18.0}/src/dev_setup/verbose.py +0 -0
  206. {devstuff-2.16.0 → devstuff-2.18.0}/tests/__init__.py +0 -0
  207. {devstuff-2.16.0 → devstuff-2.18.0}/tests/integration/__init__.py +0 -0
  208. {devstuff-2.16.0 → devstuff-2.18.0}/tests/integration/conftest.py +0 -0
  209. {devstuff-2.16.0 → devstuff-2.18.0}/tests/integration/test_agent_smoke.py +0 -0
  210. {devstuff-2.16.0 → devstuff-2.18.0}/tests/integration/test_agent_tui.py +0 -0
  211. {devstuff-2.16.0 → devstuff-2.18.0}/tests/integration/test_commitizen_config.py +0 -0
  212. {devstuff-2.16.0 → devstuff-2.18.0}/tests/integration/test_profile_apply.py +0 -0
  213. {devstuff-2.16.0 → devstuff-2.18.0}/tests/integration/test_tools.py +0 -0
  214. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_agent.py +0 -0
  215. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_agent_bridges.py +0 -0
  216. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_agent_completion.py +0 -0
  217. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_agent_loop.py +0 -0
  218. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_agent_sandbox.py +0 -0
  219. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_agent_tools.py +0 -0
  220. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_agent_wizard.py +0 -0
  221. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_apply_exec.py +0 -0
  222. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_apply_plan.py +0 -0
  223. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_apply_run.py +0 -0
  224. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_bundles.py +0 -0
  225. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_catalog.py +0 -0
  226. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_configure_ansible.py +0 -0
  227. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_configure_bat.py +0 -0
  228. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_configure_commitizen.py +0 -0
  229. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_configure_docker.py +0 -0
  230. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_configure_lazygit.py +0 -0
  231. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_configure_precommit.py +0 -0
  232. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_configure_reptyr.py +0 -0
  233. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_configure_starship.py +0 -0
  234. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_doctor.py +0 -0
  235. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_functions.py +0 -0
  236. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_generic.py +0 -0
  237. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_installed_version.py +0 -0
  238. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_lifecycle_cmds.py +0 -0
  239. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_links.py +0 -0
  240. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_mcp_classify.py +0 -0
  241. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_mcp_process.py +0 -0
  242. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_outdated_cmd.py +0 -0
  243. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_pin_support.py +0 -0
  244. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_plan_and_select.py +0 -0
  245. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_profile.py +0 -0
  246. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_profile_apply_cmd.py +0 -0
  247. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_profile_diff.py +0 -0
  248. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_profile_diff_cmd.py +0 -0
  249. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_profile_snapshot_cmd.py +0 -0
  250. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_registry.py +0 -0
  251. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_snapshot.py +0 -0
  252. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_ui.py +0 -0
  253. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_update_checker_parity.py +0 -0
  254. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_update_notes.py +0 -0
  255. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_updates.py +0 -0
  256. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_uv_probes.py +0 -0
  257. {devstuff-2.16.0 → devstuff-2.18.0}/tests/test_verbose.py +0 -0
@@ -1,3 +1,15 @@
1
+ ## v2.18.0 (2026-10-12)
2
+
3
+ ### Features
4
+
5
+ - **mcp**: M-4 — --print-config, and the SDK and Claude Code conformance suites
6
+
7
+ ## v2.17.0 (2026-10-12)
8
+
9
+ ### Features
10
+
11
+ - **mcp**: M-3 — devstuff mcp --http: MCP, REST and an OpenAPI document
12
+
1
13
  ## v2.16.0 (2026-10-12)
2
14
 
3
15
  ### Features
@@ -694,13 +694,36 @@ the `mutating` label or the key — and a test fails when a bridge is added to `
694
694
  from `tools/list` *and* refused by `tools/call` — a list-only check passes when dispatch is wide open.
695
695
  - **A request's `id` is echoed with its type, and a notification is the *absence* of the key**, never a falsy
696
696
  value: Claude Code sends an integer `0` for `initialize`. Unknown methods are `-32601`, not `{}` — the real
697
- client opens with `server/discover` and falls back to `initialize` only when told it is unknown.
697
+ client opens with `server/discover` and falls back to `initialize`. Measured: both the SDK and Claude Code
698
+ fall back on `{}` too, so no real-client test can catch that regression; the raw-frame tests are what pin it.
698
699
  - **The protocol channel is moved at the descriptor level** (`stdio.isolate_stdio`): private non-inheritable
699
700
  `dup`s, then fd 1 → stderr and fd 0 → `/dev/null`. Anything that prints, however it does it, lands on stderr.
700
701
  The test leaks through five routes and has a control showing the same leaks corrupt an un-isolated stream.
701
702
  - **The server detaches from its terminal first** (`process.detach`): `/dev/null` stdin does *not* stop `sudo`
702
703
  prompting on `/dev/tty`. `setsid`, else fork + supervisor (`EPERM` from a shell), then verify and fail closed.
703
704
  The supervisor forwards `SIGHUP` as `SIGTERM` or a closed terminal orphans the server.
705
+ - **HTTP: three checks stand in front of every route, in this order — `Origin`/`Host` (403), then the bearer
706
+ token (401, `hmac.compare_digest`), then the route.** `Host` is checked before the token so a 403 never reveals
707
+ whether a token would have been accepted; it must carry the *bound port* and name `localhost`, an IP literal
708
+ or an `--allow-host` name (DNS rebinding needs a name the attacker controls). There are no CORS headers, ever.
709
+ The token file is `0600`, persistent (a fresh token per run broke every configured client), refused if
710
+ group/other-readable *even when rotating*, and never printed — the path is.
711
+ - **A gated-off tool is indistinguishable from a made-up one over HTTP too**: 404 for POST, 405 for any other
712
+ method on `/tools/<anything>`. `OpenAPI` is generated from the same `Toolbox` as `tools/list`, and
713
+ `tests/test_mcp_openapi.py` checks it three ways — the validator (necessary: it accepts an operation with no
714
+ `responses` and a `security` entry naming no scheme), set equality across all framings, and a client that reads
715
+ *only* the document and checks statuses and bodies against each operation's own schema.
716
+ - **Shutdown must not wait for idle keep-alive connections** (`McpHTTPServer.server_close` wakes them) — only for
717
+ running calls. `ThreadingMixIn.server_close` joins every request thread, so one forgotten connection made
718
+ SIGTERM hang forever until a test caught it.
719
+ - **Real-client tests prove "connects", not "correct on the wire".** `tests/integration/test_mcp_claude.py` (real
720
+ `claude mcp list`, skipped without `claude`) and `test_mcp_conformance.py` (the SDK, skipped without `mcp`) cannot
721
+ fail on a wrong or missing answer to `server/discover` — measured, both clients fall back anyway — so the raw-frame
722
+ tests are what pin `-32601` and id echo. The suite uses `mcp.Client`, which sends `server/discover`; the lower-level
723
+ `ClientSession` does not, and a suite built on it never reaches the fallback.
724
+ - **`--print-config` is pure and never contains the token** (`mcp/printconfig.py`). The launcher is the console
725
+ script's absolute path or `<interpreter> -m dev_setup`, never a bare name; HTTP snippets read the token with
726
+ `$(cat <file>)` at paste time. A test pastes each printed command through `bash -c` into a fresh `HOME`.
704
727
  - **Reads are never blocked by an install; they are kept honest.** `generic._once` memos live as long as the
705
728
  process, so `Dispatcher` clears them when a burst of reads starts and after every mutation (in `finally`), and
706
729
  re-runs a read a mutation straddled. The advisory note is a *separate* content item so JSON stays parseable.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: devstuff
3
- Version: 2.16.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>
@@ -1181,8 +1181,59 @@ Workspace tools (`read_file`, `run_command`, …) never exist here — the clien
1181
1181
 
1182
1182
  The server has **no terminal**: an installer that needs a `sudo` password fails at once with a message telling the
1183
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/).
1184
+ Logs (`-v`, `-vv`) go to stderr. Design and measurements: [`docs/specs/mcp/`](docs/specs/mcp/).
1185
+
1186
+ ### Over HTTP, and as an OpenAPI tool server
1187
+
1188
+ ```bash
1189
+ devstuff mcp --http # 127.0.0.1:8765, this machine only
1190
+ devstuff mcp --http --allow-install # …and install_tool
1191
+ claude mcp add --transport http devstuff http://127.0.0.1:8765/mcp \
1192
+ --header "Authorization: Bearer $(cat ~/.local/state/devstuff/mcp-token)"
1193
+ ```
1194
+
1195
+ One server, three ways in — all of them show **the same tools**, and all need `Authorization: Bearer <token>`:
1196
+
1197
+ | Path | What it is |
1198
+ |---|---|
1199
+ | `POST /mcp` | MCP (Streamable HTTP, JSON responses; no sessions, no stream) — Claude Code, Claude Desktop, any MCP client |
1200
+ | `GET /tools` | The tools as an OpenAI function-calling array |
1201
+ | `POST /tools/<name>` | Run one tool: a JSON object body in, `{"is_error": …, "text": …}` out |
1202
+ | `GET /openapi.json` | An OpenAPI 3.1 document for the two rows above — point Open WebUI or any OpenAPI tool client at it |
1203
+
1204
+ The token is created on first use in `~/.local/state/devstuff/mcp-token` (mode `0600`) and **reused on every
1205
+ run**, so a client's configuration survives a restart. `devstuff` prints the file's path, never its contents.
1206
+ `--rotate-token` replaces it; a token file that group or others can read is refused.
1207
+
1208
+ | Flag | Meaning |
1209
+ |---|---|
1210
+ | `--host ADDR` / `--port N` | Default `127.0.0.1:8765`. A busy port is an error — it never picks another, which would break every configured client. `--port 0` asks the OS |
1211
+ | `--allow-host NAME` | Also accept this name in the `Host` header, e.g. `host.docker.internal` (Open WebUI in Docker reaches the host that way). `localhost` and IP addresses are always accepted |
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
+ | `--token-file PATH` | Keep the token elsewhere |
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
+
1233
+ A non-loopback `--host` is allowed and **warned about**: there is no TLS, so the token crosses the network in the
1234
+ clear, and anyone holding it can use every enabled tool. To reach a loopback server from another machine, tunnel
1235
+ instead, with the *same* local port (the `Host` header must carry the bound port):
1236
+ `ssh -L 8765:127.0.0.1:8765 you@host`.
1186
1237
 
1187
1238
  ---
1188
1239
 
@@ -1154,8 +1154,59 @@ Workspace tools (`read_file`, `run_command`, …) never exist here — the clien
1154
1154
 
1155
1155
  The server has **no terminal**: an installer that needs a `sudo` password fails at once with a message telling the
1156
1156
  client to run `devstuff install <key>` in a terminal, rather than waiting for a password nobody can type.
1157
- Logs (`-v`, `-vv`) go to stderr. HTTP and OpenAPI front ends are still to come; see
1158
- [`docs/specs/mcp/`](docs/specs/mcp/).
1157
+ Logs (`-v`, `-vv`) go to stderr. Design and measurements: [`docs/specs/mcp/`](docs/specs/mcp/).
1158
+
1159
+ ### Over HTTP, and as an OpenAPI tool server
1160
+
1161
+ ```bash
1162
+ devstuff mcp --http # 127.0.0.1:8765, this machine only
1163
+ devstuff mcp --http --allow-install # …and install_tool
1164
+ claude mcp add --transport http devstuff http://127.0.0.1:8765/mcp \
1165
+ --header "Authorization: Bearer $(cat ~/.local/state/devstuff/mcp-token)"
1166
+ ```
1167
+
1168
+ One server, three ways in — all of them show **the same tools**, and all need `Authorization: Bearer <token>`:
1169
+
1170
+ | Path | What it is |
1171
+ |---|---|
1172
+ | `POST /mcp` | MCP (Streamable HTTP, JSON responses; no sessions, no stream) — Claude Code, Claude Desktop, any MCP client |
1173
+ | `GET /tools` | The tools as an OpenAI function-calling array |
1174
+ | `POST /tools/<name>` | Run one tool: a JSON object body in, `{"is_error": …, "text": …}` out |
1175
+ | `GET /openapi.json` | An OpenAPI 3.1 document for the two rows above — point Open WebUI or any OpenAPI tool client at it |
1176
+
1177
+ The token is created on first use in `~/.local/state/devstuff/mcp-token` (mode `0600`) and **reused on every
1178
+ run**, so a client's configuration survives a restart. `devstuff` prints the file's path, never its contents.
1179
+ `--rotate-token` replaces it; a token file that group or others can read is refused.
1180
+
1181
+ | Flag | Meaning |
1182
+ |---|---|
1183
+ | `--host ADDR` / `--port N` | Default `127.0.0.1:8765`. A busy port is an error — it never picks another, which would break every configured client. `--port 0` asks the OS |
1184
+ | `--allow-host NAME` | Also accept this name in the `Host` header, e.g. `host.docker.internal` (Open WebUI in Docker reaches the host that way). `localhost` and IP addresses are always accepted |
1185
+ | `--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 |
1186
+ | `--token-file PATH` | Keep the token elsewhere |
1187
+
1188
+ ### Configuring a client
1189
+
1190
+ `--print-config TARGET` prints a snippet for the other flags you give, then exits — it starts nothing, creates no
1191
+ token file and **never contains the token** (the HTTP command reads it from the file when you run it). Commands use
1192
+ the absolute path of the `devstuff` that is running, since a GUI application usually does not inherit your shell's
1193
+ `PATH`.
1194
+
1195
+ ```bash
1196
+ devstuff mcp --allow-install --print-config claude-code # claude mcp add devstuff -- /…/devstuff mcp --allow-install
1197
+ devstuff mcp --print-config claude-desktop # the mcpServers JSON for claude_desktop_config.json
1198
+ devstuff mcp --http --print-config claude-code # the --transport http … --header "…$(cat <token file>)" form
1199
+ devstuff mcp --http --port 9000 --print-config openapi # base URL, /openapi.json URL and the header to send
1200
+ ```
1201
+
1202
+ The snippet alone is on stdout (notes go to stderr), so `… --print-config claude-desktop > snippet.json` is clean.
1203
+ `claude-desktop` has no HTTP form, `openapi` needs `--http`, and `--port 0` cannot be printed. Claude Code's
1204
+ `claude mcp list` is the quickest check that a configuration works. Claude Desktop is untested here.
1205
+
1206
+ A non-loopback `--host` is allowed and **warned about**: there is no TLS, so the token crosses the network in the
1207
+ clear, and anyone holding it can use every enabled tool. To reach a loopback server from another machine, tunnel
1208
+ instead, with the *same* local port (the `Host` header must carry the bound port):
1209
+ `ssh -L 8765:127.0.0.1:8765 you@host`.
1159
1210
 
1160
1211
  ---
1161
1212
 
@@ -22,7 +22,7 @@ M5 is independent polish that can be slotted in anywhere.
22
22
  | M3 | `devstuff profile apply` + bundled bundles | Medium–high | M2 | `profile-apply/` |
23
23
  | M4 | Agent tools for `doctor` / `outdated` | Low | M1 | `agent/` (amend) |
24
24
  | M5 | Shell completion | Low | — | `completion/` |
25
- | M6 | `devstuff mcp`: MCP (stdio + HTTP) and OpenAPI tool server | Medium | M1; builds `outdated` / `profile_diff` agent tools (overlaps M4) | `mcp/` (approved) |
25
+ | M6 | `devstuff mcp`: MCP (stdio + HTTP) and OpenAPI tool server | Medium | M1; builds `outdated` / `profile_diff` agent tools (overlaps M4) | `mcp/` (built; live check pending) |
26
26
  | — | git / tmux configurator | Medium | — | `git-config/` (unscheduled) |
27
27
  | — | `devstuff sandbox <tool>` | Medium | — | `sandbox/` (unscheduled) |
28
28
 
@@ -165,7 +165,7 @@ Serve devstuff's catalog-aware tools to any MCP or OpenAPI client, so an AI clie
165
165
  or inspect a tool instead of guessing at `apt` and `npm` itself.
166
166
 
167
167
  **Spec:** [`specs/mcp/`](specs/mcp/) — **approved**, 2026-10-11 (findings measured; two goals: Claude compatibility, OpenAPI coverage).
168
- **Progress:** M-1 (bridges, classification) and M-2 (the stdio server, `devstuff mcp`) built 2026-10-12; M-3 (HTTP, REST, OpenAPI) and M-4 (conformance, `--print-config`, docs) remain.
168
+ **Progress:** M-1 (bridges, classification), M-2 (the stdio server) and M-3 (`--http`: MCP at `POST /mcp`, REST, `/openapi.json`, the token file) and M-4 (`--print-config`, the SDK and `claude mcp list` conformance suites, docs) built 2026-10-12. Remaining: one live `tools/call` through Claude Code, run by hand with consent.
169
169
 
170
170
  - Three framings, one dispatcher: MCP over stdio, MCP over HTTP, and OpenAPI/REST (`/openapi.json`, `/tools`).
171
171
  - Read-only tools by default (`list_tools`, `search_catalog`, `tool_info`, `outdated`, `profile_diff`);
@@ -51,4 +51,4 @@ They are most useful when they capture:
51
51
  | [`profile/`](profile/) — `devstuff profile snapshot` / `diff`, a portable description of a machine's tools | Complete (v1: snapshot, diff; apply is its own spec) |
52
52
  | [`plan-and-progress/`](plan-and-progress/) — plan preview, live progress view and the guided `add` wizard for `install`/`remove`/`update`/`add` | Implemented (documented after the fact; no `stack-decisions.md`) |
53
53
  | [`profile-apply/`](profile-apply/) — `devstuff profile apply`, make a machine match a profile | Complete (v1: apply, six bundles; container test written, first run pending) |
54
- | [`mcp/`](mcp/) — `devstuff mcp`, devstuff's tools as an MCP (stdio + HTTP) and OpenAPI tool server | Approved 2026-10-11 (spec only; findings measured) |
54
+ | [`mcp/`](mcp/) — `devstuff mcp`, devstuff's tools as an MCP (stdio + HTTP) and OpenAPI tool server | Built 2026-10-12 (M-1…M-4: stdio, HTTP, OpenAPI, `--print-config`, conformance suites; one live Claude Code `tools/call` pending) |
@@ -13,8 +13,8 @@ targeting `master` from a branch cut **after** this spec merges (never stacked o
13
13
  |---|---|---|
14
14
  | **M-1** ✅ 2026-10-12 | Measure what remains of F-6/F-11: does sudo's line survive `_run`'s capture (FR-13)? Then `agent/bridges.py` + `agent_tools.yaml`: `outdated` and `profile_diff`; FR-4 test; the FR-1a classification table and its forcing test | — |
15
15
  | **M-2** ✅ 2026-10-12 | `src/dev_setup/mcp/`: `core.py` (classification, dispatch, gating, probe lifecycle FR-8a, JSON-RPC handling — pure), `stdio.py` (FR-11/11a/12/19, incl. the detach + supervisor), `commands/mcp_cmd.py` (stdio only) | M-1 |
16
- | **M-3** | `mcp/http.py`: `POST /mcp`, token/Host/Origin (FR-20, 24–28); then REST + OpenAPI (FR-21–23) | M-2 |
17
- | **M-4** | **G-1:** conformance tests (real SDK client; real `claude mcp list`); `--print-config` (FR-31). **G-2:** OpenAPI validity, both-direction coverage and the document-driven client (FR-22a–c). One live `tools/call` through Claude Code, with consent. README, CLAUDE.md section, specs index, roadmap | M-3 |
16
+ | **M-3** ✅ 2026-10-12 | `mcp/http.py`: `POST /mcp`, token/Host/Origin (FR-20, 24–28); then REST + OpenAPI (FR-21–23); `mcp/token.py`, `mcp/openapi.py`, the `--http` flags | M-2 |
17
+ | **M-4** ✅ 2026-10-12 (live `tools/call` pending consent) | **G-1:** conformance tests (real SDK client; real `claude mcp list`); `--print-config` (FR-31). **G-2:** OpenAPI validity, both-direction coverage and the document-driven client (FR-22a–c). One live `tools/call` through Claude Code, with consent. README, CLAUDE.md section, specs index, roadmap | M-3 |
18
18
 
19
19
  ## Layout
20
20
 
@@ -65,7 +65,9 @@ status the server never sends, send one it never documents.
65
65
  **SDK conformance (`tests/integration/test_mcp_conformance.py`, skipped when `mcp` is not importable):** the
66
66
  real SDK client — `mcp` in the **dev** dependency group — against `devstuff mcp` over stdio and over HTTP:
67
67
  `initialize`, `tools/list`, `tools/call` of a read-only tool, and a gated tool absent without the flag and
68
- present with it. This is the test that would have caught F-2.
68
+ present with it. It uses the high-level `mcp.Client`, the one that opens with `server/discover`, so the
69
+ fallback is exercised on every connect; the lower-level `ClientSession` never sends it, so it cannot (F-16).
70
+ Neither client *fails* on a wrong answer to `server/discover`, so those wire details are held by raw frames.
69
71
 
70
72
  **Review-driven tests (spec §5a), each with the mutation that must break it:**
71
73
  - *Classification (FR-1a):* the exact F-10a user file under all four flag combinations; a forcing test over
@@ -6,7 +6,10 @@ rest (G-1, G-2 below). Findings F-1…F-11 were measured on 2026-10-11 (F-6 clos
6
6
  the 2026-10-11 PR review are folded in (§5a). **M-1 built 2026-10-12** (the `outdated` / `profile_diff`
7
7
  bridges, FR-1a's classification in `mcp/core.py`, the FR-4 test, F-12/F-13). **M-2 built 2026-10-12**: the
8
8
  stdio server (`devstuff mcp`, FR-1–19, FR-29/30 for stdio) with the detach and supervisor measured (F-14); HTTP,
9
- REST and OpenAPI (M-3) and `--print-config` (M-4) are not.
9
+ REST and OpenAPI (M-3) and `--print-config` (M-4) are not. **M-3 built 2026-10-12**: `--http`, the token file,
10
+ `POST /mcp`, REST and `/openapi.json` (F-15). **M-4 built 2026-10-12**: `--print-config`, the SDK and
11
+ `claude mcp list` conformance suites (F-16). Not yet run: the one live `tools/call` through Claude Code (§6, G-1.3),
12
+ which makes a model turn and waits for the user's consent.
10
13
  **Authors:** Sawyer + Claude
11
14
  **Roadmap:** new (overlaps [M4](../../ROADMAP.md): the `outdated` agent tool is built once and serves both)
12
15
  **Builds on:** [`agent/`](../agent/) (the tool registry, `AgentTool.to_schema()` / `bind()` and the
@@ -195,8 +198,10 @@ When a requirement below conflicts with either, the goal wins. Each has a measur
195
198
  `capabilities: {"tools": {}}` and nothing else.
196
199
  - **FR-16** **Method not found is a JSON-RPC `-32601` error, not an empty result.** The current official
197
200
  client's first request is `server/discover` under protocol `2026-07-28`, and it falls back to
198
- `initialize` only when told the method is unknown (F-2). `resources/*`, `prompts/*` and any other
199
- method get `-32601` too.
201
+ `initialize` (F-2). `resources/*`, `prompts/*` and any other method get `-32601` too. This is protocol
202
+ correctness, *not* something either real client enforces: both also fall back on `{}`, and the SDK
203
+ waits about five seconds and falls back when the request is never answered (F-16). The raw-frame
204
+ tests are therefore the only ones that can fail on it.
200
205
  - **FR-16a** **A request's `id` is echoed back unchanged, type included.** Claude Code sends a *string* id
201
206
  (`"server-discover-probe-1"`) and an integer **`0`** for `initialize` (F-8). A request is a notification
202
207
  only if the key `id` is *absent* — never because its value is falsy — or the first real reply is
@@ -446,6 +451,65 @@ When a requirement below conflicts with either, the goal wins. Each has a measur
446
451
  `tools/list` → `tools/call` over stdio: 5 tools read-only, 13 with both flags; `install_tool` refused as an
447
452
  unknown tool without its flag, bad arguments a tool error. Claude Code 2.1.296 `claude mcp list` reported
448
453
  `✔ Connected` for the stdio server.
454
+ - **F-15 — M-3, measured against the built server (2026-10-12).**
455
+ *The OpenAPI validator is necessary, not sufficient (FR-22a).* `openapi-spec-validator` 0.9.0 rejected a
456
+ document with no `info`, a duplicate `operationId`, a schema `type: bogus`, a dangling `$ref`, a status key
457
+ `99`, and a response with no `description`. It **accepted** a top-level `security` entry naming a scheme
458
+ that does not exist — so the document test checks that itself — and, as OpenAPI 3.1 allows, an operation
459
+ with **no `responses` at all**, which is why the validator's control breaks things it demonstrably rejects.
460
+ Validity says nothing about truth, which is what FR-22c's client is for.
461
+ *A hang found by a test:* a client that leaves a keep-alive connection open made `server_close()` wait on
462
+ that connection's thread for ever, so SIGTERM never ended the server. FR-30 says wait for running *calls*, not
463
+ idle sockets: connections are now tracked as idle (inside the request-line read) or busy; shutdown wakes the
464
+ idle ones, and a busy one is told `Connection: close` after its response.
465
+ *Decisions the spec did not make:* (1) a request carrying `Transfer-Encoding` (a chunked body) is `400`, not
466
+ guessed at; (2) a rejected request's unread body is read and discarded (up to 16 MiB, else the connection is
467
+ closed) *before* the answer is sent, so its bytes are never parsed as the next request and a client that sent a large
468
+ refused body gets the `413` instead of a connection reset (**measured**: without this, a client sending 8 MB
469
+ got `BrokenPipe` and never saw the status; with it, bodies up to the 16 MiB bound are answered, above which
470
+ the client may still see a reset); (3) a path under `/tools/` is `405`
471
+ for every method but `POST` **whether or not the tool exists**, so a gated-off tool and a made-up one are
472
+ indistinguishable; (4) `HEAD`, `OPTIONS`, `PUT`, `PATCH` are `405`, so a CORS preflight is simply a method nobody
473
+ supports; (5) `404` is documented on every tool operation but cannot be reached from the document's own
474
+ paths — every path in it is in the toolbox — so it exists for a client holding an older document after a
475
+ restart with different flags, and the truthfulness test names that one exception rather than hiding it; (6)
476
+ `--allow-host` takes a bare name and `--allow-origin` an exact origin (`http://localhost:3000`, no trailing
477
+ slash), both validated as usage errors; (7) a token file with loose permissions is refused **even with
478
+ `--rotate-token`**, because quietly fixing the mode would hide that the old secret was exposed, and a
479
+ hand-written token under 16 characters is refused; (8) `Host` must carry the bound port, so an SSH tunnel has
480
+ to use the same local port (`-L 8765:127.0.0.1:8765`) and a Docker port mapping to a different host port needs
481
+ that port to be the bound one; (9) `serve_forever` polls every 0.1 s instead of 0.5 s, which is how long a
482
+ shutdown would otherwise take to be noticed.
483
+ - **F-16 — M-4: what the real clients do and do not enforce (2026-10-12; `mcp` 2.3.0, Claude Code 2.1.296).**
484
+ *Neither client fails on a wrong answer to `server/discover`.* With `{}` as the answer both fall back to
485
+ `initialize` and connect; with **no answer at all** Claude Code still connects at once and the SDK waits about
486
+ five seconds per connection and then falls back. So `-32601` (FR-16) is protocol correctness that only raw-frame
487
+ tests can hold — a mutation answering `{}` survived every real-client test and was killed by the raw-frame ones.
488
+ *Two SDK clients, one honest test.* The lower-level `ClientSession` never sends `server/discover`; the
489
+ high-level `mcp.Client` does, then `initialize`. A first draft of the conformance suite used `ClientSession` and
490
+ therefore never exercised the fallback at all, which is why the suite uses `Client` and keeps one `ClientSession`
491
+ case for the initialize-first path.
492
+ *`claude mcp list` needs no terminal:* run with stdin `/dev/null` and piped output under an isolated `HOME`, it
493
+ prints one `name: target - <health>` line per server — `✔ Connected`, or `✘ Failed to connect — …` carrying the
494
+ reason (`Server rejected the configured Authorization header (HTTP 401)…` for a wrong token, `ENOENT … posix_spawn`
495
+ for a missing command). Both failures are tested as controls, so `✔ Connected` is shown to be able to be absent.
496
+ *The printed snippets run as printed:* the `--print-config claude-code` stdio command, with and without the gate
497
+ flags, and the HTTP command with its `$(cat <token file>)` header, were each pasted through `bash -c` into a fresh
498
+ `HOME` and then listed `✔ Connected`.
499
+ *Decisions the spec did not make (FR-31):* (1) the launcher is the console script's own absolute path when
500
+ `argv[0]` is a real, executable `devstuff` (a symlink keeps its path: the venv behind it is rebuilt, the link is
501
+ not), otherwise `<this interpreter> -m dev_setup` — never a bare `devstuff` and never a `which` that could name a
502
+ different install; (2) `claude-desktop` with `--http` and `openapi` without `--http` are usage errors, since
503
+ Desktop launches a command over stdio and the OpenAPI document exists only on the HTTP server; (3) `--port 0`
504
+ cannot be printed (nobody knows the port yet); (4) a wildcard `--host` (`0.0.0.0`, `::`) prints `127.0.0.1` and
505
+ says so on stderr; an IPv6 literal is bracketed; (5) the gate flags appear in stdio snippets only — for HTTP they
506
+ are the *server's* launch flags, which a client cannot set, so they are named in a stderr note giving the line
507
+ that starts that server; (6) the snippet is the only thing on stdout and notes go to stderr, so
508
+ `--print-config … > file` is clean; (7) nothing is started, no token file is created or read, and the path is
509
+ printed absolute — a missing file gets a stderr note that the server creates it on first start; (8)
510
+ `--print-config` with `--list-tools` is a usage error, since each prints and exits.
511
+ *Not measured:* Claude Desktop (not installed here, so its snippet is checked for shape only), and the
512
+ expectation that a GUI app does not inherit the shell's `PATH` (it is why the path is absolute, not a finding).
449
513
  - **F-12 — the agent catalog had no list-typed parameter (found building M-1).** `outdated`'s `packages`
450
514
  (FR-9) is a list of keys, and `agent/catalog.py`'s `PARAM_TYPES` was `string`, `integer`, `number`,
451
515
  `boolean`. Decision: add `array` — always an array of strings, advertised as
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "devstuff"
3
- version = "2.16.0"
3
+ version = "2.18.0"
4
4
  description = "Development environment setup CLI for Linux"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -46,6 +46,8 @@ packages = ["src/dev_setup"]
46
46
  [dependency-groups]
47
47
  dev = [
48
48
  "commitizen>=3.0",
49
+ "mcp>=2.3.0",
50
+ "openapi-spec-validator>=0.9.0",
49
51
  "pytest>=8.0",
50
52
  "ruff>=0.8",
51
53
  ]
@@ -0,0 +1,257 @@
1
+ from __future__ import annotations
2
+
3
+ import errno
4
+ import ipaddress
5
+ import os
6
+ import re
7
+ import sys
8
+ from pathlib import Path
9
+
10
+ import click
11
+
12
+ from dev_setup.catalog import CatalogError
13
+ from dev_setup.mcp import http, printconfig, process, stdio, token
14
+ from dev_setup.mcp.core import Dispatcher, Toolbox
15
+
16
+ DEFAULT_HOST = "127.0.0.1"
17
+ DEFAULT_PORT = 8765 # fixed on purpose: a configured client's URL must survive a restart (SD-8)
18
+
19
+ _HOSTNAME = re.compile(r"[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?")
20
+ _ORIGIN = re.compile(r"https?://[^/\s]+")
21
+
22
+
23
+ def _warn(message: str) -> None:
24
+ click.echo(f"devstuff mcp: {message}", err=True)
25
+
26
+
27
+ def _fail(message: str) -> None:
28
+ click.echo(f"error: {message}", err=True)
29
+ sys.exit(1)
30
+
31
+
32
+ def _toolbox(allow_install: bool, allow_functions: bool) -> Toolbox:
33
+ from dev_setup.agent import registry as agent_registry
34
+
35
+ return Toolbox.from_agent(
36
+ agent_registry.build(), allow_install=allow_install, allow_functions=allow_functions, warn=_warn
37
+ )
38
+
39
+
40
+ def _enabled(allow_install: bool, allow_functions: bool) -> str:
41
+ gated = [
42
+ label
43
+ for label, on in (("install_tool", allow_install), ("functions", allow_functions))
44
+ if on
45
+ ]
46
+ return f"+ {', '.join(gated)}" if gated else "read-only; install_tool and functions are off"
47
+
48
+
49
+ def _is_loopback(host: str) -> bool:
50
+ if host == "localhost":
51
+ return True
52
+ try:
53
+ return ipaddress.ip_address(host).is_loopback
54
+ except ValueError:
55
+ return False
56
+
57
+
58
+ @click.command("mcp")
59
+ @click.option(
60
+ "--http", "use_http", is_flag=True,
61
+ help="Serve over HTTP instead of stdio: MCP at POST /mcp, REST at /tools, the OpenAPI document at "
62
+ "/openapi.json. Every request needs the bearer token.",
63
+ )
64
+ @click.option(
65
+ "--host", default=None, metavar="ADDR",
66
+ help=f"[--http] Address to listen on (default {DEFAULT_HOST}, this machine only). A non-loopback "
67
+ "address is allowed, and warned about: there is no TLS.",
68
+ )
69
+ @click.option(
70
+ "--port", type=click.IntRange(0, 65535), default=None, metavar="N",
71
+ help=f"[--http] Port (default {DEFAULT_PORT}). 0 asks the OS. A busy port is an error, never a fallback.",
72
+ )
73
+ @click.option(
74
+ "--token-file", type=click.Path(dir_okay=False, path_type=Path), default=None, metavar="PATH",
75
+ help="[--http] Where the bearer token lives (default ~/.local/state/devstuff/mcp-token). Created "
76
+ "on first use, mode 0600, reused on every run. Its path is printed; its contents never are.",
77
+ )
78
+ @click.option("--rotate-token", is_flag=True, help="[--http] Replace the token with a new one.")
79
+ @click.option(
80
+ "--allow-origin", "allow_origins", multiple=True, metavar="ORIGIN",
81
+ help="[--http] Accept requests carrying this Origin (repeatable). Default: none, so a browser "
82
+ "is refused.",
83
+ )
84
+ @click.option(
85
+ "--allow-host", "allow_hosts", multiple=True, metavar="NAME",
86
+ help="[--http] Accept this name in the Host header (repeatable), e.g. host.docker.internal. "
87
+ "`localhost` and IP addresses are always accepted.",
88
+ )
89
+ @click.option(
90
+ "--allow-install", is_flag=True,
91
+ help="Expose install_tool, which installs a catalog tool as you. Off by default: absent and refused.",
92
+ )
93
+ @click.option(
94
+ "--allow-functions", is_flag=True,
95
+ help="Expose every `type: script` function (fn_<key>). Off by default: absent and refused.",
96
+ )
97
+ @click.option(
98
+ "--list-tools", "list_tools", is_flag=True,
99
+ help="Print the tools these flags would expose, and which gate each sits behind. Starts nothing.",
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
+ )
107
+ def mcp_cmd(
108
+ use_http: bool,
109
+ host: str | None,
110
+ port: int | None,
111
+ token_file: Path | None,
112
+ rotate_token: bool,
113
+ allow_origins: tuple[str, ...],
114
+ allow_hosts: tuple[str, ...],
115
+ allow_install: bool,
116
+ allow_functions: bool,
117
+ list_tools: bool,
118
+ print_config: str | None,
119
+ ) -> None:
120
+ """Serve devstuff's tools to an MCP client (stdio) or over HTTP, MCP and OpenAPI.
121
+
122
+ By default it speaks MCP over stdio: it reads JSON-RPC from stdin and answers on stdout, and is
123
+ meant to be started by a client (Claude Code, Claude Desktop), not by hand. With --http it
124
+ listens on a port instead.
125
+
126
+ Only read-only tools are exposed unless a flag says otherwise, and a tool that is off does not
127
+ merely hide: a call naming it is refused.
128
+
129
+ The server has no terminal. An installer that needs a password fails at once rather than
130
+ waiting for one nobody can type; run `devstuff install <key>` in a terminal for those.
131
+ """
132
+ http_only = {
133
+ "--host": host is not None, "--port": port is not None, "--token-file": token_file is not None,
134
+ "--rotate-token": rotate_token, "--allow-origin": bool(allow_origins),
135
+ "--allow-host": bool(allow_hosts),
136
+ }
137
+ if not use_http and any(http_only.values()):
138
+ given = ", ".join(flag for flag, on in http_only.items() if on)
139
+ raise click.UsageError(f"{given} only apply with --http.")
140
+ for name in allow_hosts:
141
+ if not _HOSTNAME.fullmatch(name):
142
+ raise click.UsageError(
143
+ f"--allow-host takes a bare host name (no port, scheme or path), not {name!r}."
144
+ )
145
+ for origin in allow_origins:
146
+ if not _ORIGIN.fullmatch(origin):
147
+ raise click.UsageError(
148
+ f"--allow-origin takes an origin like http://localhost:3000, not {origin!r}."
149
+ )
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
159
+ if list_tools:
160
+ _print_tools(_load(allow_install, allow_functions))
161
+ return
162
+
163
+ # Detach first, before the fd move and before anything that could run an installer (FR-11a).
164
+ # Under a shell this forks and the original process becomes a supervisor that never returns.
165
+ process.detach()
166
+ try:
167
+ process.require_no_terminal(gated=allow_install or allow_functions, warn=_warn)
168
+ except process.TerminalReachable as exc:
169
+ _fail(str(exc))
170
+
171
+ box = _load(allow_install, allow_functions)
172
+ if not use_http:
173
+ what = _enabled(allow_install, allow_functions)
174
+ click.echo(f"devstuff mcp: serving {len(box.names())} tools on stdio ({what})", err=True)
175
+ sys.exit(stdio.run(Dispatcher(box)))
176
+ _serve_http(
177
+ box, Dispatcher(box), host or DEFAULT_HOST, DEFAULT_PORT if port is None else port,
178
+ token_file, rotate_token, allow_origins, allow_hosts, _enabled(allow_install, allow_functions),
179
+ )
180
+
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
+
203
+ def _serve_http(
204
+ box: Toolbox, dispatcher: Dispatcher, host: str, port: int, token_file: Path | None,
205
+ rotate: bool, allow_origins: tuple[str, ...], allow_hosts: tuple[str, ...], enabled: str,
206
+ ) -> None:
207
+ try:
208
+ secret, path = token.load(token_file, rotate=rotate)
209
+ except token.TokenError as exc:
210
+ _fail(str(exc))
211
+ try:
212
+ server = http.make_server(
213
+ dispatcher, host=host, port=port, token=secret,
214
+ allow_hosts=allow_hosts, allow_origins=allow_origins,
215
+ )
216
+ except OSError as exc:
217
+ hint = ""
218
+ if exc.errno == errno.EADDRINUSE:
219
+ hint = (
220
+ " Another process is using it. devstuff never picks a different port: a client "
221
+ "configured for this one would fail with no explanation. Stop that process, or pass --port."
222
+ )
223
+ _fail(f"cannot listen on {host}:{port}: {exc.strerror or exc}.{hint}")
224
+
225
+ # With the port held and before any request can arrive: nothing a tool prints may reach the
226
+ # terminal or read from it (FR-11).
227
+ stdio.isolate_stdio(channel=False)
228
+ bound = server.bound_port
229
+ shown = f"[{host}]" if ":" in host else host
230
+ click.echo(
231
+ f"devstuff mcp: serving {len(box.names())} tools on http://{shown}:{bound} ({enabled}); "
232
+ f"bearer token in {path}",
233
+ err=True,
234
+ )
235
+ if not _is_loopback(host):
236
+ _warn(
237
+ f"listening on {host}, not just this machine. There is no TLS: the token crosses the network in "
238
+ f"the clear, and anyone who holds it can use every enabled tool ({enabled}). To reach a "
239
+ "loopback server from another machine, an SSH tunnel is safer."
240
+ )
241
+ sys.exit(http.serve(server))
242
+
243
+
244
+ def _load(allow_install: bool, allow_functions: bool) -> Toolbox:
245
+ try:
246
+ return _toolbox(allow_install, allow_functions)
247
+ except CatalogError as exc:
248
+ _fail(str(exc))
249
+ raise # unreachable: _fail exits
250
+
251
+
252
+ def _print_tools(box: Toolbox) -> None:
253
+ width = max((len(n) for n in box.names()), default=0)
254
+ for name in box.names():
255
+ tool = box.get(name)
256
+ first = (tool.description.splitlines() or [""])[0]
257
+ click.echo(f"{name:<{width}} [{box.gate(name).value}] {first}")