ldraney/forgejo-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add missing update_issue tool, CLAUDE.md symlink, fix auth docs #27

Merged
ldraney merged 2 commits from 26-docs-update into main 2026-06-13 18:19:16 +00:00
Conversation 2 Commits 2 Files changed 3 +43 -7
ldraney commented 2026-06-13 18:06:42 +00:00
Owner
Copy link

Summary

Docs-only fix. README was stale (missing update_issue, auth section showed basic auth as primary), and no CLAUDE.md existed for Claude Code to pick up tool inventory.

Changes

  • Added update_issue to README tool list (missing since 05b4a18)
  • Updated Auth section: token auth (FORGEJO_TOKEN) as preferred, basic auth as fallback
  • Aligned server.py get_client() docstring to match
  • Added CLAUDE.md as symlink to README

Test Plan

  • README renders correctly with 14 tools listed
  • CLAUDE.md symlink resolves to README content
  • server.py docstring matches README auth description

Review Checklist

  • No new dependencies
  • No logic changes — docs only
  • Symlink verified (CLAUDE.md -> README.md)

Related Notes

None.

Closes #26

## Summary Docs-only fix. README was stale (missing update_issue, auth section showed basic auth as primary), and no CLAUDE.md existed for Claude Code to pick up tool inventory. ## Changes - Added `update_issue` to README tool list (missing since 05b4a18) - Updated Auth section: token auth (`FORGEJO_TOKEN`) as preferred, basic auth as fallback - Aligned server.py `get_client()` docstring to match - Added CLAUDE.md as symlink to README ## Test Plan - [ ] README renders correctly with 14 tools listed - [ ] CLAUDE.md symlink resolves to README content - [ ] server.py docstring matches README auth description ## Review Checklist - [x] No new dependencies - [x] No logic changes — docs only - [x] Symlink verified (`CLAUDE.md -> README.md`) ## Related Notes None. Closes #26
docs: add missing update_issue tool, CLAUDE.md symlink, fix auth docs
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
Details
ci/woodpecker/pr/woodpecker Pipeline was successful
Details
65cb85101f 
README was missing the update_issue tool added in 05b4a18. Auth section
still showed basic auth as the primary path despite token auth being
preferred since create_api_token landed. Server.py docstring aligned
to match. CLAUDE.md symlinked to README so Claude Code picks up the
tool inventory.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ldraney commented 2026-06-13 18:08:26 +00:00
Author
Owner
Copy link

PR #27 Review

DOMAIN REVIEW

Stack: Python (docstring only), Markdown documentation, symlink.

This is a docs-only PR with 3 files changed (+8/-5). All changes are non-functional.

README.md

  • update_issue tool entry added in the correct alphabetical position within the tool list. Description is accurate and consistent with the other entries' style.
  • Auth section correctly updated to show FORGEJO_TOKEN as the primary auth method with basic auth as fallback. This matches the actual get_client() implementation in server.py which delegates to ForgejoClient() (the SDK handles auth precedence).
  • The fallback note after the code block is clear and sufficient.

CLAUDE.md

  • Symlink to README.md (120000 mode). This is a reasonable approach -- Claude Code reads CLAUDE.md for project context, and the README already contains the tool inventory and architecture overview. No duplication to maintain.

server.py

  • Docstring update only. The new text ("Auth precedence: FORGEJO_TOKEN (token auth) > FORGEJO_USER/FORGEJO_PASSWORD (basic auth). FORGEJO_URL is always required.") is accurate, concise, and aligns with the README changes. Removes the stale forgejo-sdk >= 0.2.0 note which is no longer relevant.

BLOCKERS

None. This is a docs-only PR with no logic changes. No BLOCKER criteria are triggered:

  • No new functionality requiring tests
  • No user input handling
  • No secrets or credentials (the example uses placeholder values)
  • No auth logic changes

NITS

  1. Tool count mismatch in test plan: The PR body's test plan says "README renders correctly with 14 tools listed," but the README (after this PR) lists 12 tool entries (some grouped, e.g., list_issues / list_prs / list_branches). The actual codebase has 16 @mcp.tool() definitions. Neither "14" nor "12" matches "16." Not blocking for a docs PR, but the README tool list could fall out of sync again. Consider a follow-up to list all 16 tools individually.

  2. Missing newline at end of CLAUDE.md symlink: The diff shows \ No newline at end of file for the symlink target. This is normal for symlink content in git and has no practical impact, but worth noting.

SOP COMPLIANCE

  • PR body has: Summary, Changes, Test Plan, Related -- all present and filled
  • No secrets committed (example uses "your-api-token" placeholder)
  • No unnecessary file changes -- all 3 files are on-topic for the issue
  • Commit message is descriptive (docs: add missing update_issue tool, CLAUDE.md symlink, fix auth docs)
  • Branch naming follows convention (26-docs-update)
  • PR references parent issue (Closes #26)

PROCESS OBSERVATIONS

  • Low change-failure risk: docs-only, no logic changes.
  • The pattern of docs falling behind after feature merges (update_issue merged in #25 but README not updated) suggests a process gap. Consider adding a checklist item to feature PR templates: "README tool list updated?"

VERDICT: APPROVED

## PR #27 Review ### DOMAIN REVIEW **Stack**: Python (docstring only), Markdown documentation, symlink. This is a docs-only PR with 3 files changed (+8/-5). All changes are non-functional. **README.md** - `update_issue` tool entry added in the correct alphabetical position within the tool list. Description is accurate and consistent with the other entries' style. - Auth section correctly updated to show `FORGEJO_TOKEN` as the primary auth method with basic auth as fallback. This matches the actual `get_client()` implementation in `server.py` which delegates to `ForgejoClient()` (the SDK handles auth precedence). - The fallback note after the code block is clear and sufficient. **CLAUDE.md** - Symlink to README.md (`120000` mode). This is a reasonable approach -- Claude Code reads CLAUDE.md for project context, and the README already contains the tool inventory and architecture overview. No duplication to maintain. **server.py** - Docstring update only. The new text ("Auth precedence: FORGEJO_TOKEN (token auth) > FORGEJO_USER/FORGEJO_PASSWORD (basic auth). FORGEJO_URL is always required.") is accurate, concise, and aligns with the README changes. Removes the stale `forgejo-sdk >= 0.2.0` note which is no longer relevant. ### BLOCKERS None. This is a docs-only PR with no logic changes. No BLOCKER criteria are triggered: - No new functionality requiring tests - No user input handling - No secrets or credentials (the example uses placeholder values) - No auth logic changes ### NITS 1. **Tool count mismatch in test plan**: The PR body's test plan says "README renders correctly with 14 tools listed," but the README (after this PR) lists 12 tool entries (some grouped, e.g., `list_issues / list_prs / list_branches`). The actual codebase has 16 `@mcp.tool()` definitions. Neither "14" nor "12" matches "16." Not blocking for a docs PR, but the README tool list could fall out of sync again. Consider a follow-up to list all 16 tools individually. 2. **Missing newline at end of CLAUDE.md symlink**: The diff shows `\ No newline at end of file` for the symlink target. This is normal for symlink content in git and has no practical impact, but worth noting. ### SOP COMPLIANCE - [x] PR body has: Summary, Changes, Test Plan, Related -- all present and filled - [x] No secrets committed (example uses `"your-api-token"` placeholder) - [x] No unnecessary file changes -- all 3 files are on-topic for the issue - [x] Commit message is descriptive (`docs: add missing update_issue tool, CLAUDE.md symlink, fix auth docs`) - [x] Branch naming follows convention (`26-docs-update`) - [x] PR references parent issue (`Closes #26`) ### PROCESS OBSERVATIONS - Low change-failure risk: docs-only, no logic changes. - The pattern of docs falling behind after feature merges (update_issue merged in #25 but README not updated) suggests a process gap. Consider adding a checklist item to feature PR templates: "README tool list updated?" ### VERDICT: APPROVED
docs: replace ASCII architecture with mermaid diagrams showing platform context
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
Details
ci/woodpecker/pr/woodpecker Pipeline was successful
Details
097fb6f2ff 
The old one-liner didn't explain how forgejo-mcp relates to the rest of
the platform. New diagrams show the action path (agents → MCP → SDK →
API) and how it's parallel to the measurement path (API → DORA exporter
→ Prometheus → Grafana). Makes clear forgejo-mcp is not in the
observability pipeline.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ldraney commented 2026-06-13 18:18:13 +00:00
Author
Owner
Copy link

PR #27 Review

DOMAIN REVIEW

Tech stack: Docs-only (Markdown, Mermaid diagrams, symlink, Python docstring). No logic changes.

Files changed (3):

  • CLAUDE.md -- new symlink to README.md
  • README.md -- added update_issue tool, replaced ASCII architecture diagram with Mermaid, rewrote auth section
  • src/forgejo_mcp/server.py -- docstring update in get_client()

Mermaid diagrams: Both diagrams are syntactically correct and accurately represent the architecture:

  • Action path: Agents -> forgejo-mcp -> forgejo-sdk -> Forgejo API (correct)
  • Measurement path: Forgejo API + Woodpecker API -> DORA exporter -> Prometheus -> Grafana (correct, and clearly separates the two paths)
  • Prose clarifies forgejo-mcp is not in the observability pipeline (good, addresses what would otherwise be a common misconception)

Auth section: Token auth promoted to preferred, basic auth documented as fallback. Matches get_client() docstring and actual ForgejoClient behavior. The JSON example now shows only FORGEJO_TOKEN which is cleaner. Fallback documented in prose below the JSON block.

Symlink: CLAUDE.md -> README.md (mode 120000 confirms symlink). This gives Claude Code the tool inventory without content duplication.

server.py docstring: Change from old text ("Reads FORGEJO_URL, FORGEJO_USER, FORGEJO_PASSWORD...Token auth requires forgejo-sdk >= 0.2.0") to new text ("Auth precedence: FORGEJO_TOKEN > FORGEJO_USER/FORGEJO_PASSWORD. FORGEJO_URL is always required.") is accurate and removes the stale SDK version note.

BLOCKERS

None. This is a docs-only PR with no logic changes. No test coverage needed for documentation updates.

NITS

  1. Tool count in test plan is off. PR body says "14 tools listed" but the actual count in workflows.py is 16 unique @mcp.tool() decorators. The README groups some on shared lines (e.g., list_issues / list_prs / list_branches), but whether you count unique tools (16) or bullet points (12), neither is 14. Update the test plan checklist to reflect the accurate count.

  2. Missing review_pr from README tool list. After applying the diff, the tool list bullet for review_pr is present (line 8 in current README: review_pr -- gets diff + metadata for review). Confirmed this is fine -- the tool is listed.

  3. No trailing newline on CLAUDE.md. The diff shows \ No newline at end of file for the symlink target. This is standard for symlinks created by git and not a real issue.

SOP COMPLIANCE

  • PR body has: ## Summary, ## Changes, ## Test Plan, ## Related (as "## Related Notes")
  • No secrets, .env files, or credentials committed
  • No unnecessary file changes -- all three files are in scope for the docs issue
  • Commit messages are descriptive
  • PR references parent issue (#26) with Closes #26
  • Branch naming follows convention: 26-docs-update

PROCESS OBSERVATIONS

  • Clean docs-only PR. Low change failure risk.
  • The Mermaid diagrams are a significant improvement over the ASCII one-liner -- they make the architecture legible for both humans and agents consuming CLAUDE.md.
  • Separating the action path from the measurement path in the architecture section is good documentation practice; it prevents agents from thinking they need forgejo-mcp for observability tasks.

VERDICT: APPROVED

## PR #27 Review ### DOMAIN REVIEW **Tech stack:** Docs-only (Markdown, Mermaid diagrams, symlink, Python docstring). No logic changes. **Files changed (3):** - `CLAUDE.md` -- new symlink to `README.md` - `README.md` -- added `update_issue` tool, replaced ASCII architecture diagram with Mermaid, rewrote auth section - `src/forgejo_mcp/server.py` -- docstring update in `get_client()` **Mermaid diagrams:** Both diagrams are syntactically correct and accurately represent the architecture: - Action path: Agents -> forgejo-mcp -> forgejo-sdk -> Forgejo API (correct) - Measurement path: Forgejo API + Woodpecker API -> DORA exporter -> Prometheus -> Grafana (correct, and clearly separates the two paths) - Prose clarifies forgejo-mcp is not in the observability pipeline (good, addresses what would otherwise be a common misconception) **Auth section:** Token auth promoted to preferred, basic auth documented as fallback. Matches `get_client()` docstring and actual `ForgejoClient` behavior. The JSON example now shows only `FORGEJO_TOKEN` which is cleaner. Fallback documented in prose below the JSON block. **Symlink:** `CLAUDE.md -> README.md` (mode `120000` confirms symlink). This gives Claude Code the tool inventory without content duplication. **server.py docstring:** Change from old text ("Reads FORGEJO_URL, FORGEJO_USER, FORGEJO_PASSWORD...Token auth requires forgejo-sdk >= 0.2.0") to new text ("Auth precedence: FORGEJO_TOKEN > FORGEJO_USER/FORGEJO_PASSWORD. FORGEJO_URL is always required.") is accurate and removes the stale SDK version note. ### BLOCKERS None. This is a docs-only PR with no logic changes. No test coverage needed for documentation updates. ### NITS 1. **Tool count in test plan is off.** PR body says "14 tools listed" but the actual count in `workflows.py` is **16** unique `@mcp.tool()` decorators. The README groups some on shared lines (e.g., `list_issues / list_prs / list_branches`), but whether you count unique tools (16) or bullet points (12), neither is 14. Update the test plan checklist to reflect the accurate count. 2. **Missing `review_pr` from README tool list.** After applying the diff, the tool list bullet for `review_pr` is present (line 8 in current README: `review_pr -- gets diff + metadata for review`). Confirmed this is fine -- the tool is listed. 3. **No trailing newline on CLAUDE.md.** The diff shows `\ No newline at end of file` for the symlink target. This is standard for symlinks created by git and not a real issue. ### SOP COMPLIANCE - [x] PR body has: ## Summary, ## Changes, ## Test Plan, ## Related (as "## Related Notes") - [x] No secrets, .env files, or credentials committed - [x] No unnecessary file changes -- all three files are in scope for the docs issue - [x] Commit messages are descriptive - [x] PR references parent issue (#26) with `Closes #26` - [x] Branch naming follows convention: `26-docs-update` ### PROCESS OBSERVATIONS - Clean docs-only PR. Low change failure risk. - The Mermaid diagrams are a significant improvement over the ASCII one-liner -- they make the architecture legible for both humans and agents consuming CLAUDE.md. - Separating the action path from the measurement path in the architecture section is good documentation practice; it prevents agents from thinking they need forgejo-mcp for observability tasks. ### VERDICT: APPROVED
ldraney deleted branch 26-docs-update 2026-06-13 18:19:16 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
domain:backend

   
domain:devops

   
domain:frontend

   
status:approved

QA passed, awaiting merge approval

  
status:in-progress

Dev agent is actively working

  
status:needs-fix

QA found issues, back to dev

  
status:qa

PR submitted, awaiting QA review

  
test:label-a

   
test:label-b

   
test:set-label

   
type:bug

Bug fix

  
type:devops

Infrastructure/CI/config work

  
type:feature

New functionality

No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
test:label-a
test:label-b
test:set-label
type:bug
type:devops
type:feature
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
ldraney/forgejo-mcp!27
No description provided.