pandoras-box/youtrack-cli
Watch
8
0
Fork
You've already forked youtrack-cli
 0
Code Issues Pull requests Projects Releases 12 Packages 1 Wiki Activity Actions

docs(deployment): rewrite the yt mcp serve setup guide end-to-end #105

Merged
David merged 2 commits from docs/YT-45-mcp-serve-setup-guide into main 2026-07-05 21:58:27 +02:00
Conversation 0 Commits 2 Files changed 1 +182 -16
David commented 2026-07-05 21:54:50 +02:00
Owner
Copy link

Rework docs/deployment.md so a first-time operator can stand up yt mcp serve top-to-bottom without source diving or trial-and-error on the six points that each blocked a real install with a non-obvious error.

Adds a "Three distinct URLs" table plus an ordered "End-to-end setup" walkthrough (pick the MCP host, register a Hub Service, set the flow toggles, assemble the scope, install, DB dir, reverse-proxy TLS, register with Claude) and a troubleshooting table mapping each failure symptom to its cause and fix.

Specifics: --public-base-url is the MCP host not the YouTrack instance (opaque 405 when confused); register a Service at <instance>/hub/services, not an Auth Module -> OAuth 2.0; exact Authorization-Code + PKCE flow toggles, the /oauth/hub/callback redirect URI, and which fields to leave blank; YOUTRACK_MCP_HUB_SCOPE=0-0-0-0-0 <youtrack-service-id> offline_access with how to find the YouTrack service id and the 0-0-0-0-0 401 symptom; the SQLite DB parent dir is now created automatically (YT-42) with the historical code: 14 symptom noted; --hub-issuer = <instance>/hub distinguished from --public-base-url; and the claude mcp add --transport http registration line plus the authenticate step. Fixes the Environment table rows for --public-base-url and the now-0-0-0-0-0 offline_access scope default.

#YT-45

Rework docs/deployment.md so a first-time operator can stand up `yt mcp serve` top-to-bottom without source diving or trial-and-error on the six points that each blocked a real install with a non-obvious error. Adds a "Three distinct URLs" table plus an ordered "End-to-end setup" walkthrough (pick the MCP host, register a Hub Service, set the flow toggles, assemble the scope, install, DB dir, reverse-proxy TLS, register with Claude) and a troubleshooting table mapping each failure symptom to its cause and fix. Specifics: `--public-base-url` is the MCP host not the YouTrack instance (opaque 405 when confused); register a Service at `<instance>/hub/services`, not an Auth Module -> OAuth 2.0; exact Authorization-Code + PKCE flow toggles, the `/oauth/hub/callback` redirect URI, and which fields to leave blank; `YOUTRACK_MCP_HUB_SCOPE=0-0-0-0-0 <youtrack-service-id> offline_access` with how to find the YouTrack service id and the `0-0-0-0-0` 401 symptom; the SQLite DB parent dir is now created automatically (YT-42) with the historical `code: 14` symptom noted; `--hub-issuer` = `<instance>/hub` distinguished from `--public-base-url`; and the `claude mcp add --transport http` registration line plus the authenticate step. Fixes the Environment table rows for `--public-base-url` and the now-`0-0-0-0-0 offline_access` scope default. #YT-45
docs(deployment): rewrite the yt mcp serve setup guide end-to-end
All checks were successful
Check / fmt + clippy + build + tests (pull_request) Successful in 37s
Details
54dd82f011 
Rework docs/deployment.md so a first-time operator can stand up `yt mcp serve` top-to-bottom without source diving or trial-and-error on the six points that each blocked a real install with a non-obvious error.

Adds a "Three distinct URLs" table plus an ordered "End-to-end setup" walkthrough (pick the MCP host, register a Hub Service, set the flow toggles, assemble the scope, install, DB dir, reverse-proxy TLS, register with Claude) and a troubleshooting table mapping each failure symptom to its cause and fix.

Specifics: `--public-base-url` is the MCP host not the YouTrack instance (opaque 405 when confused); register a Service at `<instance>/hub/services`, not an Auth Module -> OAuth 2.0; exact Authorization-Code + PKCE flow toggles, the `/oauth/hub/callback` redirect URI, and which fields to leave blank; `YOUTRACK_MCP_HUB_SCOPE=0-0-0-0-0 <youtrack-service-id> offline_access` with how to find the YouTrack service id and the `0-0-0-0-0` 401 symptom; the SQLite DB parent dir is now created automatically (YT-42) with the historical `code: 14` symptom noted; `--hub-issuer` = `<instance>/hub` distinguished from `--public-base-url`; and the `claude mcp add --transport http` registration line plus the authenticate step. Fixes the Environment table rows for `--public-base-url` and the now-`0-0-0-0-0 offline_access` scope default.

#YT-45
chore: Merge from main and resolve conflicts
All checks were successful
Check / fmt + clippy + build + tests (pull_request) Successful in 47s
Details
Create release / Create release from merged PR (pull_request) Has been skipped
Details
a13a2aecc1 
Signed-off-by: David Randall <David@NiceGuyIT.biz>
David scheduled this pull request to auto merge when all checks succeed 2026-07-05 21:57:42 +02:00
David merged commit 2fd9a6c775 into main 2026-07-05 21:58:27 +02:00
David deleted branch docs/YT-45-mcp-serve-setup-guide 2026-07-05 21:58:27 +02:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
pandoras-box/youtrack-cli!105
No description provided.