devstuff 2.16.0__tar.gz → 2.17.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 (251) hide show
  1. {devstuff-2.16.0 → devstuff-2.17.0}/CHANGELOG.md +6 -0
  2. {devstuff-2.16.0 → devstuff-2.17.0}/CLAUDE.md +14 -0
  3. {devstuff-2.16.0 → devstuff-2.17.0}/PKG-INFO +36 -3
  4. {devstuff-2.16.0 → devstuff-2.17.0}/README.md +35 -2
  5. {devstuff-2.16.0 → devstuff-2.17.0}/docs/ROADMAP.md +1 -1
  6. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/mcp/development-plan.md +1 -1
  7. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/mcp/specifications.md +31 -1
  8. {devstuff-2.16.0 → devstuff-2.17.0}/pyproject.toml +2 -1
  9. devstuff-2.17.0/src/dev_setup/commands/mcp_cmd.py +220 -0
  10. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/mcp/core.py +26 -0
  11. devstuff-2.17.0/src/dev_setup/mcp/http.py +422 -0
  12. devstuff-2.17.0/src/dev_setup/mcp/openapi.py +139 -0
  13. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/mcp/stdio.py +10 -3
  14. devstuff-2.17.0/src/dev_setup/mcp/token.py +85 -0
  15. devstuff-2.17.0/tests/mcp_http_support.py +121 -0
  16. devstuff-2.17.0/tests/test_mcp_http.py +481 -0
  17. devstuff-2.17.0/tests/test_mcp_http_cmd.py +314 -0
  18. devstuff-2.17.0/tests/test_mcp_openapi.py +356 -0
  19. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_mcp_stdio.py +0 -5
  20. devstuff-2.17.0/tests/test_mcp_token.py +118 -0
  21. {devstuff-2.16.0 → devstuff-2.17.0}/uv.lock +508 -2
  22. devstuff-2.16.0/src/dev_setup/commands/mcp_cmd.py +0 -90
  23. {devstuff-2.16.0 → devstuff-2.17.0}/.claude/skills/run-stuff/SKILL.md +0 -0
  24. {devstuff-2.16.0 → devstuff-2.17.0}/.claude/skills/run-stuff/smoke.sh +0 -0
  25. {devstuff-2.16.0 → devstuff-2.17.0}/.github/codex/review.md +0 -0
  26. {devstuff-2.16.0 → devstuff-2.17.0}/.github/workflows/agent.yml +0 -0
  27. {devstuff-2.16.0 → devstuff-2.17.0}/.github/workflows/bump.yml +0 -0
  28. {devstuff-2.16.0 → devstuff-2.17.0}/.github/workflows/ci.yml +0 -0
  29. {devstuff-2.16.0 → devstuff-2.17.0}/.github/workflows/publish.yml +0 -0
  30. {devstuff-2.16.0 → devstuff-2.17.0}/.github/workflows/test-installs.yml +0 -0
  31. {devstuff-2.16.0 → devstuff-2.17.0}/.gitignore +0 -0
  32. {devstuff-2.16.0 → devstuff-2.17.0}/AGENTS.md +0 -0
  33. {devstuff-2.16.0 → devstuff-2.17.0}/dev/Dockerfile +0 -0
  34. {devstuff-2.16.0 → devstuff-2.17.0}/dev/Dockerfile.ci +0 -0
  35. {devstuff-2.16.0 → devstuff-2.17.0}/dev/Makefile +0 -0
  36. {devstuff-2.16.0 → devstuff-2.17.0}/dev/docker-compose.yml +0 -0
  37. {devstuff-2.16.0 → devstuff-2.17.0}/devstuff +0 -0
  38. {devstuff-2.16.0 → devstuff-2.17.0}/docs/github-agent.md +0 -0
  39. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/README.md +0 -0
  40. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/agent/development-plan.md +0 -0
  41. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/agent/specifications.md +0 -0
  42. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/agent/stack-decisions.md +0 -0
  43. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/ansible-config/development-plan.md +0 -0
  44. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/ansible-config/specifications.md +0 -0
  45. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/ansible-config/stack-decisions.md +0 -0
  46. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/bat-config/development-plan.md +0 -0
  47. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/bat-config/specifications.md +0 -0
  48. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/bat-config/stack-decisions.md +0 -0
  49. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/commitizen-config/development-plan.md +0 -0
  50. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/commitizen-config/specifications.md +0 -0
  51. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/commitizen-config/stack-decisions.md +0 -0
  52. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/docker-config/development-plan.md +0 -0
  53. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/docker-config/specifications.md +0 -0
  54. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/docker-config/stack-decisions.md +0 -0
  55. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/lazygit-config/development-plan.md +0 -0
  56. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/lazygit-config/specifications.md +0 -0
  57. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/lazygit-config/stack-decisions.md +0 -0
  58. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/mcp/stack-decisions.md +0 -0
  59. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/outdated/development-plan.md +0 -0
  60. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/outdated/specifications.md +0 -0
  61. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/outdated/stack-decisions.md +0 -0
  62. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/plan-and-progress/specifications.md +0 -0
  63. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/precommit-config/development-plan.md +0 -0
  64. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/precommit-config/specifications.md +0 -0
  65. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/precommit-config/stack-decisions.md +0 -0
  66. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/profile/development-plan.md +0 -0
  67. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/profile/specifications.md +0 -0
  68. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/profile/stack-decisions.md +0 -0
  69. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/profile-apply/development-plan.md +0 -0
  70. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/profile-apply/specifications.md +0 -0
  71. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/profile-apply/stack-decisions.md +0 -0
  72. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/starship-config/development-plan.md +0 -0
  73. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/starship-config/specifications.md +0 -0
  74. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/starship-config/stack-decisions.md +0 -0
  75. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/uv-backbone/development-plan.md +0 -0
  76. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/uv-backbone/specifications.md +0 -0
  77. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/uv-backbone/stack-decisions.md +0 -0
  78. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/verbose-mode/development-plan.md +0 -0
  79. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/verbose-mode/specifications.md +0 -0
  80. {devstuff-2.16.0 → devstuff-2.17.0}/docs/specs/verbose-mode/stack-decisions.md +0 -0
  81. {devstuff-2.16.0 → devstuff-2.17.0}/install.sh +0 -0
  82. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/__init__.py +0 -0
  83. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/__main__.py +0 -0
  84. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/__init__.py +0 -0
  85. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/approval.py +0 -0
  86. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/bridges.py +0 -0
  87. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/catalog.py +0 -0
  88. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/completion.py +0 -0
  89. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/config.py +0 -0
  90. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/loop.py +0 -0
  91. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/ollama.py +0 -0
  92. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/preflight.py +0 -0
  93. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/primitives.py +0 -0
  94. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/registry.py +0 -0
  95. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/sandbox.py +0 -0
  96. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/session.py +0 -0
  97. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/transcript.py +0 -0
  98. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent/wizard.py +0 -0
  99. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent_tools.schema.json +0 -0
  100. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/agent_tools.yaml +0 -0
  101. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/apply_exec.py +0 -0
  102. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/apply_plan.py +0 -0
  103. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/base.py +0 -0
  104. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/bundles/ai-agents.yaml +0 -0
  105. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/bundles/ai-local.yaml +0 -0
  106. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/bundles/devops.yaml +0 -0
  107. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/bundles/essentials.yaml +0 -0
  108. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/bundles/languages.yaml +0 -0
  109. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/bundles/python.yaml +0 -0
  110. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/bundles.py +0 -0
  111. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/catalog.py +0 -0
  112. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/cli.py +0 -0
  113. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/__init__.py +0 -0
  114. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/_plan.py +0 -0
  115. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/add_cmd.py +0 -0
  116. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/agent_cmd.py +0 -0
  117. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/catalog_cmd.py +0 -0
  118. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/configure_cmd.py +0 -0
  119. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/delete_cmd.py +0 -0
  120. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/docs_cmd.py +0 -0
  121. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/doctor_cmd.py +0 -0
  122. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/functions_cmd.py +0 -0
  123. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/help_cmd.py +0 -0
  124. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/install_cmd.py +0 -0
  125. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/links_cmd.py +0 -0
  126. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/list_cmd.py +0 -0
  127. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/outdated_cmd.py +0 -0
  128. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/profile_cmd.py +0 -0
  129. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/remove_cmd.py +0 -0
  130. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/run_cmd.py +0 -0
  131. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/skills_cmd.py +0 -0
  132. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/commands/update_cmd.py +0 -0
  133. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/__init__.py +0 -0
  134. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/ansible/__init__.py +0 -0
  135. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/ansible/detect.py +0 -0
  136. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/ansible/model.py +0 -0
  137. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/ansible/render.py +0 -0
  138. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/ansible/validate.py +0 -0
  139. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/ansible/wizard.py +0 -0
  140. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/bat/__init__.py +0 -0
  141. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/bat/detect.py +0 -0
  142. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/bat/model.py +0 -0
  143. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/bat/preview.py +0 -0
  144. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/bat/render.py +0 -0
  145. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/bat/wizard.py +0 -0
  146. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/commitizen/__init__.py +0 -0
  147. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/commitizen/detect.py +0 -0
  148. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/commitizen/model.py +0 -0
  149. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/commitizen/render.py +0 -0
  150. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/commitizen/validate.py +0 -0
  151. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/commitizen/wizard.py +0 -0
  152. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/docker/__init__.py +0 -0
  153. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/docker/detect.py +0 -0
  154. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/docker/model.py +0 -0
  155. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/docker/render.py +0 -0
  156. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/docker/validate.py +0 -0
  157. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/docker/wizard.py +0 -0
  158. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/lazygit/__init__.py +0 -0
  159. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/lazygit/detect.py +0 -0
  160. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/lazygit/model.py +0 -0
  161. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/lazygit/render.py +0 -0
  162. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/lazygit/validate.py +0 -0
  163. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/lazygit/wizard.py +0 -0
  164. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/precommit/__init__.py +0 -0
  165. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/precommit/detect.py +0 -0
  166. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/precommit/model.py +0 -0
  167. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/precommit/render.py +0 -0
  168. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/precommit/validate.py +0 -0
  169. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/precommit/wizard.py +0 -0
  170. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/reptyr/__init__.py +0 -0
  171. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/reptyr/wizard.py +0 -0
  172. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/starship/__init__.py +0 -0
  173. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/starship/fonts.py +0 -0
  174. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/starship/icons.py +0 -0
  175. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/starship/model.py +0 -0
  176. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/starship/preview.py +0 -0
  177. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/starship/render.py +0 -0
  178. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/configure/starship/wizard.py +0 -0
  179. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/doctor.py +0 -0
  180. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/function_runner.py +0 -0
  181. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/functions.schema.json +0 -0
  182. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/functions.yaml +0 -0
  183. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/functions_catalog.py +0 -0
  184. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/functions_registry.py +0 -0
  185. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/generic.py +0 -0
  186. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/links.schema.json +0 -0
  187. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/links.yaml +0 -0
  188. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/links_catalog.py +0 -0
  189. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/links_registry.py +0 -0
  190. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/mcp/__init__.py +0 -0
  191. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/mcp/process.py +0 -0
  192. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/profile.py +0 -0
  193. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/registry.py +0 -0
  194. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/snapshot.py +0 -0
  195. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/tools.yaml +0 -0
  196. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/ui.py +0 -0
  197. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/updates.py +0 -0
  198. {devstuff-2.16.0 → devstuff-2.17.0}/src/dev_setup/verbose.py +0 -0
  199. {devstuff-2.16.0 → devstuff-2.17.0}/tests/__init__.py +0 -0
  200. {devstuff-2.16.0 → devstuff-2.17.0}/tests/integration/__init__.py +0 -0
  201. {devstuff-2.16.0 → devstuff-2.17.0}/tests/integration/conftest.py +0 -0
  202. {devstuff-2.16.0 → devstuff-2.17.0}/tests/integration/test_agent_smoke.py +0 -0
  203. {devstuff-2.16.0 → devstuff-2.17.0}/tests/integration/test_agent_tui.py +0 -0
  204. {devstuff-2.16.0 → devstuff-2.17.0}/tests/integration/test_commitizen_config.py +0 -0
  205. {devstuff-2.16.0 → devstuff-2.17.0}/tests/integration/test_profile_apply.py +0 -0
  206. {devstuff-2.16.0 → devstuff-2.17.0}/tests/integration/test_tools.py +0 -0
  207. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_agent.py +0 -0
  208. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_agent_bridges.py +0 -0
  209. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_agent_completion.py +0 -0
  210. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_agent_loop.py +0 -0
  211. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_agent_sandbox.py +0 -0
  212. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_agent_tools.py +0 -0
  213. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_agent_wizard.py +0 -0
  214. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_apply_exec.py +0 -0
  215. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_apply_plan.py +0 -0
  216. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_apply_run.py +0 -0
  217. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_bundles.py +0 -0
  218. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_catalog.py +0 -0
  219. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_configure_ansible.py +0 -0
  220. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_configure_bat.py +0 -0
  221. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_configure_commitizen.py +0 -0
  222. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_configure_docker.py +0 -0
  223. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_configure_lazygit.py +0 -0
  224. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_configure_precommit.py +0 -0
  225. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_configure_reptyr.py +0 -0
  226. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_configure_starship.py +0 -0
  227. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_doctor.py +0 -0
  228. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_functions.py +0 -0
  229. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_generic.py +0 -0
  230. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_installed_version.py +0 -0
  231. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_lifecycle_cmds.py +0 -0
  232. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_links.py +0 -0
  233. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_mcp_classify.py +0 -0
  234. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_mcp_core.py +0 -0
  235. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_mcp_process.py +0 -0
  236. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_outdated_cmd.py +0 -0
  237. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_pin_support.py +0 -0
  238. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_plan_and_select.py +0 -0
  239. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_profile.py +0 -0
  240. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_profile_apply_cmd.py +0 -0
  241. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_profile_diff.py +0 -0
  242. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_profile_diff_cmd.py +0 -0
  243. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_profile_snapshot_cmd.py +0 -0
  244. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_registry.py +0 -0
  245. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_snapshot.py +0 -0
  246. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_ui.py +0 -0
  247. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_update_checker_parity.py +0 -0
  248. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_update_notes.py +0 -0
  249. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_updates.py +0 -0
  250. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_uv_probes.py +0 -0
  251. {devstuff-2.16.0 → devstuff-2.17.0}/tests/test_verbose.py +0 -0
@@ -1,3 +1,9 @@
1
+ ## v2.17.0 (2026-10-12)
2
+
3
+ ### Features
4
+
5
+ - **mcp**: M-3 — devstuff mcp --http: MCP, REST and an OpenAPI document
6
+
1
7
  ## v2.16.0 (2026-10-12)
2
8
 
3
9
  ### Features
@@ -701,6 +701,20 @@ the `mutating` label or the key — and a test fails when a bridge is added to `
701
701
  - **The server detaches from its terminal first** (`process.detach`): `/dev/null` stdin does *not* stop `sudo`
702
702
  prompting on `/dev/tty`. `setsid`, else fork + supervisor (`EPERM` from a shell), then verify and fail closed.
703
703
  The supervisor forwards `SIGHUP` as `SIGTERM` or a closed terminal orphans the server.
704
+ - **HTTP: three checks stand in front of every route, in this order — `Origin`/`Host` (403), then the bearer
705
+ token (401, `hmac.compare_digest`), then the route.** `Host` is checked before the token so a 403 never reveals
706
+ whether a token would have been accepted; it must carry the *bound port* and name `localhost`, an IP literal
707
+ or an `--allow-host` name (DNS rebinding needs a name the attacker controls). There are no CORS headers, ever.
708
+ The token file is `0600`, persistent (a fresh token per run broke every configured client), refused if
709
+ group/other-readable *even when rotating*, and never printed — the path is.
710
+ - **A gated-off tool is indistinguishable from a made-up one over HTTP too**: 404 for POST, 405 for any other
711
+ method on `/tools/<anything>`. `OpenAPI` is generated from the same `Toolbox` as `tools/list`, and
712
+ `tests/test_mcp_openapi.py` checks it three ways — the validator (necessary: it accepts an operation with no
713
+ `responses` and a `security` entry naming no scheme), set equality across all framings, and a client that reads
714
+ *only* the document and checks statuses and bodies against each operation's own schema.
715
+ - **Shutdown must not wait for idle keep-alive connections** (`McpHTTPServer.server_close` wakes them) — only for
716
+ running calls. `ThreadingMixIn.server_close` joins every request thread, so one forgotten connection made
717
+ SIGTERM hang forever until a test caught it.
704
718
  - **Reads are never blocked by an install; they are kept honest.** `generic._once` memos live as long as the
705
719
  process, so `Dispatcher` clears them when a burst of reads starts and after every mutation (in `finally`), and
706
720
  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.17.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,41 @@ 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
+ A non-loopback `--host` is allowed and **warned about**: there is no TLS, so the token crosses the network in the
1216
+ clear, and anyone holding it can use every enabled tool. To reach a loopback server from another machine, tunnel
1217
+ instead, with the *same* local port (the `Host` header must carry the bound port):
1218
+ `ssh -L 8765:127.0.0.1:8765 you@host`.
1186
1219
 
1187
1220
  ---
1188
1221
 
@@ -1154,8 +1154,41 @@ 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
+ A non-loopback `--host` is allowed and **warned about**: there is no TLS, so the token crosses the network in the
1189
+ clear, and anyone holding it can use every enabled tool. To reach a loopback server from another machine, tunnel
1190
+ instead, with the *same* local port (the `Host` header must carry the bound port):
1191
+ `ssh -L 8765:127.0.0.1:8765 you@host`.
1159
1192
 
1160
1193
  ---
1161
1194
 
@@ -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) built 2026-10-12; M-4 (conformance suite, `--print-config`, docs) remains.
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`);
@@ -13,7 +13,7 @@ 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 |
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
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 |
18
18
 
19
19
  ## Layout
@@ -6,7 +6,8 @@ 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); `--print-config` and the formal conformance suite (M-4) are not.
10
11
  **Authors:** Sawyer + Claude
11
12
  **Roadmap:** new (overlaps [M4](../../ROADMAP.md): the `outdated` agent tool is built once and serves both)
12
13
  **Builds on:** [`agent/`](../agent/) (the tool registry, `AgentTool.to_schema()` / `bind()` and the
@@ -446,6 +447,35 @@ When a requirement below conflicts with either, the goal wins. Each has a measur
446
447
  `tools/list` → `tools/call` over stdio: 5 tools read-only, 13 with both flags; `install_tool` refused as an
447
448
  unknown tool without its flag, bad arguments a tool error. Claude Code 2.1.296 `claude mcp list` reported
448
449
  `✔ Connected` for the stdio server.
450
+ - **F-15 — M-3, measured against the built server (2026-10-12).**
451
+ *The OpenAPI validator is necessary, not sufficient (FR-22a).* `openapi-spec-validator` 0.9.0 rejected a
452
+ document with no `info`, a duplicate `operationId`, a schema `type: bogus`, a dangling `$ref`, a status key
453
+ `99`, and a response with no `description`. It **accepted** a top-level `security` entry naming a scheme
454
+ that does not exist — so the document test checks that itself — and, as OpenAPI 3.1 allows, an operation
455
+ with **no `responses` at all**, which is why the validator's control breaks things it demonstrably rejects.
456
+ Validity says nothing about truth, which is what FR-22c's client is for.
457
+ *A hang found by a test:* a client that leaves a keep-alive connection open made `server_close()` wait on
458
+ that connection's thread for ever, so SIGTERM never ended the server. FR-30 says wait for running *calls*, not
459
+ idle sockets: connections are now tracked as idle (inside the request-line read) or busy; shutdown wakes the
460
+ idle ones, and a busy one is told `Connection: close` after its response.
461
+ *Decisions the spec did not make:* (1) a request carrying `Transfer-Encoding` (a chunked body) is `400`, not
462
+ guessed at; (2) a rejected request's unread body is read and discarded (up to 16 MiB, else the connection is
463
+ closed) *before* the answer is sent, so its bytes are never parsed as the next request and a client that sent a large
464
+ refused body gets the `413` instead of a connection reset (**measured**: without this, a client sending 8 MB
465
+ got `BrokenPipe` and never saw the status; with it, bodies up to the 16 MiB bound are answered, above which
466
+ the client may still see a reset); (3) a path under `/tools/` is `405`
467
+ for every method but `POST` **whether or not the tool exists**, so a gated-off tool and a made-up one are
468
+ indistinguishable; (4) `HEAD`, `OPTIONS`, `PUT`, `PATCH` are `405`, so a CORS preflight is simply a method nobody
469
+ supports; (5) `404` is documented on every tool operation but cannot be reached from the document's own
470
+ paths — every path in it is in the toolbox — so it exists for a client holding an older document after a
471
+ restart with different flags, and the truthfulness test names that one exception rather than hiding it; (6)
472
+ `--allow-host` takes a bare name and `--allow-origin` an exact origin (`http://localhost:3000`, no trailing
473
+ slash), both validated as usage errors; (7) a token file with loose permissions is refused **even with
474
+ `--rotate-token`**, because quietly fixing the mode would hide that the old secret was exposed, and a
475
+ hand-written token under 16 characters is refused; (8) `Host` must carry the bound port, so an SSH tunnel has
476
+ to use the same local port (`-L 8765:127.0.0.1:8765`) and a Docker port mapping to a different host port needs
477
+ 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
478
+ shutdown would otherwise take to be noticed.
449
479
  - **F-12 — the agent catalog had no list-typed parameter (found building M-1).** `outdated`'s `packages`
450
480
  (FR-9) is a list of keys, and `agent/catalog.py`'s `PARAM_TYPES` was `string`, `integer`, `number`,
451
481
  `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.17.0"
4
4
  description = "Development environment setup CLI for Linux"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -46,6 +46,7 @@ packages = ["src/dev_setup"]
46
46
  [dependency-groups]
47
47
  dev = [
48
48
  "commitizen>=3.0",
49
+ "openapi-spec-validator>=0.9.0",
49
50
  "pytest>=8.0",
50
51
  "ruff>=0.8",
51
52
  ]
@@ -0,0 +1,220 @@
1
+ from __future__ import annotations
2
+
3
+ import errno
4
+ import ipaddress
5
+ import re
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ import click
10
+
11
+ from dev_setup.catalog import CatalogError
12
+ from dev_setup.mcp import http, process, stdio, token
13
+ from dev_setup.mcp.core import Dispatcher, Toolbox
14
+
15
+ DEFAULT_HOST = "127.0.0.1"
16
+ DEFAULT_PORT = 8765 # fixed on purpose: a configured client's URL must survive a restart (SD-8)
17
+
18
+ _HOSTNAME = re.compile(r"[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?")
19
+ _ORIGIN = re.compile(r"https?://[^/\s]+")
20
+
21
+
22
+ def _warn(message: str) -> None:
23
+ click.echo(f"devstuff mcp: {message}", err=True)
24
+
25
+
26
+ def _fail(message: str) -> None:
27
+ click.echo(f"error: {message}", err=True)
28
+ sys.exit(1)
29
+
30
+
31
+ def _toolbox(allow_install: bool, allow_functions: bool) -> Toolbox:
32
+ from dev_setup.agent import registry as agent_registry
33
+
34
+ return Toolbox.from_agent(
35
+ agent_registry.build(), allow_install=allow_install, allow_functions=allow_functions, warn=_warn
36
+ )
37
+
38
+
39
+ def _enabled(allow_install: bool, allow_functions: bool) -> str:
40
+ gated = [
41
+ label
42
+ for label, on in (("install_tool", allow_install), ("functions", allow_functions))
43
+ if on
44
+ ]
45
+ return f"+ {', '.join(gated)}" if gated else "read-only; install_tool and functions are off"
46
+
47
+
48
+ def _is_loopback(host: str) -> bool:
49
+ if host == "localhost":
50
+ return True
51
+ try:
52
+ return ipaddress.ip_address(host).is_loopback
53
+ except ValueError:
54
+ return False
55
+
56
+
57
+ @click.command("mcp")
58
+ @click.option(
59
+ "--http", "use_http", is_flag=True,
60
+ help="Serve over HTTP instead of stdio: MCP at POST /mcp, REST at /tools, the OpenAPI document at "
61
+ "/openapi.json. Every request needs the bearer token.",
62
+ )
63
+ @click.option(
64
+ "--host", default=None, metavar="ADDR",
65
+ help=f"[--http] Address to listen on (default {DEFAULT_HOST}, this machine only). A non-loopback "
66
+ "address is allowed, and warned about: there is no TLS.",
67
+ )
68
+ @click.option(
69
+ "--port", type=click.IntRange(0, 65535), default=None, metavar="N",
70
+ help=f"[--http] Port (default {DEFAULT_PORT}). 0 asks the OS. A busy port is an error, never a fallback.",
71
+ )
72
+ @click.option(
73
+ "--token-file", type=click.Path(dir_okay=False, path_type=Path), default=None, metavar="PATH",
74
+ help="[--http] Where the bearer token lives (default ~/.local/state/devstuff/mcp-token). Created "
75
+ "on first use, mode 0600, reused on every run. Its path is printed; its contents never are.",
76
+ )
77
+ @click.option("--rotate-token", is_flag=True, help="[--http] Replace the token with a new one.")
78
+ @click.option(
79
+ "--allow-origin", "allow_origins", multiple=True, metavar="ORIGIN",
80
+ help="[--http] Accept requests carrying this Origin (repeatable). Default: none, so a browser "
81
+ "is refused.",
82
+ )
83
+ @click.option(
84
+ "--allow-host", "allow_hosts", multiple=True, metavar="NAME",
85
+ help="[--http] Accept this name in the Host header (repeatable), e.g. host.docker.internal. "
86
+ "`localhost` and IP addresses are always accepted.",
87
+ )
88
+ @click.option(
89
+ "--allow-install", is_flag=True,
90
+ help="Expose install_tool, which installs a catalog tool as you. Off by default: absent and refused.",
91
+ )
92
+ @click.option(
93
+ "--allow-functions", is_flag=True,
94
+ help="Expose every `type: script` function (fn_<key>). Off by default: absent and refused.",
95
+ )
96
+ @click.option(
97
+ "--list-tools", "list_tools", is_flag=True,
98
+ help="Print the tools these flags would expose, and which gate each sits behind. Starts nothing.",
99
+ )
100
+ def mcp_cmd(
101
+ use_http: bool,
102
+ host: str | None,
103
+ port: int | None,
104
+ token_file: Path | None,
105
+ rotate_token: bool,
106
+ allow_origins: tuple[str, ...],
107
+ allow_hosts: tuple[str, ...],
108
+ allow_install: bool,
109
+ allow_functions: bool,
110
+ list_tools: bool,
111
+ ) -> None:
112
+ """Serve devstuff's tools to an MCP client (stdio) or over HTTP, MCP and OpenAPI.
113
+
114
+ By default it speaks MCP over stdio: it reads JSON-RPC from stdin and answers on stdout, and is
115
+ meant to be started by a client (Claude Code, Claude Desktop), not by hand. With --http it
116
+ listens on a port instead.
117
+
118
+ Only read-only tools are exposed unless a flag says otherwise, and a tool that is off does not
119
+ merely hide: a call naming it is refused.
120
+
121
+ The server has no terminal. An installer that needs a password fails at once rather than
122
+ waiting for one nobody can type; run `devstuff install <key>` in a terminal for those.
123
+ """
124
+ http_only = {
125
+ "--host": host is not None, "--port": port is not None, "--token-file": token_file is not None,
126
+ "--rotate-token": rotate_token, "--allow-origin": bool(allow_origins),
127
+ "--allow-host": bool(allow_hosts),
128
+ }
129
+ if not use_http and any(http_only.values()):
130
+ given = ", ".join(flag for flag, on in http_only.items() if on)
131
+ raise click.UsageError(f"{given} only apply with --http.")
132
+ for name in allow_hosts:
133
+ if not _HOSTNAME.fullmatch(name):
134
+ raise click.UsageError(
135
+ f"--allow-host takes a bare host name (no port, scheme or path), not {name!r}."
136
+ )
137
+ for origin in allow_origins:
138
+ if not _ORIGIN.fullmatch(origin):
139
+ raise click.UsageError(
140
+ f"--allow-origin takes an origin like http://localhost:3000, not {origin!r}."
141
+ )
142
+
143
+ if list_tools:
144
+ _print_tools(_load(allow_install, allow_functions))
145
+ return
146
+
147
+ # Detach first, before the fd move and before anything that could run an installer (FR-11a).
148
+ # Under a shell this forks and the original process becomes a supervisor that never returns.
149
+ process.detach()
150
+ try:
151
+ process.require_no_terminal(gated=allow_install or allow_functions, warn=_warn)
152
+ except process.TerminalReachable as exc:
153
+ _fail(str(exc))
154
+
155
+ box = _load(allow_install, allow_functions)
156
+ if not use_http:
157
+ what = _enabled(allow_install, allow_functions)
158
+ click.echo(f"devstuff mcp: serving {len(box.names())} tools on stdio ({what})", err=True)
159
+ sys.exit(stdio.run(Dispatcher(box)))
160
+ _serve_http(
161
+ box, Dispatcher(box), host or DEFAULT_HOST, DEFAULT_PORT if port is None else port,
162
+ token_file, rotate_token, allow_origins, allow_hosts, _enabled(allow_install, allow_functions),
163
+ )
164
+
165
+
166
+ def _serve_http(
167
+ box: Toolbox, dispatcher: Dispatcher, host: str, port: int, token_file: Path | None,
168
+ rotate: bool, allow_origins: tuple[str, ...], allow_hosts: tuple[str, ...], enabled: str,
169
+ ) -> None:
170
+ try:
171
+ secret, path = token.load(token_file, rotate=rotate)
172
+ except token.TokenError as exc:
173
+ _fail(str(exc))
174
+ try:
175
+ server = http.make_server(
176
+ dispatcher, host=host, port=port, token=secret,
177
+ allow_hosts=allow_hosts, allow_origins=allow_origins,
178
+ )
179
+ except OSError as exc:
180
+ hint = ""
181
+ if exc.errno == errno.EADDRINUSE:
182
+ hint = (
183
+ " Another process is using it. devstuff never picks a different port: a client "
184
+ "configured for this one would fail with no explanation. Stop that process, or pass --port."
185
+ )
186
+ _fail(f"cannot listen on {host}:{port}: {exc.strerror or exc}.{hint}")
187
+
188
+ # With the port held and before any request can arrive: nothing a tool prints may reach the
189
+ # terminal or read from it (FR-11).
190
+ stdio.isolate_stdio(channel=False)
191
+ bound = server.bound_port
192
+ shown = f"[{host}]" if ":" in host else host
193
+ click.echo(
194
+ f"devstuff mcp: serving {len(box.names())} tools on http://{shown}:{bound} ({enabled}); "
195
+ f"bearer token in {path}",
196
+ err=True,
197
+ )
198
+ if not _is_loopback(host):
199
+ _warn(
200
+ f"listening on {host}, not just this machine. There is no TLS: the token crosses the network in "
201
+ f"the clear, and anyone who holds it can use every enabled tool ({enabled}). To reach a "
202
+ "loopback server from another machine, an SSH tunnel is safer."
203
+ )
204
+ sys.exit(http.serve(server))
205
+
206
+
207
+ def _load(allow_install: bool, allow_functions: bool) -> Toolbox:
208
+ try:
209
+ return _toolbox(allow_install, allow_functions)
210
+ except CatalogError as exc:
211
+ _fail(str(exc))
212
+ raise # unreachable: _fail exits
213
+
214
+
215
+ def _print_tools(box: Toolbox) -> None:
216
+ width = max((len(n) for n in box.names()), default=0)
217
+ for name in box.names():
218
+ tool = box.get(name)
219
+ first = (tool.description.splitlines() or [""])[0]
220
+ click.echo(f"{name:<{width}} [{box.gate(name).value}] {first}")
@@ -167,6 +167,24 @@ class Toolbox:
167
167
  out["additionalProperties"] = False
168
168
  return out
169
169
 
170
+ def requires_body(self, name: str) -> bool:
171
+ """Whether a REST call to this tool must carry a body: it has a required parameter (FR-23)."""
172
+ return bool(self.input_schema(self._tools[name]).get("required"))
173
+
174
+ def openai_tools(self) -> list[dict[str, Any]]:
175
+ """`GET /tools`: the OpenAI function-calling array, with FR-16c's schema rules (FR-21)."""
176
+ return [
177
+ {
178
+ "type": "function",
179
+ "function": {
180
+ "name": key,
181
+ "description": tool.description,
182
+ "parameters": self.input_schema(tool),
183
+ },
184
+ }
185
+ for key, tool in self._tools.items()
186
+ ]
187
+
170
188
  def describe(self) -> list[dict[str, Any]]:
171
189
  """The MCP `tools/list` entries."""
172
190
  return [
@@ -203,6 +221,14 @@ def to_mcp_result(result: ToolResult) -> dict[str, Any]:
203
221
  return {"content": content, "isError": result.is_error}
204
222
 
205
223
 
224
+ def rest_result(result: ToolResult) -> dict[str, Any]:
225
+ """The REST body for a call: the same facts as MCP's result (FR-23). `note` only when there is one."""
226
+ out: dict[str, Any] = {"is_error": result.is_error, "text": result.text}
227
+ if result.note:
228
+ out["note"] = result.note
229
+ return out
230
+
231
+
206
232
  def _install_hint(key: str) -> str:
207
233
  # FR-13. Appended to *every* install failure, not keyed on sudo's wording: under -v the error
208
234
  # is only "exit code 1" and sudo's line never reaches the result (F-13).