Fix MCP Search Tool (#1)

* refactor(ci): support multiple scoped tags in release workflow

Update release workflow and bump script to handle multiple plugin releases in a single commit.

Changes:
- release.yml: Parse multiple scoped tags (e.g., android/v0.0.3, devbox-mcp/v0.1.3) from commit message
- release.yml: Create multiple git tags and use first tag for GitHub Release title
- release.yml: Detect devbox-mcp version bumps from tag in commit message instead of git diff
- bump.sh: Use scoped tags in commit messages instead of generic v* tags
- bump.sh: Find last release tag by creation date across all scoped tags
- devbox-mcp README: Add detailed GitHub token setup instructions for docs_search tool
- devbox-mcp index.js: Improve docs_search description with authentication troubleshooting steps
- devbox-mcp index.js: Remove unnecessary path filters from GitHub search query

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* chore(release): devbox-mcp/v0.1.3

## What changed

Patch release improving CI release workflow with support for multiple scoped tags.

### Plugins bumped

| Plugin | Version |
|--------|---------|
| devbox-mcp | 0.1.2 -> 0.1.3 |

### Changes

#### Other
- Refactored CI release workflow to support multiple scoped tags
- Moved tag creation from bump.sh script to release.yml workflow
- Migrated to GitHub plugin references and simplified release workflow

* update treefmt

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: abueide

.github/workflows/release.yml

@@ -10,7 +10,9 @@ jobs:
       contents: write
     outputs:
       is_release: ${{ steps.check.outputs.is_release }}
-      tag: ${{ steps.check.outputs.tag }}
+      tags: ${{ steps.check.outputs.tags }}
+      first_tag: ${{ steps.check.outputs.first_tag }}
+      title: ${{ steps.check.outputs.title }}
       mcp_bumped: ${{ steps.check-mcp.outputs.mcp_bumped }}
       mcp_version: ${{ steps.check-mcp.outputs.mcp_version }}
     steps:
@@ -24,8 +26,14 @@ jobs:
           MSG=$(git log -1 --format=%s)
           if echo "$MSG" | grep -qE '^chore\(release\):'; then
             echo "is_release=true" >> "$GITHUB_OUTPUT"
-            TAG=$(echo "$MSG" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+')
-            echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+            TAGS=$(echo "$MSG" | grep -oE '[a-z][-a-z]*/v[0-9]+\.[0-9]+\.[0-9]+')
+            echo "tags<<EOF" >> "$GITHUB_OUTPUT"
+            echo "$TAGS" >> "$GITHUB_OUTPUT"
+            echo "EOF" >> "$GITHUB_OUTPUT"
+            FIRST_TAG=$(echo "$TAGS" | head -1)
+            echo "first_tag=$FIRST_TAG" >> "$GITHUB_OUTPUT"
+            TITLE=$(echo "$MSG" | sed 's/^chore(release): //')
+            echo "title=$TITLE" >> "$GITHUB_OUTPUT"
             BODY=$(git log -1 --format=%b)
             echo "body<<EOF" >> "$GITHUB_OUTPUT"
             echo "$BODY" >> "$GITHUB_OUTPUT"
@@ -38,8 +46,10 @@ jobs:
         id: check-mcp
         if: steps.check.outputs.is_release == 'true'
         run: |
-          if git diff --name-only HEAD~1 HEAD | grep -q '^plugins/devbox-mcp/package.json$'; then
-            VERSION=$(jq -r '.version' plugins/devbox-mcp/package.json)
+          MSG=$(git log -1 --format=%s)
+          MCP_TAG=$(echo "$MSG" | grep -oE 'devbox-mcp/v[0-9]+\.[0-9]+\.[0-9]+' || true)
+          if [ -n "$MCP_TAG" ]; then
+            VERSION=$(echo "$MCP_TAG" | sed 's|devbox-mcp/v||')
             echo "mcp_bumped=true" >> "$GITHUB_OUTPUT"
             echo "mcp_version=$VERSION" >> "$GITHUB_OUTPUT"
             echo "devbox-mcp version bumped to $VERSION"
@@ -48,19 +58,23 @@ jobs:
             echo "devbox-mcp not changed in this release"
           fi
 
-      - name: Create git tag
-        if: steps.check.outputs.is_release == 'true' && steps.check.outputs.tag != ''
+      - name: Create git tags
+        if: steps.check.outputs.is_release == 'true' && steps.check.outputs.tags != ''
         run: |
-          git tag "${{ steps.check.outputs.tag }}"
-          git push origin "${{ steps.check.outputs.tag }}"
+          echo "${{ steps.check.outputs.tags }}" | while read -r TAG; do
+            [ -z "$TAG" ] && continue
+            echo "Creating tag: $TAG"
+            git tag "$TAG"
+            git push origin "$TAG"
+          done
 
       - name: Create GitHub Release
-        if: steps.check.outputs.is_release == 'true' && steps.check.outputs.tag != ''
+        if: steps.check.outputs.is_release == 'true' && steps.check.outputs.first_tag != ''
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          gh release create "${{ steps.check.outputs.tag }}" \
-            --title "${{ steps.check.outputs.tag }}" \
+          gh release create "${{ steps.check.outputs.first_tag }}" \
+            --title "${{ steps.check.outputs.title }}" \
             --notes "${{ steps.check.outputs.body }}"
 
   npm-publish:

plugins/devbox-mcp/README.md

@@ -24,10 +24,19 @@ Model Context Protocol server for [Jetify's devbox](https://www.jetify.com/devbo
 
 The `.devbox/virtenv/` directory is automatically regenerated on `devbox shell` or `devbox run`. Any manual changes will be lost.
 
+## Environment Variables
+
+The devbox-mcp server supports the following optional environment variables:
+
+- **`GITHUB_TOKEN`** or **`GITHUB_PAT`**: Required for `devbox_docs_search` tool. GitHub Personal Access Token with `public_repo` read access. Without this, the docs search tool will fail with authentication errors.
+
+See the Installation section below for how to configure environment variables.
+
 ## Installation
 
 ### For Claude Code
 
+Basic installation (without GitHub token):
 ```bash
 # Install via npx (recommended)
 claude mcp add devbox -- npx -y devbox-mcp-server
@@ -37,10 +46,18 @@ npm install -g devbox-mcp-server
 claude mcp add devbox -- devbox-mcp-server
 ```
 
-### For Claude Desktop
+With GitHub token for `devbox_docs_search` (recommended):
+```bash
+# User-wide configuration
+claude mcp add devbox-mcp -s user -e GITHUB_TOKEN="your_token_here" -- npx -y devbox-mcp-server
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+# Or for local development
+claude mcp add devbox-mcp -s user -e GITHUB_TOKEN="your_token_here" -- node /path/to/devbox-mcp/src/index.js
+```
+
+### For Claude Desktop
 
+Without GitHub token:
 ```json
 {
   "mcpServers": {
@@ -52,6 +69,21 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+With GitHub token (recommended):
+```json
+{
+  "mcpServers": {
+    "devbox": {
+      "command": "npx",
+      "args": ["-y", "devbox-mcp-server"],
+      "env": {
+        "GITHUB_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
 ## Development
 
 This plugin includes its own devbox environment for development:
@@ -125,16 +157,40 @@ Initialize a new devbox.json file in the specified directory.
 ### `devbox_docs_search`
 Search the devbox documentation for relevant information.
 
-**Requires GitHub Authentication:** This tool uses GitHub's code search API which requires a Personal Access Token (PAT). Set one of these environment variables:
-- `GITHUB_TOKEN=your_token_here`
-- `GITHUB_PAT=your_token_here`
-
-To create a token:
-1. Visit https://github.com/settings/tokens
-2. Create a fine-grained token with `public_repo` read access
-3. Set it in your environment
-
-If authentication isn't available, use `devbox_docs_list` to browse files, then `devbox_docs_read` to read specific docs.
+**Requires GitHub Authentication:** This tool uses GitHub's code search API which requires authentication.
+
+**Setup Instructions:**
+
+1. Create a GitHub Personal Access Token (PAT):
+   - Visit https://github.com/settings/tokens
+   - Click "Generate new token" (fine-grained or classic)
+   - Grant `public_repo` or `repo` read access
+   - Copy the token
+
+2. Configure the MCP server with your token:
+
+   For Claude Code (user-wide):
+   ```bash
+   claude mcp remove devbox-mcp -s user  # Remove existing config
+   claude mcp add devbox-mcp -s user -e GITHUB_TOKEN="your_token_here" -- node /path/to/devbox-mcp/src/index.js
+   ```
+
+   For Claude Desktop, add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+   ```json
+   {
+     "mcpServers": {
+       "devbox": {
+         "command": "node",
+         "args": ["/path/to/devbox-mcp/src/index.js"],
+         "env": {
+           "GITHUB_TOKEN": "your_token_here"
+         }
+       }
+     }
+   }
+   ```
+
+**Alternative (no auth required):** Use `devbox_docs_list` to browse files, then `devbox_docs_read` to read specific docs.
 
 ```typescript
 devbox_docs_search({
@@ -166,7 +222,10 @@ devbox_docs_read({
 
 - Node.js 18+ (for native fetch support)
 - devbox CLI installed and in PATH (for devbox commands)
-- GitHub Personal Access Token (optional, required for `devbox_docs_search`)
+- GitHub Personal Access Token (optional, but required for `devbox_docs_search` tool)
+  - Create at: https://github.com/settings/tokens
+  - Requires: `public_repo` or `repo` read access
+  - Configure via `GITHUB_TOKEN` environment variable in MCP config
 
 ## License
 

plugins/devbox-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devbox-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Model Context Protocol server for Jetify's devbox development environment tool",
   "type": "module",
   "main": "src/index.js",

plugins/devbox-mcp/src/index.js

@@ -110,7 +110,8 @@ async function searchDocs(query, options = {}) {
 
   try {
     // Use GitHub's code search API
-    const searchQuery = `${query} repo:jetify-com/docs path:*.md path:*.mdx`;
+    // Search in the docs repo - most files are markdown anyway
+    const searchQuery = `${query} repo:jetify-com/docs`;
     const url = new URL("https://api.github.com/search/code");
     url.searchParams.set("q", searchQuery);
     url.searchParams.set("per_page", String(maxResults));
@@ -320,11 +321,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       {
         name: "devbox_docs_search",
         description:
-          "Search devbox documentation for a keyword or phrase. " +
-          "Returns matching lines from the official devbox docs repository.\n\n" +
-          "Requires: GitHub Personal Access Token (PAT) set as GITHUB_TOKEN or GITHUB_PAT environment variable. " +
-          "Create a token at https://github.com/settings/tokens with public_repo read access.\n\n" +
-          "Alternative: Use devbox_docs_list to browse files, then devbox_docs_read to read specific docs.",
+          "Search devbox documentation for a keyword or phrase. Returns matching lines from the official devbox docs repository.\n\n" +
+          "IMPORTANT - Authentication Required:\n" +
+          "This tool requires a GitHub Personal Access Token (PAT) configured in the MCP server environment. " +
+          "If the user hasn't configured their GITHUB_TOKEN, this tool will fail with a 403 error. " +
+          "When this happens, inform the user they need to reconfigure their MCP server:\n\n" +
+          "  claude mcp remove devbox-mcp -s user\n" +
+          "  claude mcp add devbox-mcp -s user -e GITHUB_TOKEN=\"your_token\" -- node /path/to/devbox-mcp/src/index.js\n\n" +
+          "To create a GitHub PAT:\n" +
+          "1. Visit https://github.com/settings/tokens\n" +
+          "2. Create a fine-grained token or classic token\n" +
+          "3. Grant 'public_repo' or 'repo' read access\n" +
+          "4. Set it as GITHUB_TOKEN environment variable in MCP config\n\n" +
+          "Alternative: Use devbox_docs_list (no auth required) to browse files, then devbox_docs_read to read specific docs.",
         inputSchema: {
           type: "object",
           properties: {

scripts/bump.sh

@@ -68,7 +68,7 @@ fi
 # Step 2: Find last release tag
 # ---------------------------------------------------------------------------
 
-LAST_TAG=$(git tag -l 'v*' --sort=-v:refname | head -1 || true)
+LAST_TAG=$(git tag -l --sort=-creatordate | grep -E '(^v[0-9]|/v[0-9])' | head -1 || true)
 if [ -z "$LAST_TAG" ]; then
   LAST_TAG=$(git rev-list --max-parents=0 HEAD)
   echo "No release tags found, using initial commit: ${LAST_TAG:0:8}"
@@ -173,10 +173,6 @@ BUMPED_LIST=$(printf '%s\n' "${BUMPED_SUMMARY[@]}")
 LOG_OUTPUT=$(git log --oneline "$LAST_TAG"..HEAD -- "${CHANGED_DIRS[@]}")
 TEMPLATE=$(cat "$REPO_ROOT/scripts/bump-template.md")
 
-# Determine the representative new version (use the first bumped plugin's new version)
-IFS=':' read -r _ first_file first_path <<< "${CHANGED_PLUGINS[0]}"
-NEW_VERSION=$(jq -r "$first_path" "$first_file")
-
 echo "Generating release summary with Claude..."
 
 RELEASE_SUMMARY=$(claude -p --model sonnet <<PROMPT
@@ -205,33 +201,33 @@ echo ""
 # Step 7: Stage, commit, and tag
 # ---------------------------------------------------------------------------
 
-# Build plugin name list for commit message
-PLUGIN_NAMES=""
+# Build scoped tag list for commit message (e.g. android/v0.0.3, devbox-mcp/v0.1.3)
+SCOPED_TAGS=""
 for entry in "${CHANGED_PLUGINS[@]}"; do
-  IFS=':' read -r plugin_dir _ _ <<< "$entry"
+  IFS=':' read -r plugin_dir version_file jq_path <<< "$entry"
   name=$(basename "$plugin_dir")
-  if [ -z "$PLUGIN_NAMES" ]; then
-    PLUGIN_NAMES="$name"
+  version=$(jq -r "$jq_path" "$version_file")
+  tag="${name}/v${version}"
+  if [ -z "$SCOPED_TAGS" ]; then
+    SCOPED_TAGS="$tag"
   else
-    PLUGIN_NAMES="$PLUGIN_NAMES, $name"
+    SCOPED_TAGS="$SCOPED_TAGS, $tag"
   fi
 done
 
 git add "${CHANGED_FILES[@]}"
 
 git commit -m "$(cat <<EOF
-chore(release): bump ${PLUGIN_NAMES} to v${NEW_VERSION}
+chore(release): ${SCOPED_TAGS}
 
 ${RELEASE_SUMMARY}
 EOF
 )"
 
-TAG="v${NEW_VERSION}"
-
-echo "Committed: $TAG"
+echo "Committed: ${SCOPED_TAGS}"
 echo ""
 echo "To publish this release:"
 echo "  1. Push your branch and open a PR:"
 echo "     git push -u origin HEAD"
-echo "     gh pr create --title 'chore(release): bump ${PLUGIN_NAMES} to ${TAG}'"
-echo "  2. After CI passes and the PR is merged, release.yml will create the tag and GitHub Release."
+echo "     gh pr create --title 'chore(release): ${SCOPED_TAGS}'"
+echo "  2. After CI passes and the PR is merged, release.yml will create the tags and GitHub Release."

treefmt.toml

@@ -17,6 +17,8 @@
 #     exec treefmt --fail-on-change
 
 [global]
+# Use git to walk files, which respects .gitignore
+walk = "git"
 excludes = [
   "*.md",
   "*.lock",