mirror of
https://gh.wpcy.net/https://github.com/verygoodplugins/mcp-freescout.git
synced 2026-07-15 19:17:34 +08:00
dc0b649f63
Major update with breaking changes: FreeScout search API now uses explicit filter parameters instead of query-string syntax, and Git/GitHub tools have been removed. Migrated to MCP SDK 1.25+ with modern McpServer and registerTool() patterns, added Zod schema validation, structured outputs, exponential backoff retry logic, and improved reliability. Includes new test suite, Jest config, and documentation updates for v2.0 features and migration guidance.
111 lines
2.9 KiB
Markdown
111 lines
2.9 KiB
Markdown
# 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
|
