fix: date filter and status defaults for v1.6.2

- Replace modifiedSince with createdAt query syntax for accurate creation date filtering
- Add appendCreatedAtFilter helper with ISO 8601 validation and ms stripping
- Fix advancedConversationSearch to default to status=all
- Fix structuredConversationFilter to send status=all for ticket lookups
- Update tests for new query format and version

Author: drewburchfield

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.6.1" \
+      version="1.6.2" \
       maintainer="Drew Burchfield"

README.md

@@ -9,45 +9,32 @@
 
 ## Table of Contents
 
-- [What's New](#whats-new-in-v161)
+- [What's New](#whats-new-in-v162)
 - [Quick Start](#quick-start)
 - [API Credentials](#getting-your-api-credentials)
 - [Tools & Capabilities](#tools--capabilities)
 - [Configuration](#configuration-options)
 - [Troubleshooting](#troubleshooting)
 - [Contributing](#contributing)
 
-## What's New in v1.6.1
+## What's New in v1.6.2
 
-- **Pagination Bug Fix**: Multi-status searches now report accurate total counts. Previously, searching without a status filter (active/pending/closed in parallel) reported `totalResults` capped at the page limit instead of the real total across all statuses. Now returns `totalAvailable` (sum of API totals) and `totalByStatus` breakdown. ([#10](https://github.com/drewburchfield/help-scout-mcp-server/issues/10))
-- **Client-Side Date Filtering**: New `createdBefore` parameter for all search tools with clear metadata distinguishing filtered counts from API totals
-- **Partial Failure Transparency**: Multi-status searches now surface structured error info when individual status queries fail, instead of silently returning incomplete results
-- **Stronger Error Type Guard**: `isApiError` now validates against the schema enum, preventing false matches on Node.js system errors
+- **Date Filter Fix**: `createdAfter` and `timeframeDays` now correctly filter by conversation creation date instead of last modification date. Previously, all search tools mapped `createdAfter` to Help Scout's `modifiedSince` API parameter, silently excluding conversations that were created within the timeframe but not recently modified. Now uses Help Scout query syntax `createdAt:[date TO *]` for accurate creation-date filtering.
+- **Multi-Status Search Consistency**: `advancedConversationSearch` and `structuredConversationFilter` now search all statuses (active, pending, closed) by default, matching the behavior established in v1.6.0 for `searchConversations`. Previously, omitting the status parameter silently returned only active conversations.
+- **Ticket Number Lookup Fix**: `structuredConversationFilter` with `conversationNumber` now finds conversations regardless of status. Previously, looking up a closed ticket by number returned empty results.
+
+### Previous Release (v1.6.1)
+
+- **Pagination Bug Fix**: Multi-status searches now report accurate total counts with `totalAvailable` and `totalByStatus` breakdown ([#10](https://github.com/drewburchfield/help-scout-mcp-server/issues/10))
+- **Client-Side Date Filtering**: New `createdBefore` parameter for all search tools
+- **Partial Failure Transparency**: Multi-status searches surface structured error info when individual status queries fail
 - **Dependency Security Fixes**: Upgraded `@modelcontextprotocol/sdk` to 1.26.0, fixed axios, hono, and qs vulnerabilities
 
 ### Previous Release (v1.6.0)
 
 - **Inbox Auto-Discovery**: Inboxes automatically discovered on server connect and included in server instructions
-- **Multi-Status Search Default**: `searchConversations` now searches all statuses (active, pending, closed) by default when no status specified
+- **Multi-Status Search Default**: `searchConversations` searches all statuses (active, pending, closed) by default when no status specified
 - **Simpler Workflow**: AI agents can use inbox IDs directly from server instructions without a preliminary lookup step
-- **Deprecated Tools**: `searchInboxes` and `listAllInboxes` remain functional but are deprecated (inboxes now in instructions)
-
-### Previous Release (v1.5.0)
-
-- MCP SDK with enhanced compatibility
-- `structuredConversationFilter` for ID-based refinement and ticket number lookup
-- Enhanced input validation and error handling
-- Standardized environment variable naming (`APP_ID`/`APP_SECRET`)
-
-### Migration from v1.5.0
-
-**For programmatic users:**
-- `HelpScoutMCPServer` now uses an async factory pattern: use `await HelpScoutMCPServer.create()` instead of `new HelpScoutMCPServer()`
-
-**Response format change:**
-- `searchConversations` response now includes `statusesSearched` array instead of `status` string when searching without a specific status filter
-
-**No action required for most users** - the MCP protocol interface remains unchanged.
 
 ## Prerequisites
 

helpscout-mcp-extension/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "help-scout-mcp-server",
   "display_name": "Help Scout MCP Server",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "Connect Claude and other AI assistants to your Help Scout data with enterprise-grade security and advanced search capabilities.",
   "long_description": "Connect your AI assistant to Help Scout for intelligent customer support analysis.\n\n**Search & Analysis:**\n• Advanced conversation search with query syntax\n• Multi-status search across active, pending, and closed\n• Boolean queries with content and subject filtering\n• Conversation summaries and full thread retrieval\n• Direct ticket lookup by number\n\n**Enterprise Security:**\n• OAuth2 Client Credentials authentication\n• Optional content redaction for privacy\n• Built-in caching and rate limiting\n• Automatic retry with exponential backoff",
   "author": {

mcp.json

@@ -1,7 +1,7 @@
 {
   "name": "helpscout-search",
   "description": "Search-capable MCP server for Help Scout inboxes, conversations, and threads.",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "mcpVersion": "1.17.4",
   "resources": [
     "helpscout://inboxes",

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "help-scout-mcp-server",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "The first MCP server for Help Scout - search conversations, threads, and inboxes with AI agents",
   "main": "dist/index.js",
   "type": "module",

package.json

@@ -98,7 +98,7 @@ describe('HelpScoutMCPServer - THE ACTUAL APPLICATION', () => {
       expect(Server).toHaveBeenCalledWith(
         {
           name: 'helpscout-search',
-          version: '1.6.1',
+          version: '1.6.2',
         },
         expect.objectContaining({
           capabilities: {

src/__tests__/index.test.ts

@@ -207,27 +207,34 @@ describe('Complete User Workflows - Integration Tests', () => {
       };
 
       // Set up nock interceptors for each status
+      // Query now includes createdAt range from timeframeDays (fix for modifiedSince mismatch)
       nock(baseURL)
         .get('/conversations')
-        .query(params => 
-          params.status === 'active' && 
-          params.query === '(body:"billing" OR subject:"billing")'
+        .query(params =>
+          params.status === 'active' &&
+          typeof params.query === 'string' &&
+          params.query.includes('body:"billing"') &&
+          params.query.includes('createdAt:')
         )
         .reply(200, mockActiveConversations);
 
       nock(baseURL)
         .get('/conversations')
-        .query(params => 
-          params.status === 'pending' && 
-          params.query === '(body:"billing" OR subject:"billing")'
+        .query(params =>
+          params.status === 'pending' &&
+          typeof params.query === 'string' &&
+          params.query.includes('body:"billing"') &&
+          params.query.includes('createdAt:')
         )
         .reply(200, mockPendingConversations);
 
       nock(baseURL)
         .get('/conversations')
-        .query(params => 
-          params.status === 'closed' && 
-          params.query === '(body:"billing" OR subject:"billing")'
+        .query(params =>
+          params.status === 'closed' &&
+          typeof params.query === 'string' &&
+          params.query.includes('body:"billing"') &&
+          params.query.includes('createdAt:')
         )
         .reply(200, mockClosedConversations);
 

src/__tests__/integration.test.ts

@@ -30,7 +30,7 @@ export class HelpScoutMCPServer {
     this.server = new Server(
       {
         name: 'helpscout-search',
-        version: '1.6.1',
+        version: '1.6.2',
       },
       {
         capabilities: {

src/index.ts

@@ -74,6 +74,37 @@ export class ToolHandler {
     return term.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
   }
 
+  /**
+   * Append a createdAt date range to an existing Help Scout query string.
+   * Help Scout has no native createdAfter/createdBefore URL params, so we
+   * use query syntax: (createdAt:[start TO end]).
+   */
+  private appendCreatedAtFilter(
+    existingQuery: string | undefined,
+    createdAfter?: string,
+    createdBefore?: string
+  ): string | undefined {
+    if (!createdAfter && !createdBefore) return existingQuery;
+
+    // Validate date format to prevent query injection and match Help Scout expectations
+    const isoDatePattern = /^\d{4}-\d{2}-\d{2}(T[\d:.]+Z?)?$/;
+    if (createdAfter && !isoDatePattern.test(createdAfter)) {
+      throw new Error(`Invalid createdAfter date format: ${createdAfter}. Expected ISO 8601 (e.g., 2024-01-15T00:00:00Z)`);
+    }
+    if (createdBefore && !isoDatePattern.test(createdBefore)) {
+      throw new Error(`Invalid createdBefore date format: ${createdBefore}. Expected ISO 8601 (e.g., 2024-01-15T00:00:00Z)`);
+    }
+
+    // Strip milliseconds (Help Scout rejects .xxx format)
+    const normalize = (d: string) => d.replace(/\.\d{3}Z$/, 'Z');
+    const start = createdAfter ? normalize(createdAfter) : '*';
+    const end = createdBefore ? normalize(createdBefore) : '*';
+    const clause = `(createdAt:[${start} TO ${end}])`;
+
+    if (!existingQuery) return clause;
+    return `(${existingQuery}) AND ${clause}`;
+  }
+
   /**
    * Set the current user query for context-aware validation
    */
@@ -566,7 +597,12 @@ export class ToolHandler {
     }
 
     if (input.tag) baseParams.tag = input.tag;
-    if (input.createdAfter) baseParams.modifiedSince = input.createdAfter;
+
+    const queryWithDate = this.appendCreatedAtFilter(
+      baseParams.query as string | undefined,
+      input.createdAfter
+    );
+    if (queryWithDate) baseParams.query = queryWithDate;
 
     let conversations: Conversation[] = [];
     let searchedStatuses: string[];
@@ -968,8 +1004,14 @@ export class ToolHandler {
       queryParams.mailbox = effectiveInboxId;
     }
 
-    if (input.status) queryParams.status = input.status;
-    if (input.createdAfter) queryParams.modifiedSince = input.createdAfter;
+    // Default to all statuses for consistency with searchConversations (v1.6.0+)
+    queryParams.status = input.status || 'all';
+
+    const queryWithDate = this.appendCreatedAtFilter(
+      queryParams.query as string | undefined,
+      input.createdAfter
+    );
+    if (queryWithDate) queryParams.query = queryWithDate;
 
     const response = await helpScoutClient.get<PaginatedResponse<Conversation>>('/conversations', queryParams);
 
@@ -1232,14 +1274,18 @@ export class ToolHandler {
     inboxId?: string;
     createdBefore?: string;
   }) {
+    const queryWithDate = this.appendCreatedAtFilter(
+      params.searchQuery,
+      params.createdAfter
+    );
+
     const queryParams: Record<string, unknown> = {
       page: 1,
       size: params.limitPerStatus,
       sortField: TOOL_CONSTANTS.DEFAULT_SORT_FIELD,
       sortOrder: TOOL_CONSTANTS.DEFAULT_SORT_ORDER,
-      query: params.searchQuery,
+      query: queryWithDate || params.searchQuery,
       status: params.status,
-      modifiedSince: params.createdAfter,
     };
 
     if (params.inboxId) {
@@ -1345,11 +1391,17 @@ export class ToolHandler {
     // Apply combination filters
     const effectiveInboxId = input.inboxId || config.helpscout.defaultInboxId;
     if (effectiveInboxId) queryParams.mailbox = effectiveInboxId;
-    if (input.status && input.status !== 'all') queryParams.status = input.status;
+    // Send status=all explicitly (Help Scout defaults to active-only when omitted)
+    queryParams.status = input.status || 'all';
     if (input.tag) queryParams.tag = input.tag;
-    if (input.createdAfter) queryParams.modifiedSince = input.createdAfter;
     if (input.modifiedSince) queryParams.modifiedSince = input.modifiedSince;
 
+    const queryWithDate = this.appendCreatedAtFilter(
+      queryParams.query as string | undefined,
+      input.createdAfter
+    );
+    if (queryWithDate) queryParams.query = queryWithDate;
+
     const response = await helpScoutClient.get<PaginatedResponse<Conversation>>('/conversations', queryParams);
     let conversations = response._embedded?.conversations || [];