feat: excludeDrafts param for getThreads (v2.2.1)

[zackkatz]

Summary

• Add excludeDrafts parameter to getThreads (default: true) — filters AI-generated drafts (source.type: "support-agent-ai") and unsent drafts (state: "draft") from results
• Add support-agent-ai filter to buildTranscript (inline transcripts via searchConversations)
• Include draftsExcluded: true flag in all three output formats (transcript, verbose, slim)
• Set excludeDrafts: false to include all threads including AI drafts

Why: Help Scout assigns AI drafts to the mailbox owner's name in createdBy, causing AI agents to falsely attribute them as real staff replies.

Test plan

• Verify getThreads with default params excludes AI drafts and unsent drafts
• Verify getThreads with excludeDrafts: false returns all threads
• Verify transcript format excludes drafts
• Verify inline transcripts via searchConversations exclude drafts
• Build succeeds: npm run build

Summary by CodeRabbit

• New Features

  • Conversation management: create, retrieve, and update conversations (assignees, tags, custom fields).
  • Reply creation: draft or published replies with HTML formatting and configurable spacing; option to exclude AI drafts from thread results.
  • New tools/endpoints to manage replies and conversations.

• Documentation

  • Updated README with examples and new Reply/Conversation sections.
  • Added comprehensive Help Scout API reference.

• Chores

  • Package version bump and added multipart/form-data support dependency.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1eba088 and 16c47fb.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (2)

• package.json
• src/__tests__/tools.test.ts

---

Walkthrough

Adds four new Help Scout tools (createReply, getConversation, createConversation, updateConversation), new input schemas and validations, client methods for POST/PATCH/PUT and multipart uploads, config flags for reply spacing and publish permission, docs updates, and expanded tests.

Changes

Cohort / File(s)	Summary
Configuration & Env /.env.example, helpscout-mcp-extension/manifest.json, src/utils/config.ts	Add HELPSCOUT_REPLY_SPACING and HELPSCOUT_ALLOW_SEND_REPLY; expose config.helpscout.replySpacing and config.helpscout.allowSendReply; manifest and user_config updated.
New Tools & Router src/tools/index.ts	Add createReply, getConversation, createConversation, updateConversation implementations and dispatch cases; add formatReplyHtml and excludeDrafts handling for threads.
Schemas & Validation src/schema/types.ts, src/utils/api-constraints.ts	Add CreateReply/GetConversation/CreateConversation/UpdateConversation input schemas and types; extend GetThreadsInputSchema with excludeDrafts; add validators for the new tools and guidance messages.
API Clients & Uploads src/utils/helpscout-client.ts, src/utils/helpscout-docs-client.ts, package.json	Add postWithResponse, patch, put to HelpScoutClient; add getApiKey and postFormData (uses form-data) to Docs client; add form-data dependency.
Docs & Reference README.md, docs/help-scout-api-reference.md	Expand README with reply/conversation examples and config notes; add large Help Scout API reference doc.
Docs Tools & Assets src/tools/docs-tools.ts	Introduce stripCdata, change asset upload signatures to article-based and settings endpoints, switch to multipart/form-data uploads via FormData and createReadStream.
Tests & Manifest Validation src/__tests__/tools.test.ts, src/__tests__/mcpb-validation.test.ts	Add extensive tests for new tools, HTML formatting, transcripts, and config-driven behavior; update manifest-tools count to include new tools.
Extension Manifest helpscout-mcp-extension/manifest.json	Expose new tools and user_config fields; add server env entries for new vars; update descriptions to reflect draft/published reply behavior.

Sequence Diagram(s)

sequenceDiagram
  participant User as Client
  participant TH as ToolHandler
  participant CFG as Config
  participant HS as HelpScoutClient
  participant API as HelpScout API

  User->>TH: call createReply(args)
  TH->>CFG: read replySpacing & allowSendReply
  TH->>TH: formatReplyHtml(args.html, replySpacing)
  TH->>HS: postWithResponse("/conversations/{id}/threads", {type: "reply", ...})
  HS->>API: POST /conversations/{id}/threads
  API-->>HS: 201 Created (thread/draft id)
  HS-->>TH: {status, headers, data}
  TH->>TH: if published -> patch conversation status (guarded by allowSendReply)
  TH-->>User: return created reply metadata (draft/published)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately and clearly describes the main feature: adding an excludeDrafts parameter to the getThreads function with versioning.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch develop

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}