FS_MCP_thin

FS_MCP_thin 🚀

 

A powerful, read-only Model Context Protocol (MCP) server that bridges the gap between your AI assistant (like Claude) and your Freshservice Service Desk. Empower your AI with deep context to triage incidents, analyze asset distribution, and summarize support history.

---

✨ Features

• 🎫 Ticket Intelligence – Deep dive into tickets, conversations, private notes, and service request items.
• 📚 Knowledge Integration – Search and retrieve the full content of your solution articles.
• 🔧 Problem Analysis – Inspect root-cause investigation records.
• 📦 Inventory Visibility – Browse and drill down into Assets (Hardware) and Software inventory.
• 👤 Identity Context – Lookup Requesters and Agents, and view their specific ticket/asset history.
• ⏱️ Governance Context – Access SLA policies, business hours, and org structure as standing context.
• 💬 Canned Success – Use your curated response templates to draft high-quality replies.
• 🪶 Token-Efficient – Responses are shaped (field-projected, HTML-stripped, compacted) before they reach the model, cutting context bloat 5-10x on list/detail calls. See Response Shaping.

---

🛠 Prerequisites

• Node.js: Version 18.x or higher.
• Freshservice: An active account with API access enabled.
• API Key: Found in your Profile Settings → API Key.

---

🚀 Quick Start

1. Installation

# Clone or download the repository
cd FS_MCP_thin

# Install dependencies
npm install

# Setup environment variables
cp .env.example .env

2. Configuration

The server needs exactly two environment variables. Both are required — if either is missing the server exits immediately on startup with an error.

| Variable | What it is | Where to get it | |----------|-----------|-----------------| | FRESHSERVICE_DOMAIN | Your Freshservice URL | The host in your browser, e.g. acme.freshservice.com. | | FRESHSERVICE_API_KEY | Your personal API key | Freshservice → avatar → Profile Settings → API Key (right sidebar). |

Domain format: supply just the host (acme.freshservice.com). A full URL (https://acme.freshservice.com) also works — the client adds https:// only if no protocol is present. Do not include a trailing slash or path.

How auth works: Freshservice uses HTTP Basic auth with the API key as the username and a dummy password. The server handles this for you — you only ever supply the raw key.

Edit the .env file with your details:

FRESHSERVICE_DOMAIN=acme.freshservice.com
FRESHSERVICE_API_KEY=your_api_key_here

.env is git-ignored. Your credentials never leave your machine — see Security & Privacy.

3. Integration with Claude Desktop

Add this snippet to your claude_desktop_config.json. The env block here is an alternative to a .env file — when Claude Desktop launches the server it injects these, so you don't need both. (If both exist, the values in env take precedence.)

{
  "mcpServers": {
    "freshservice": {
      "command": "node",
      "args": ["C:\\path\\to\\FS_MCP_thin\\src\\index.js"],
      "env": {
        "FRESHSERVICE_DOMAIN": "acme.freshservice.com",
        "FRESHSERVICE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Use the absolute path to src/index.js. On Windows, escape backslashes (\\) as shown.

Troubleshooting credentials

| Symptom | Likely cause | |---------|--------------| | Server exits with FRESHSERVICE_DOMAIN and FRESHSERVICE_API_KEY ... are required | One or both env vars are unset (typo, wrong key name, or .env not loaded). | | 401 Unauthorized on every call | API key is wrong, revoked, or copied with surrounding whitespace. | | 403 Forbidden on specific tools (assets, problems, catalog) | Your account's role or plan tier doesn't grant access to that resource — not a config bug. | | 404 Not Found | Wrong domain, or the record ID doesn't exist. | | 429 Too Many Requests | Rate limit hit. Limits are per-plan; the server surfaces the error but does not auto-retry. |

---

📁 Project Structure

FS_MCP_thin/
├── src/
│   ├── index.js              # MCP server entry point — registers all tools,
│   │                         #   resources, and prompts; wires responses through shape.js
│   ├── freshservice.js       # FreshserviceClient — thin axios wrapper over the
│   │                         #   Freshservice v2 REST API (auth, requests, error mapping)
│   ├── shape.js              # Token-economy engine — projects/strips/compacts responses
│   ├── shape.config.js       # Declarative per-domain field/shaping rules (edit this to tune output)
│   ├── index.test.js         # Tests for tool registration & handler behavior
│   ├── freshservice.test.js  # Tests for the API client
│   └── shape.test.js         # Tests for the shaping engine + config
├── eslint.config.js          # ESLint flat config (Node + Jest, recommended rules)
├── tsconfig.json             # TypeScript config for `checkJs` type-checking
├── .env.example              # Template for required environment variables
├── .gitignore                # Ignores node_modules/ and .env (credentials)
├── package.json              # Dependencies, scripts, bin entry
└── README.md

Data flow: index.js (MCP request) → freshservice.js (API call) → shape.js + shape.config.js (trim response) → back to the AI assistant.

Where to make changes:

• Add/modify a tool, resource, or prompt → src/index.js
• Add/modify a Freshservice API call → src/freshservice.js
• Change what fields the model sees → src/shape.config.js (no code changes needed)

---

🧰 Available Tools

🎫 Tickets & Conversations

| Tool | Purpose | |------|---------| | search_tickets | Flexible search using status, priority, or subject. | | list_open_tickets | List open tickets (status:2) with pagination. | | get_ticket | Curated detail view of a ticket (key fields + HTML-stripped body). | | get_ticket_conversations | Complete thread of public and private messages. | | get_ticket_notes | Isolates private internal notes for audit/context. | | get_service_request_items| Views quantity and custom fields for SR items. |

📚 Knowledge Base & Problems

| Tool | Purpose | |------|---------| | search_kb | Find articles by keywords. | | get_kb_article | Retrieve the full article body (Markdown/HTML). | | list_problems | Get a list of recent Problem records. | | get_problem | Detailed view of a root cause investigation. |

📦 Assets & Software

| Tool | Purpose | |------|---------| | list_assets | Browse the CI (Configuration Item) inventory. | | get_asset | Deep dive into a specific piece of hardware. | | list_software | See software installations and licenses. |

?? Service Catalog & Responses

| Tool | Purpose | |------|---------| | list_service_catalog_items | List items available in the service catalog. | | get_service_catalog_item | Retrieve details of a specific service catalog item. | | list_canned_responses | List canned response templates. |

👤 Identity & History

| Tool | Purpose | |------|---------| | search_requesters | Find users by name or email. | | get_requester | Detailed profile of a user. | | get_requester_tickets | Historical view of all tickets for a specific user. | | get_requester_assets | List of hardware currently assigned to a user. | | search_agents | Find support staff members. | | get_agent / get_agent_group| Inspect specific agents or support teams. |

---

📖 Available Resources (Standing Context)

Resources can be attached to a conversation to provide the AI with constant reference data without needing a tool call.

| URI | Content | |-----|---------| | freshservice://departments | Your organizational hierarchy. | | freshservice://ticket-fields | The schema for custom ticket fields and their values. | | freshservice://agent-groups | Valid routing destinations (support teams). | | freshservice://sla-policies | Your response and resolution time targets. | | freshservice://business-hours | Operation schedules for various teams. |

---

🪄 Available Prompts (Workflows)

| Prompt | Scenario | |--------|----------| | triage_ticket | Input: Ticket ID. Output: A comprehensive assessment including history, SR items, and suggested KB articles. | | summarize_ticket | Input: Ticket ID. Output: A concise executive summary perfect for handoffs or manager reviews. | | draft_reply | Input: Ticket ID. Output: A professional draft reply incorporating KB solutions and empathy. | | sla_check | Input: Ticket ID. Output: An analysis of breach risk based on business hours and policies. |

---

🔍 Search Syntax Reference

The search_tickets tool supports the Freshservice Filter API syntax:

• Status Codes: 2: Open, 3: Pending, 4: Resolved, 5: Closed.
• Priority Codes: 1: Low, 2: Medium, 3: High, 4: Urgent.

Examples for AI:

• "status:2 AND priority:4" → Show me urgent open tickets.
• "created_at:>'2024-01-01'" → Show me tickets from this year.
• "type:'Incident'" → Filter for incidents only.

---

🪶 Response Shaping (Token Economy)

Freshservice API responses are verbose — a single ticket carries 40-60 fields (many null), HTML bodies, and internal metadata the model never needs. To avoid bloating the AI's context window, tool and resource responses pass through a shaping layer before they're returned. Most are field-projected and HTML-stripped; a few (e.g. service-request items, whose custom_fields hold the request's actual answers) are compacted but deliberately kept whole.

What it does:

• Compact JSON – no pretty-print whitespace (~15-30% saving on every call).
• Field projection – list/search tools return lean summary rows (e.g. a ticket → id, subject, status, priority, requester_id, group_id, timestamps); detail tools (get_ticket, get_asset, …) return a curated, richer set.
• HTML stripping – descriptions, conversation bodies, and articles are converted from HTML to plain text (description → description_text), then truncated if very long.
• Noise removal – null/empty fields and empty custom-field entries are dropped; attachments are reduced to filenames.
• Defensive fallback – if a response doesn't match the expected shape, it passes through compacted but otherwise untouched (never mangled).

Summary-then-drill-down: list tools intentionally return summaries. When the model needs everything about one record, it calls the matching get_* tool. This keeps broad queries cheap.

Tuning what the model sees

All shaping rules are declarative and live in one file — src/shape.config.js. The engine (src/shape.js) contains no per-domain logic, so adjusting output requires no code changes.

Each domain defines a list (summary) and/or detail profile:

tickets: {
  container: 'tickets',   // array key for list responses
  item: 'ticket',         // object key for single-record responses
  list:   { fields: ['id', 'subject', 'status', 'priority', /* … */] },
  detail: {
    fields:  ['id', 'subject', 'status', /* …more… */],
    text:    [{ from: ['description_text', 'description'], to: 'description_text', max: 2000 }],
    objects: ['custom_fields'],   // kept, but null/empty entries dropped
  },
}

| Profile key | Effect | |-------------|--------| | fields | Whitelist of keys to keep (present + non-empty only). | | text | Take the first available from field, strip HTML, truncate to max, store under to. | | objects | Custom-field-style objects to keep but compact (drop null/empty). | | names | Reduce an array of { name, … } objects to an array of names (e.g. attachments). |

To add a field to a tool's output, append it to that domain's fields array. To expose more/less body text, change max. That's the whole workflow.

Note: the field names in shape.config.js are mapped to the Freshservice v2 API. If your instance relies on a field that isn't surfaced, add it to the relevant fields array — it's a one-line change.

---

⚡ Performance & Reliability

The Freshservice client (src/freshservice.js) includes several measures to stay fast and resilient under real-world conditions:

• Request timeout – every request times out after 10s rather than hanging indefinitely on a stalled connection.
• Automatic retry with backoff – transient failures (429 rate limits, 5xx, network/timeout errors) are retried up to 3 times with exponential backoff. A 429's Retry-After header is honored when present. Non-transient errors (401, 403, 404) are not retried.
• Caching of static data – near-static reference endpoints (departments, ticket/requester fields, SLA policies, business hours, agent groups) are cached in memory for 10 minutes, so the AI's repeated context-gathering doesn't re-hit the API. Failed lookups are never cached.
• Concurrent pagination – tools that aggregate every page (list_canned_responses, list_service_catalog_items) fetch page 1, then pull the remaining pages in bounded-concurrency batches (per_page=100, 5 pages at a time) instead of one slow page at a time — turning ~10 sequential round-trips into 2-3 parallel batches.

These are tuned by constants at the top of src/freshservice.js (STATIC_TTL_MS, REQUEST_TIMEOUT_MS, MAX_RETRIES).

---

🧪 Development

| Command | What it does | |---------|--------------| | npm start | Run the MCP server on stdio. | | npm test | Run the Jest test suite. | | npm run lint | Lint with ESLint (flat config, eslint:recommended + Node/Jest globals). | | npm run lint:fix | Lint and auto-fix where possible. | | npm run typecheck | Type-check the JS via TypeScript in checkJs mode (no emit). | | npm run check | Run lint + typecheck + tests together (use before committing). |

Type-checking uses TypeScript's checkJs against the application code (tsconfig.json). It catches real errors — e.g. wrong API shapes or SDK misuse — without requiring the code to be migrated to TypeScript. Test files are excluded from tsc (their Jest mocks are validated by the test runner, not the type-checker). Implicit-any is allowed, so the checker surfaces genuine type errors rather than annotation noise.

---

🔒 Security & Privacy

1. Read-Only: This server has NO capability to create, edit, or delete data. It is inherently safe.
2. Local Only: Credentials NEVER leave your machine.
3. Auditability: All API requests are standard HTTPS and appear in your Freshservice API logs.

📄 License

ISC License. Build with freedom.