@verygoodplugins/mcp-freescout 1.4.0 → 2.0.0

package/.github/dependabot.yml

@@ -0,0 +1,26 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      production-dependencies:
+        patterns:
+          - "*"
+        exclude-patterns:
+          - "@types/*"
+          - "typescript"
+          - "vitest"
+          - "eslint*"
+          - "prettier"
+      dev-dependencies:
+        patterns:
+          - "@types/*"
+          - "typescript"
+          - "vitest"
+          - "eslint*"
+          - "prettier"
+    commit-message:
+      prefix: "chore(deps)"
+    open-pull-requests-limit: 10

package/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Test coverage
+        run: npm run test:coverage
+        continue-on-error: true

package/.github/workflows/release-please.yml

@@ -0,0 +1,102 @@
+# Release Please - Automated versioning and npm publishing
+#
+# How it works:
+# 1. Every push to main with conventional commits updates a "Release PR"
+# 2. When you merge the Release PR, it:
+#    - Updates version in package.json
+#    - Updates CHANGELOG.md
+#    - Creates a GitHub Release with tag
+#    - Triggers the npm publish job below
+#
+# Commit message format:
+#   feat: add new feature          → minor version bump
+#   fix: fix a bug                 → patch version bump
+#   feat!: breaking change         → major version bump
+#   chore/docs: no version bump
+#
+# npm Publishing:
+#   Uses Trusted Publishing (OIDC) - no secrets needed!
+#   Configure at: https://www.npmjs.com/package/@verygoodplugins/mcp-{name}/access
+
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: node
+
+  npm-publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+
+      # Trusted Publishing: No NPM_TOKEN needed!
+      - run: npm publish --access public --provenance
+
+  mcp-registry-publish:
+    needs: [release-please, npm-publish]
+    if: ${{ needs.release-please.outputs.release_created }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mcp-publisher CLI
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz mcp-publisher
+          sudo mv mcp-publisher /usr/local/bin/
+
+      - name: Publish to MCP Registry
+        run: |
+          mcp-publisher login github-oidc
+          mcp-publisher publish
+        env:
+          MCP_REGISTRY_URL: https://registry.modelcontextprotocol.io
+
+  announce:
+    needs: [release-please, npm-publish]
+    if: ${{ needs.release-please.outputs.release_created }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post to Slack
+        if: ${{ vars.SLACK_WEBHOOK_URL }}
+        uses: slackapi/slack-github-action@v1
+        with:
+          webhook-url: ${{ vars.SLACK_WEBHOOK_URL }}
+          webhook-type: incoming-webhook
+          payload: |
+            {
+              "text": "🚀 ${{ github.repository }} ${{ needs.release-please.outputs.tag_name }} released!\n\nhttps://github.com/${{ github.repository }}/releases/tag/${{ needs.release-please.outputs.tag_name }}"
+            }

package/.github/workflows/security.yml

@@ -0,0 +1,53 @@
+name: Security
+
+on:
+  schedule:
+    - cron: "0 0 * * 0" # Weekly on Sunday
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  codeql:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: typescript
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+
+  audit:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - run: npm ci
+
+      - name: Audit dependencies
+        run: npm audit --audit-level=high
+        continue-on-error: true
+
+      - name: Check for known vulnerabilities
+        run: npx better-npm-audit audit --level high
+        continue-on-error: true

package/.prettierignore

@@ -0,0 +1,24 @@
+# Build outputs
+dist/
+build/
+*.js.map
+*.d.ts.map
+
+# Dependencies
+node_modules/
+
+# Lock files
+package-lock.json
+yarn.lock
+
+# Git
+.git/
+
+# IDE
+.vscode/
+.idea/
+
+# Temporary files
+*.log
+.DS_Store
+

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "avoid",
+  "proseWrap": "preserve"
+}

package/AGENTS.md

@@ -1,11 +1,13 @@
 # Repository Guidelines
 
 ## Project Structure & Modules
+
 - **Source**: TypeScript sources live in `src/` (`index.ts`, `freescout-api.ts`, `ticket-analyzer.ts`, `types.ts`).
 - **Build output**: Compiled JavaScript and type declarations are in `dist/` (do not edit directly).
 - **Entry point**: The MCP server CLI entry is `src/index.ts`, built to `dist/index.js` and exposed as `mcp-freescout`.
 
 ## Build, Test & Development
+
 - **Install**: `npm install` – install dependencies.
 - **Dev server**: `npm run dev` – run `src/index.ts` with live reload.
 - **Build**: `npm run build` – compile TypeScript to `dist/`.
@@ -14,23 +16,27 @@
 - **Format**: `npm run format` – apply Prettier formatting to `src/**/*.ts`.
 
 ## Coding Style & Naming
+
 - **Language**: TypeScript with ES modules (`type: module`).
 - **Formatting**: Use Prettier via `npm run format`; 2‑space indentation and single quotes where possible.
 - **Linting**: ESLint with `@typescript-eslint` rules; fix warnings before opening a PR.
 - **Naming**: Use `camelCase` for variables/functions, `PascalCase` for classes/types, and descriptive file names (e.g., `freescout-api.ts`).
 
 ## Testing Guidelines
+
 - **Framework**: Jest (`npm test`).
 - **Location**: Place tests alongside code as `*.test.ts` or in a dedicated test folder if introduced consistently.
 - **Scope**: Cover new behavior, especially FreeScout API calls and ticket analysis logic.
 - **CI readiness**: Ensure `npm test` and `npm run lint` pass locally before pushing.
 
 ## Commit & Pull Requests
+
 - **Commits**: Write clear, imperative messages (e.g., `Add ticket analyzer tests`, `Fix FreeScout auth error`).
 - **Branches**: Use short, descriptive names (e.g., `feat/ticket-tags`, `fix/rate-limits`).
 - **PRs**: Include a concise summary, motivation, testing notes (`npm test`, `npm run lint`), and link related issues. Add screenshots or logs when changing error handling or CLI behavior.
 
 ## Memory MCP Usage
+
 - **Start of work**: Use the memory MCP to recall project-specific context for the area you are modifying (recent bugs, decisions, or related files).
 - **During/after work**: When you fix an issue or learn something important (API behavior, edge case, configuration nuance), store or update a memory via the MCP.
 - **Associations**: When relevant, associate new memories with existing ones (e.g., linking a bugfix to a specific module or decision) to keep context navigable for future tasks.

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-01-05
+
+### Breaking Changes
+
+- **Search API redesign**: Replaced fragile query-string syntax (`assignee:null`) with explicit filter parameters
+  - Old: `query: "assignee:null"`
+  - New: `assignee: "unassigned"` as a dedicated parameter
+- Migrated from legacy `Server` class to modern `McpServer` with `registerTool()` API
+- All tool responses now include structured output schemas for better type safety
+- **Removed Git/GitHub tools**: The following tools have been removed to focus on core FreeScout functionality:
+  - `git_create_worktree`
+  - `git_remove_worktree`
+  - `github_create_pr`
+  - `freescout_implement_ticket`
+  - Use dedicated Git/GitHub MCP servers for these workflows
+
+### Added
+
+- **Markdown-to-HTML conversion**: Draft replies now automatically convert Markdown formatting (bold, italic, code, lists) to proper HTML for FreeScout display
+- **Zod schema validation** for all FreeScout API types with runtime validation
+- **Explicit search filters**:
+  - `assignee`: 'unassigned' | 'any' | number
+  - `updatedSince`: ISO date or relative time (e.g., "7d", "24h")
+  - `createdSince`: ISO date or relative time
+  - `page` and `pageSize`: Proper pagination support
+  - `mailboxId`, `status`, `state`: First-class filter parameters
+- **Exponential backoff retry logic** with jitter for transient API failures
+- **Rate limiting awareness**: Automatic detection and backoff for 429 responses
+- **Timeout handling**: Configurable request timeouts (default: 30s)
+- **Structured content responses**: All tools now return typed `structuredContent` alongside text
+- **Relative time parsing**: Support for "7d", "24h", "30m" in date filters
+
+### Changed
+
+- Updated to MCP SDK best practices (January 2026)
+- Improved error messages with specific status codes and retry information
+- Enhanced type safety with Zod schemas throughout the codebase
+- Better input normalization and validation
+
+### Fixed
+
+- Eliminated client-side filtering workarounds for search state parameter
+- Removed fragile string matching for special query syntax
+- Improved reliability with automatic retries for network errors
+- Windows compatibility: README config examples now use args array format to prevent path separator issues
+
+### Infrastructure
+
+- Added GitHub Actions CI/CD with automated testing and npm publishing
+- Added MCP Registry publishing for discoverability
+- ESLint 9 flat config with typescript-eslint 8
+- Security scanning with CodeQL and Dependabot
+
+### Migration Guide
+
+If you were using `freescout_search_tickets` with query strings like `"assignee:null"`:
+
+**Before (v1.x):**
+
+```json
+{
+  "query": "assignee:null",
+  "status": "active"
+}
+```
+
+**After (v2.0):**
+
+```json
+{
+  "assignee": "unassigned",
+  "status": "active"
+}
+```
+
+For text search, use the `textSearch` parameter:
+
+```json
+{
+  "textSearch": "authentication error",
+  "assignee": "unassigned",
+  "updatedSince": "7d"
+}
+```
+
+## [1.4.2] - 2025-11-20
+
+### Added
+
+- MCP Registry support with `mcpName` configuration
+- GitHub Actions CI/CD workflows
+- Dependabot configuration for dependency updates
+- Security scanning with CodeQL
+
+### Changed
+
+- Updated package.json with `engines` and `publishConfig`
+
+## [1.4.1] - 2025-11-15
+
+### Fixed
+
+- Improved error handling in ticket operations
+
+## [1.4.0] - 2025-11-10
+
+### Added
+
+- Git worktree integration for ticket-based development
+- GitHub PR creation support
+
+## [1.3.0] - 2025-10-15
+
+### Added
+
+- Ticket context retrieval for personalized replies
+- Draft reply creation functionality
+
+## [1.2.0] - 2025-09-20
+
+### Added
+
+- Ticket search functionality
+- Note addition to tickets
+
+## [1.1.0] - 2025-08-15
+
+### Added
+
+- Ticket status updates
+- Ticket assignment
+
+## [1.0.0] - 2025-07-01
+
+### Added
+
+- Initial release
+- FreeScout ticket fetching
+- Ticket analysis with AI
+- Basic ticket operations

package/CLAUDE.md

@@ -0,0 +1,111 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+**MCP FreeScout** is an MCP server for FreeScout helpdesk integration. It enables AI assistants to manage support tickets, analyze issues, create responses, and integrate with Git workflows.
+
+## Build & Development
+
+```bash
+# Build TypeScript to dist/
+npm run build
+
+# Development with hot-reload
+npm run dev
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Architecture
+
+```
+src/
+├── index.ts              # MCP server entry point, tool registration
+├── freescout-api.ts      # FreeScout API client
+├── ticket-analyzer.ts    # AI-powered ticket analysis
+├── git-integration.ts    # Git worktree and GitHub PR support
+└── types.ts              # TypeScript interfaces
+```
+
+## MCP Tools
+
+The server exposes these tools:
+
+### Ticket Management
+
+- **freescout_get_ticket** - Fetch ticket by ID or URL with threads
+- **freescout_analyze_ticket** - Analyze ticket to determine issue type and solution
+- **freescout_add_note** - Add internal note to ticket
+- **freescout_update_ticket** - Update ticket status and assignment
+- **freescout_create_draft_reply** - Create draft reply for review
+- **freescout_get_ticket_context** - Get ticket context for personalized replies
+- **freescout_search_tickets** - Search tickets by query and filters
+
+### Git Integration
+
+- **git_create_worktree** - Create Git worktree for ticket work
+- **git_remove_worktree** - Remove worktree after completion
+- **github_create_pr** - Create GitHub PR for ticket branch
+
+### Workflow
+
+- **freescout_implement_ticket** - Full workflow: analyze, worktree, plan
+
+## Environment Variables
+
+```env
+# Required: FreeScout instance URL
+FREESCOUT_URL=https://your-freescout.example.com
+
+# Required: FreeScout API key
+FREESCOUT_API_KEY=your_api_key
+
+# Optional: Default user ID for notes/drafts
+FREESCOUT_USER_ID=1
+
+# Optional: Git worktree base path
+WORKTREE_BASE_PATH=/path/to/worktrees
+
+# Optional: GitHub token for PR creation
+GITHUB_TOKEN=ghp_xxxx
+```
+
+## Common Tasks
+
+**Add a new tool:**
+
+1. Define tool schema in `src/index.ts` tools array
+2. Add handler in `CallToolRequestSchema` switch
+3. Implement API method in `freescout-api.ts`
+4. Add types in `types.ts`
+
+**Test a specific tool:**
+
+```bash
+echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"freescout_get_ticket","arguments":{"ticket":"12345"}},"id":1}' | npm start
+```
+
+## API Patterns
+
+The FreeScout API client uses:
+
+- Basic authentication with API key
+- JSON request/response format
+- Pagination for list endpoints
+- Status codes: active, pending, closed, spam
+
+## Important Notes
+
+- Ticket IDs can be provided as number, string, or full URL
+- Thread content is HTML, cleaned with DOMPurify before display
+- Draft replies require user review before sending
+- Worktrees are created in `./worktrees/` by default