Merge branch 'main' of https://github.com/steveyegge/beads

2025-11-23 22:26:01 -08:00
parent ed9b46d163 054700456c
commit 8f465df351
4 changed files with 802 additions and 91 deletions
--- a/.beads/beads.jsonl
+++ b/.beads/beads.jsonl
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -568,17 +568,41 @@ jobs:

 After a successful release:

-1. **Restart local daemons** to pick up the new version:
+1. **Upgrade local beads-mcp installation** to the new version:
+   ```bash
+   # Option 1: Use the bump-version.sh script (recommended during version bump)
+   ./scripts/bump-version.sh <version> --upgrade-mcp
+
+   # Option 2: Manual upgrade via pip (if installed globally)
+   pip install --upgrade beads-mcp
+
+   # Option 3: Manual upgrade via uv tool (if installed as a tool)
+   uv tool upgrade beads-mcp
+
+   # Verify the new version
+   pip show beads-mcp | grep Version
+
+   # Restart Claude Code or MCP session to pick up the new version
+   # The MCP server will load the newly installed version
+   ```
+
+   **Note:** The `--upgrade-mcp` flag can be combined with other flags:
+   ```bash
+   # Update versions, commit, install bd binary, and upgrade beads-mcp all at once
+   ./scripts/bump-version.sh 0.24.3 --commit --install --upgrade-mcp
+   ```
+
+2. **Restart local daemons** to pick up the new version:
   ```bash
   bd daemons killall --json
   # Daemons will auto-restart with new version on next bd command
   ```

-2. **Announce** on relevant channels (Twitter, blog, etc.)
-3. **Update documentation** if needed
-4. **Close milestone** on GitHub if using milestones
-5. **Update project board** if using project management
-6. **Monitor** for issues in the first 24-48 hours
+3. **Announce** on relevant channels (Twitter, blog, etc.)
+4. **Update documentation** if needed
+5. **Close milestone** on GitHub if using milestones
+6. **Update project board** if using project management
+7. **Monitor** for issues in the first 24-48 hours

 ## Troubleshooting

--- a/integrations/beads-mcp/README.md
+++ b/integrations/beads-mcp/README.md
@@ -224,21 +224,25 @@ await beads_ready_work(workspace_root="/Users/you/project-a")

 ## Known Issues

-### MCP Tools Not Loading in Claude Code (Issue [#346](https://github.com/steveyegge/beads/issues/346))
+### ~~MCP Tools Not Loading in Claude Code~~ (Issue [#346](https://github.com/steveyegge/beads/issues/346)) - RESOLVED

-**Status:** Blocked by upstream FastMCP bug ([#2455](https://github.com/jlowin/fastmcp/issues/2455))
+**Status:** ✅ Fixed in v0.24.0+

-MCP tools currently fail to load in Claude Code due to a schema generation bug in FastMCP 2.13.1. The issue affects self-referential Pydantic models and causes Claude Code to reject all beads MCP tools.
+This issue affected versions prior to v0.24.0. The problem was caused by self-referential Pydantic models (`Issue` with `dependencies: list["Issue"]`) generating invalid MCP schemas with `$ref` at root level.

-**Workaround:** Use slash commands instead of MCP tools in Claude Code:
- `/beads:ready` instead of the `ready` MCP tool
- `/beads:show bd-123` instead of the `show` MCP tool
- `/beads:list` instead of the `list` MCP tool
- etc.
+**Solution:** The issue was fixed in commit f3a678f by refactoring the data models:
+- Created `IssueBase` with common fields
+- Created `LinkedIssue(IssueBase)` for dependency references
+- Changed `Issue` to use `list[LinkedIssue]` instead of `list["Issue"]`

-Slash commands work because they call the `bd` CLI directly rather than going through the MCP tool interface.
+This breaks the circular reference and ensures all tool outputSchemas have `type: object` at root level.

-**Resolution:** This will be fixed automatically once FastMCP releases a fix for their schema generation bug. The beads-mcp dependency will then be updated to use the fixed version.
+**Upgrade:** If you're running beads-mcp < 0.24.0:
+```bash
+pip install --upgrade beads-mcp
+```
+
+All MCP tools now load correctly in Claude Code with v0.24.0+.


 ## Development
--- a/scripts/bump-version.sh
+++ b/scripts/bump-version.sh
@@ -9,24 +9,26 @@ NC='\033[0m' # No Color

 # Usage message
 usage() {
-    echo "Usage: $0 <version> [--commit] [--tag] [--push] [--install]"
+    echo "Usage: $0 <version> [--commit] [--tag] [--push] [--install] [--upgrade-mcp]"
    echo ""
    echo "Bump version across all beads components."
    echo ""
    echo "Arguments:"
-    echo "  <version>    Semantic version (e.g., 0.9.3, 1.0.0)"
-    echo "  --commit     Automatically create a git commit (optional)"
-    echo "  --tag        Create annotated git tag after commit (requires --commit)"
-    echo "  --push       Push commit and tag to origin (requires --commit and --tag)"
-    echo "  --install    Rebuild and install bd binary to GOPATH/bin after version bump"
+    echo "  <version>      Semantic version (e.g., 0.9.3, 1.0.0)"
+    echo "  --commit       Automatically create a git commit (optional)"
+    echo "  --tag          Create annotated git tag after commit (requires --commit)"
+    echo "  --push         Push commit and tag to origin (requires --commit and --tag)"
+    echo "  --install      Rebuild and install bd binary to GOPATH/bin after version bump"
+    echo "  --upgrade-mcp  Upgrade local beads-mcp installation via pip after version bump"
    echo ""
    echo "Examples:"
-    echo "  $0 0.9.3                      # Update versions and show diff"
-    echo "  $0 0.9.3 --install            # Update versions and rebuild/install bd"
-    echo "  $0 0.9.3 --commit             # Update versions and commit"
-    echo "  $0 0.9.3 --commit --tag       # Update, commit, and tag"
-    echo "  $0 0.9.3 --commit --tag --push  # Full release preparation"
-    echo "  $0 0.9.3 --commit --install   # Update, commit, and install"
+    echo "  $0 0.9.3                            # Update versions and show diff"
+    echo "  $0 0.9.3 --install                  # Update versions and rebuild/install bd"
+    echo "  $0 0.9.3 --upgrade-mcp              # Update versions and upgrade beads-mcp"
+    echo "  $0 0.9.3 --commit                   # Update versions and commit"
+    echo "  $0 0.9.3 --commit --tag             # Update, commit, and tag"
+    echo "  $0 0.9.3 --commit --tag --push      # Full release preparation"
+    echo "  $0 0.9.3 --commit --install --upgrade-mcp  # Update, commit, and install all"
    exit 1
 }

@@ -72,6 +74,7 @@ main() {
    AUTO_TAG=false
    AUTO_PUSH=false
    AUTO_INSTALL=false
+    AUTO_UPGRADE_MCP=false

    # Parse flags
    shift  # Remove version argument
@@ -89,6 +92,9 @@ main() {
            --install)
                AUTO_INSTALL=true
                ;;
+            --upgrade-mcp)
+                AUTO_UPGRADE_MCP=true
+                ;;
            *)
                echo -e "${RED}Error: Unknown option '$1'${NC}"
                usage
@@ -272,6 +278,48 @@ main() {
        echo ""
    fi

+    # Auto-upgrade MCP if requested
+    if [ "$AUTO_UPGRADE_MCP" = true ]; then
+        echo "Upgrading local beads-mcp installation..."
+
+        # Try pip first (most common)
+        if command -v pip &> /dev/null; then
+            if pip install --upgrade beads-mcp; then
+                echo -e "${GREEN}✓ beads-mcp upgraded via pip${NC}"
+                echo ""
+                INSTALLED_MCP_VERSION=$(pip show beads-mcp 2>/dev/null | grep Version | awk '{print $2}')
+                if [ "$INSTALLED_MCP_VERSION" = "$NEW_VERSION" ]; then
+                    echo -e "${GREEN}✓ Verified: beads-mcp version is $INSTALLED_MCP_VERSION${NC}"
+                    echo -e "${YELLOW}  Note: Restart Claude Code or MCP session to use the new version${NC}"
+                else
+                    echo -e "${YELLOW}⚠ Warning: beads-mcp version is $INSTALLED_MCP_VERSION (expected $NEW_VERSION)${NC}"
+                    echo -e "${YELLOW}  This is normal - PyPI package may not be published yet${NC}"
+                    echo -e "${YELLOW}  The local source version in pyproject.toml is $NEW_VERSION${NC}"
+                fi
+            else
+                echo -e "${YELLOW}⚠ pip upgrade failed or beads-mcp not installed via pip${NC}"
+                echo -e "${YELLOW}  You may need to upgrade manually after publishing to PyPI${NC}"
+            fi
+        # Try uv tool as fallback
+        elif command -v uv &> /dev/null; then
+            if uv tool list | grep -q beads-mcp; then
+                if uv tool upgrade beads-mcp; then
+                    echo -e "${GREEN}✓ beads-mcp upgraded via uv tool${NC}"
+                    echo -e "${YELLOW}  Note: Restart Claude Code or MCP session to use the new version${NC}"
+                else
+                    echo -e "${RED}✗ uv tool upgrade failed${NC}"
+                fi
+            else
+                echo -e "${YELLOW}⚠ beads-mcp not installed via uv tool${NC}"
+                echo -e "${YELLOW}  Install with: uv tool install beads-mcp${NC}"
+            fi
+        else
+            echo -e "${YELLOW}⚠ Neither pip nor uv found${NC}"
+            echo -e "${YELLOW}  Install beads-mcp with: pip install beads-mcp${NC}"
+        fi
+        echo ""
+    fi
+
    # Auto-commit if requested
    if [ "$AUTO_COMMIT" = true ]; then
        echo "Creating git commit..."
@@ -327,6 +375,9 @@ Generated by scripts/bump-version.sh"
            if [ "$AUTO_INSTALL" = false ]; then
                echo -e "  ${YELLOW}make install${NC}  # ⚠️  IMPORTANT: Rebuild and install bd binary!"
            fi
+            if [ "$AUTO_UPGRADE_MCP" = false ]; then
+                echo -e "  ${YELLOW}pip install --upgrade beads-mcp${NC}  # ⚠️  After publishing to PyPI"
+            fi
            echo "  git push origin main"
            echo "  git push origin v$NEW_VERSION"
        else
@@ -334,6 +385,9 @@ Generated by scripts/bump-version.sh"
            if [ "$AUTO_INSTALL" = false ]; then
                echo -e "  ${YELLOW}make install${NC}  # ⚠️  IMPORTANT: Rebuild and install bd binary!"
            fi
+            if [ "$AUTO_UPGRADE_MCP" = false ]; then
+                echo -e "  ${YELLOW}pip install --upgrade beads-mcp${NC}  # ⚠️  After publishing to PyPI"
+            fi
            echo "  git push origin main"
            echo "  git tag -a v$NEW_VERSION -m 'Release v$NEW_VERSION'"
            echo "  git push origin v$NEW_VERSION"
@@ -344,6 +398,10 @@ Generated by scripts/bump-version.sh"
            echo -e "  ${YELLOW}make install${NC}  # ⚠️  IMPORTANT: Rebuild and install bd binary first!"
            echo ""
        fi
+        if [ "$AUTO_UPGRADE_MCP" = false ]; then
+            echo -e "  ${YELLOW}pip install --upgrade beads-mcp${NC}  # ⚠️  After publishing to PyPI"
+            echo ""
+        fi
        echo "  git add -A"
        echo "  git commit -m 'chore: Bump version to $NEW_VERSION'"
        echo "  git tag -a v$NEW_VERSION -m 'Release v$NEW_VERSION'"
@@ -351,7 +409,7 @@ Generated by scripts/bump-version.sh"
        echo "  git push origin v$NEW_VERSION"
        echo ""
        echo "Or run with flags to automate:"
-        echo "  $0 $NEW_VERSION --commit --tag --push --install"
+        echo "  $0 $NEW_VERSION --commit --tag --push --install --upgrade-mcp"
    fi
 }