Release v1.5.0: MCP SDK upgrade, security improvements, and new tools (#6)

* feat: add default inbox configuration and remove deprecated PAT authentication

This commit implements three major improvements:

1. Default Inbox Configuration (Option 4 - Hybrid Approach)
   - Add HELPSCOUT_DEFAULT_INBOX_ID environment variable
   - Automatic inbox scoping: explicit inboxId > default > all inboxes
   - Clear feedback in search results showing which scope was used
   - Improves LLM context when users don't specify inbox
   - All search tools (searchConversations, advancedConversationSearch, comprehensiveConversationSearch) support default inbox

2. Remove Personal Access Token Authentication
   - Help Scout API only supports OAuth2 Client Credentials (verified from official docs)
   - Removed PAT authentication logic from helpscout-client.ts
   - Updated all documentation (README.md, CLAUDE.md) to OAuth2-only
   - Updated config validation to require OAuth2 credentials
   - Clearer error messages mentioning OAuth2 specifically
   - Updated all tests to use OAuth2 mocking

3. Repository Cleanup
   - Removed outdated documentation files:
     * PLANNED_IMPROVEMENTS.md (2-item outdated planning doc)
     * PRODUCTION_WORKFLOW.md (v1.2.1 workflow, superseded by CLAUDE.md)
     * test_search_examples.md (old manual test examples)
   - Kept CONTRIBUTING.md (still relevant)

Breaking Changes:
   - Personal Access Token authentication no longer supported
   - Users must use OAuth2 Client Credentials (HELPSCOUT_CLIENT_ID + HELPSCOUT_CLIENT_SECRET)

Migration Guide:
   - If using HELPSCOUT_API_KEY=Bearer token: migrate to OAuth2 app in Help Scout My Apps
   - Optional: Set HELPSCOUT_DEFAULT_INBOX_ID to improve LLM search context

* feat: add comprehensive MCP client testing framework with .env support

- Create test-mcp-client.cjs for end-to-end MCP protocol testing
- Update test-docker.cjs to load credentials from .env file
- Update .env.example to reflect OAuth2-only authentication
- Add npm script: npm run test:mcp for quick integration testing
- Support HELPSCOUT_DEFAULT_INBOX_ID in all test scripts
- Fix security vulnerabilities in dependencies (axios, form-data)

Testing Framework:
- npm run test:mcp - Direct MCP client test (fastest, tests built server)
- npm run test:docker - Docker integration test with .env credentials
- npm run test:docker:ci - CI-safe test (no auth required)

Tests validate:
- Server startup and initialization
- All 8 MCP tools (listAllInboxes, searchConversations, etc.)
- Resources and prompts endpoints
- Default inbox configuration behavior
- OAuth2 authentication flow

All tests now load credentials from .env file for convenience.

* feat: add structuredConversationFilter for ID-based refinement after content discovery

Adds new tool for structural filtering by:
- assignedTo: Filter by user ID (discovered from previous searches)
- customerIds: Batch customer lookup by IDs
- conversationNumber: Direct ticket #12345 lookup
- folderId: Folder-based filtering (power users)
- Advanced sorting: waitingSince, customerName, customerEmail

Design philosophy: Enhancement, not replacement
- Content search remains primary (comprehensiveConversationSearch)
- This tool for refinement after discovering IDs
- Enables: rep queue queries, SLA sorting, efficient customer history

Tool description explicitly lists 5 unique fields and when to use each.

* fix: critical security and reliability improvements from code review

Security Fixes:
- Add query injection protection by escaping user input in Help Scout query syntax
- Detect deprecated PAT tokens and reject with clear migration error
- Add integer bounds validation (assignedTo, folderId, customerIds, conversationNumber)
- Enforce HTTPS for API base URL to prevent credential exposure
- Remove internal URL/method from error responses (log internally only)

Reliability Fixes:
- Add promise-based locking to prevent concurrent token refresh race conditions
- Document client-side createdBefore filtering limitation in responses
- Add warnings when pagination totals don't reflect filtered results

All fixes validated with real Help Scout data (16,443 conversations tested).

* fix: improve tool discovery with clearer descriptions and decision tree

Tool Description Improvements:
- searchConversations: Simplified to 'list by time/status' (no keywords needed)
- comprehensiveConversationSearch: Clear 'keyword search' with use case examples
- advancedConversationSearch: Explicit about complex filters (domains, tags, boolean)
- structuredConversationFilter: Clear it's for IDs or ticket number lookup

README Enhancements:
- Added 'Quick Guide: Which tool should I use?' decision tree
- Clear USE FOR examples in table: 'Recent tickets' vs 'Find billing issues'
- Categorized tools by purpose: TIME/STATUS, KEYWORD, ID LOOKUP, COMPLEX
- Added listAllInboxes to tools table (was missing)

Addresses critical tool confusion issue where LLM couldn't determine which search tool to use.

* feat: upgrade to MCP SDK 1.22.0 and migrate DXT to MCPB 2.0.1

Package Upgrades:
- @modelcontextprotocol/sdk: 1.17.4 → 1.22.0 (latest)
- @anthropic-ai/dxt: 0.2.6 → removed
- @anthropic-ai/mcpb: 2.0.1 → installed
- Fixed security vulnerabilities (glob, js-yaml)

Breaking Changes Fixed:
- MCP SDK 1.22.0: Resource type no longer has 'text' field
- Updated all resource handlers to return TextResourceContents
- Resources now separate metadata (Resource) from content (TextResourceContents)

Script Updates:
- mcpb:pack now uses '@anthropic-ai/mcpb pack' instead of '@anthropic-ai/dxt pack'
- Updated build-dxt.js instructions to reference MCPB CLI
- Updated .gitignore to include *.mcpb files

Build Status:
- TypeScript compilation: ✅ PASS
- Type checking: ✅ PASS
- All 9 tools compatible with SDK 1.22.0

* feat: improve content redaction naming and auth variable alignment

- Add HELPSCOUT_APP_ID/APP_SECRET to match Help Scout UI terminology
- Add REDACT_MESSAGE_CONTENT as primary content control variable
- Default to showing content (REDACT_MESSAGE_CONTENT=false)
- Update redaction placeholder with actionable message
- Maintain backwards compatibility with ALLOW_PII and CLIENT_ID/SECRET
- Update DXT tests for 9 tools (added structuredConversationFilter)
- Fix tools.test.ts mock conflicts with unique conversation IDs

* test: update config test to use CLIENT_ID/SECRET

Align test with auth variable changes - use HELPSCOUT_CLIENT_ID
and HELPSCOUT_CLIENT_SECRET instead of deprecated Bearer token pattern.

* chore: upgrade MCP SDK to 1.25.2

Bump @modelcontextprotocol/sdk from 1.22.0 to 1.25.2

* chore: add dev utility scripts for testing

- check-conversations.ts: Query and verify conversation data
- debug-api.ts: Debug Help Scout API responses
- generate-synthetic-data.ts: Create synthetic test data
- import-conversations.ts: Import conversations for testing
- live-api-test.ts: Live API integration testing
- verify-credentials.ts: Validate Help Scout credentials

All scripts use HELPSCOUT_DEFAULT_INBOX_ID from .env for mailbox operations.
Script state files (.import-progress.json) are gitignored.

* chore: bump version 1.3.0 → 1.4.0 (minor)

- Update package.json version
- Update Dockerfile version label
- Update MCP server version in source code
- Update mcp.json version
- Update DXT manifest version
- Automated version bump for release

* docs: clean up README formatting, update env vars, and modernize ecosystem references

- Remove excessive emojis from headers
- Add About This Project section at bottom
- Update all examples to use APP_ID/APP_SECRET as primary
- Fix config.ts secret precedence for consistency
- Update Compatibility section with current MCP ecosystem
- Broaden Quick Start headers for multi-client support
- Update What's New section for v1.4.0

* chore: bump to v1.5.0, add CI branch guard for Docker builds

- Add main branch verification to docker job (prevents dev tag builds)
- Bump all version files to 1.5.0 (package.json, src/index.ts, Dockerfile, mcp.json, manifest.json)
- Update README env vars to prioritize APP_ID/APP_SECRET
- Update MCP ecosystem compatibility section
- Delete errant v1.4.0 tag that was pushed from dev

Author: drewburchfield

.env.example

@@ -1,15 +1,38 @@
 # Help Scout API Configuration
-# Option 1: Personal Access Token (recommended)
-HELPSCOUT_API_KEY=Bearer your-personal-access-token-here
+# OAuth2 Client Credentials (only supported method)
+# Get these from: Help Scout → My Apps → Create Private App
+#
+# Variable names match Help Scout UI exactly:
+#   Help Scout UI    Environment Variable
+#   "App ID"      →  HELPSCOUT_APP_ID
+#   "App Secret"  →  HELPSCOUT_APP_SECRET
+#
+HELPSCOUT_APP_ID=your-app-id-from-helpscout
+HELPSCOUT_APP_SECRET=your-app-secret-from-helpscout
 
-# Option 2: OAuth2 App Credentials (legacy)
-# HELPSCOUT_API_KEY=your-client-id-here
-# HELPSCOUT_APP_SECRET=your-client-secret-here
+# Alternative variable names (also supported):
+# HELPSCOUT_CLIENT_ID=your-app-id        # OAuth2 standard naming
+# HELPSCOUT_CLIENT_SECRET=your-app-secret
+# HELPSCOUT_API_KEY=your-app-id          # Legacy
 
+# Optional: Default inbox for scoped searches (improves LLM context)
+# Get inbox IDs using the listAllInboxes tool
+# HELPSCOUT_DEFAULT_INBOX_ID=123456
+
+# API Configuration
 HELPSCOUT_BASE_URL=https://api.helpscout.net/v2/
 
-# Optional Configuration
-ALLOW_PII=false
+# Content Redaction
+# Default behavior: message content IS shown (REDACT_MESSAGE_CONTENT=false)
+# Set to true to hide message bodies in responses for privacy/compliance
+REDACT_MESSAGE_CONTENT=false
+
+# Legacy variable (still supported for backwards compatibility):
+# ALLOW_PII=true  # Same effect as REDACT_MESSAGE_CONTENT=false
+
+# Cache Configuration
 CACHE_TTL_SECONDS=300
 MAX_CACHE_SIZE=10000
-LOG_LEVEL=info
+
+# Logging
+LOG_LEVEL=info

.github/workflows/ci.yml

@@ -48,10 +48,23 @@ jobs:
     runs-on: ubuntu-latest
     needs: test
     if: startsWith(github.ref, 'refs/tags/v')
-    
+
     steps:
     - uses: actions/checkout@v4
-    
+      with:
+        fetch-depth: 0
+
+    - name: Verify tag is on main branch
+      env:
+        COMMIT_SHA: ${{ github.sha }}
+      run: |
+        git fetch origin main
+        if ! git merge-base --is-ancestor "$COMMIT_SHA" origin/main; then
+          echo "::error::Docker builds only allowed from tags on main branch. Push tag after merging to main."
+          exit 1
+        fi
+        echo "✅ Tag verified on main branch"
+
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
 

.gitignore

@@ -79,4 +79,8 @@ WORKFLOW.md
 # Development artifacts and results
 test-results/
 benchmark-results/
-perf-reports/
+perf-reports/
+
+# Script state files (may contain sensitive data)
+scripts/.import-progress.json
+scripts/*.state.json

Dockerfile

@@ -55,5 +55,5 @@ ENTRYPOINT ["node", "dist/index.js"]
 # Labels for metadata
 LABEL name="help-scout-mcp-server" \
       description="Help Scout MCP server for searching inboxes, conversations, and threads" \
-      version="1.3.0" \
+      version="1.5.0" \
       maintainer="Drew Burchfield"