Skip to content

docs: generated tool table, credential scope, NPM compatibility - #34

Merged
euisuh merged 3 commits into
masterfrom
night/readme-refresh
Oct 29, 2026
Merged

euisuh merged 3 commits into
masterfrom
night/readme-refresh

Conversation

@euisuh

@euisuh euisuh commented Oct 27, 2026

Copy link
Copy Markdown
Owner

Summary

Stacked on #33, which is stacked on #32. Merge in order #32 → #33 → this PR. The diff against master includes their commits until they merge. This PR's own commit only touches docs, docs/tools_table.py, tests/test_readme.py, and .gitignore.

  • Tool table generated from code. python docs/tools_table.py prints name, category, read-only flag, and the first sentence of each registered tool's description. tests/test_readme.py fails if the README block between <!-- tools:start --> and <!-- tools:end --> differs.
  • Doc bug fix. claude mcp add npm http://localhost:8000/sse (README and examples/claude-code.md) registers a stdio server whose command is the URL, because claude mcp add defaults to --transport stdio (checked with claude mcp add --help). It's now --transport sse, with an -H "Authorization: Bearer …" variant.
  • Install/config. Added uvx-based Claude Desktop JSON and Claude Code stdio snippets. Notes that the published 0.6.0 wheel requires Python ≥3.12 (checked on PyPI) while the source supports 3.10+.
  • Security → NPM credential scope. The server needs no NPM admin rights: it calls only /api/tokens, /api/nginx/*, and GET /api/. The section recommends a dedicated user with per-resource manage/view/hidden permissions (NPM permission-object.json), and a view-only user plus NPM_READ_ONLY for inspect-only setups. It also covers JWT handling, DNS-credential exposure, and the stripped access-list hint. SECURITY.md no longer says "dedicated NPM admin account".
  • NPM compatibility section (2.12 vs 2.13+ certificate schema), refreshed limitations, ROADMAP shipped items, and a skill example where email is optional.

Usage I ran

Stdio launch through uvx from this checkout, with NPM unreachable on purpose (NPM_URL=http://127.0.0.1:9), via a FastMCP stdio client:

NPM_READ_ONLY=true  -> 12 tools: find_host_by_domain, get_access_list, get_certificate, get_proxy_host, ...
NPM_READ_ONLY=false -> 34 tools
list_proxy_hosts -> ToolError Error calling tool 'list_proxy_hosts': Cannot reach NPM at http://127.0.0.1:9 (POST /tokens): ConnectError: [Errno 61] Connection refused

Test evidence

$ ruff check .
All checks passed!
$ pytest -q
py3.10: 233 passed in 1.69s
py3.13: 233 passed in 1.47s

Not done

docs/demo.gif still shows the pre-2.13 payload. Re-recording needs VHS: vhs docs/demo.tape.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQNvypim823UvUJXvw9amj

euisuh and others added 3 commits October 28, 2026 00:39
- Let's Encrypt requests no longer send meta.letsencrypt_email /
  letsencrypt_agree on NPM >= 2.13, whose schema rejects them
  (additionalProperties: false). Version comes from GET /api/, cached.
  email becomes optional; still required on NPM < 2.13.
- get_access_list passes ?expand=items,clients (NPM omits rules
  otherwise) and drops NPM's password "hint" (first char + length).
- update_proxy_host / update_redirection_host accept 0 for
  certificate_id / access_list_id to detach.
- Extract message from NPM's {"error": {"code", "message"}} bodies.
- Wrap httpx transport errors in NPMConnectionError naming NPM_URL.
- Support Python 3.10+; CI tests 3.10-3.13, lint as separate job.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQNvypim823UvUJXvw9amj
- create_letsencrypt_cert takes dns_provider, dns_provider_credentials
  and propagation_seconds (NPM certificate meta fields). dns_challenge
  without provider+credentials, DNS fields without dns_challenge, and
  wildcard domains over HTTP-01 are rejected before any request.
  Dry-run previews redact dns_provider_credentials.
- get_certificate and delete_certificate (NPM revokes Let's Encrypt
  certs on delete; docstring says to detach hosts first).
- MCP end-to-end tests: FastMCP in-memory client -> real NPMClient ->
  respx-mocked NPM.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQNvypim823UvUJXvw9amj
- README tool table generated from registered tools by
  docs/tools_table.py; tests/test_readme.py fails on drift.
- Fix `claude mcp add` for SSE: needs --transport sse, otherwise the
  URL is run as a stdio command. Add bearer-header variant.
- uvx-based Claude Desktop and Claude Code stdio configs.
- Security: NPM credential scope (dedicated non-admin user, per-resource
  manage/view/hidden permissions), JWT/credential handling notes.
- NPM compatibility section (2.12 vs 2.13+ certificate schema).
- Limitations refreshed; 34 tools; contributing step points at
  register_all(); ignore build/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQNvypim823UvUJXvw9amj

@euisuh euisuh left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gates: ruff, pytest (233 passed) pass locally; private-repo CI is billing-blocked, not a test result.

@euisuh
euisuh merged commit f18e016 into master Oct 29, 2026
7 checks passed
@euisuh
euisuh deleted the night/readme-refresh branch October 29, 2026 11:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant