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.

Related MCP server: Freshservice MCP Server

🛠 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.

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

📁 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

📚 Knowledge Base & Problems

📦 Assets & Software

?? Service Catalog & Responses

👤 Identity & History

📖 Available Resources (Standing Context)

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

🪄 Available Prompts (Workflows)

🔍 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
  },
}

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

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.