mcp-freshservice 2.0.0__tar.gz

mcp_freshservice-2.0.0/.gitignore

@@ -0,0 +1,174 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

mcp_freshservice-2.0.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## 2.0.0
+
+Published as **`mcp-freshservice`** (was `freshservice-mcp`); run it with `uvx mcp-freshservice`.
+
+### Fixed
+- `get_ticket_by_id` returned a pydantic output-validation error instead of the ticket.
+  Single-record tools now return their `{"ticket": {...}}` payload with a proper output schema, and
+  `include=` (conversations, requester, stats, …) is supported.
+- Tools that returned an error *string* from a `dict`-typed function and the `${…}` typo in
+  those messages. Every failure is now a tool error with Freshservice's description and field errors.
+- `send_ticket_reply` no longer sends a made-up `from_email` that Freshservice rejected with 400.
+- Wrong ticket source IDs (Chat was 7, is 4) and missing ones (Chatbot, Workplace, Alerts, MS Teams, …).
+- Change approvals used paths that don't exist (`approval_groups`, `approval_chain`, `resend_approval`);
+  they now use `approval-groups`, `approval-chain-rule` and `approvals/{id}/remind`.
+- Docs/examples that treated `:<` as strict (e.g. `status:<6` for "not closed" changes). `:>`/`:<` are inclusive,
+  confirmed against a live account, so "not closed" is `status:<5`.
+- Knowledge-base search and folder listings return a short `snippet` instead of every article's full HTML and
+  text body (Freshservice sends full bodies for all 30 results, which is large enough for clients to truncate);
+  pass `include_body=true` for the full text or read one article with `get_solution_article`.
+- Change `query` and `view` can't be combined (the API rejects it); the server says so up front.
+- Filter syntax checked against the official docs: `:>`/`:<` are documented as inclusive; query length limit
+  (512) enforced locally; filter endpoints no longer send `per_page` (fixed 30); page caps (40) for
+  requester/agent filters; queries are percent-encoded as in the docs; departments/locations/asset-search/
+  release filters describe only their documented fields. Releases take the documented `filter_name` values
+  only (there is no free-form release query).
+- `filter_requesters` now quotes its query like the other filters (the API requires it); all filters use one code path.
+
+### Added
+- Ticket, change, problem and release time entries, tasks and notes; ticket approvals,
+  child tickets, restore, activities, ticket sources.
+- Problems, releases, assets and asset types, departments, locations, vendors, roles, service catalog
+  search, solution search and sub-folders, requester-group member removal, agent/requester deactivate and
+  reactivate.
+- Attachments on replies, notes and tickets; `private` flag on notes; `group_id` /
+  `responder_id` on `create_ticket`.
+- `FRESHSERVICE_WORKSPACE_ID` default workspace, `FRESHSERVICE_READ_ONLY`,
+  `FRESHSERVICE_TOOLSETS`, streamable-HTTP/SSE transports, `--version`.
+- Read-only / destructive / idempotent annotations on every tool, titles, typed and described parameters.
+
+### Changed (breaking)
+- **Only a core set of 76 tools is enabled by default** (tickets, ticket time entries, requesters, agents,
+  groups, solutions, service catalog). Everything else is opt-in: `--toolsets default,changes,assets` or
+  `--toolsets all`; `--list-toolsets` shows the options. Notes, tasks, time entries and approvals for each
+  record type are separate toolsets (e.g. `change_notes`).
+- Requires `mcp>=1.30,<2` (MCP SDK v1 line); still Python 3.13+.
+- Package/module renamed `freshservice_mcp` → `mcp_freshservice`; console script `mcp-freshservice`.
+- `server.py` split into `client.py`, `config.py` and `tools/<area>.py`.
+- Renamed tools: `get_requester_id` → `get_requester`, `getAgentGroupById` → `get_agent_group`,
+  `get_requester_groups_by_id` → `get_requester_group`, `get_products_by_id` → `get_product`,
+  `get_change_tasks` → `list_change_tasks`, `update_approval_chain_rule_change` →
+  `update_change_approval_chain_rule`.
+- Renamed parameters: generic `id` arguments are now explicit (`product_id`, `requester_group_id`,
+  `canned_response_id`, `workspace_id`, `folder_id`, `category_id`); `get_list_of_solution_folder` takes
+  `category_id` and `get_list_of_solution_article` takes `folder_id`.
+- `update_agent`, `update_requester`, `update_group` and `update_*_task` take a fields object; `update_product`
+  and `update_solution_category` no longer require every field.
+- `list_canned_response_folder` now lists the responses *in* a folder (`/canned_response_folders/{id}/canned_responses`).
+- List tools return the API's own wrapper once (`{"tickets": [...]}`, not nested twice) plus
+  `pagination: {page, per_page, next_page, has_more}`; `current_page`/`prev_page` are gone.
+  `list_service_items` returns one page instead of fetching every page; `filter_agents` returns one page.
+- `send_ticket_reply` takes lists for `cc_emails`/`bcc_emails` (JSON strings are no longer parsed).
+- `get_requested_items` no longer pre-fetches the ticket to check its type; the API's own error is returned.
+- Failures raise tool errors rather than returning `{"error": ...}` dictionaries or strings.
+- Removed `smithery.yaml` and the Smithery-generated `Dockerfile` (distribution is via PyPI/`uvx`).
+- Dropped the `build` runtime dependency and the live-API script `tests/test-fs-mcp.py` (replaced by offline tests).

mcp_freshservice-2.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 effy
+Copyright (c) 2026 Angel Pandey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_freshservice-2.0.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: mcp-freshservice
+Version: 2.0.0
+Summary: A Model Context Protocol (MCP) server for the Freshservice ITSM API v2
+Project-URL: Homepage, https://github.com/angel-pandey/mcp-freshservice
+Project-URL: Repository, https://github.com/angel-pandey/mcp-freshservice
+Project-URL: Issues, https://github.com/angel-pandey/mcp-freshservice/issues
+Project-URL: Freshservice API, https://api.freshservice.com/
+Author: Angel Pandey, Gopi Krishnan, Maanaesh Swamy, Vijay Ragunath
+License-Expression: MIT
+License-File: LICENSE
+Keywords: freshservice,helpdesk,itsm,llm,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.13
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: mcp[cli]<2,>=1.30.0
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+# mcp-freshservice
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server for the
+[Freshservice REST API v2](https://api.freshservice.com/). It lets an AI assistant work with tickets,
+changes, problems, releases, assets, requesters, agents, groups, the service catalog and the knowledge
+base.
+
+> Forked from [effytech/freshservice_mcp](https://github.com/effytech/freshservice_mcp) and reworked for
+> v2 (see [CHANGELOG.md](CHANGELOG.md) for breaking changes).
+
+## Quick start
+
+You need a Freshservice API key (Profile Settings → API key) and your domain.
+
+```bash
+uvx mcp-freshservice --version
+```
+
+Claude Desktop / any MCP client (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "freshservice": {
+      "command": "uvx",
+      "args": ["mcp-freshservice"],
+      "env": {
+        "FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com",
+        "FRESHSERVICE_APIKEY": "<your-api-key>"
+      }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add freshservice -e FRESHSERVICE_DOMAIN=yourcompany.freshservice.com -e FRESHSERVICE_APIKEY=... -- uvx mcp-freshservice`
+
+## Configuration
+
+| Variable | Required | Description |
+|---|---|---|
+| `FRESHSERVICE_DOMAIN` | yes | `yourcompany.freshservice.com` (a bare `yourcompany` also works) |
+| `FRESHSERVICE_APIKEY` | yes | API key of the agent the server acts as. Permissions follow that agent |
+| `FRESHSERVICE_WORKSPACE_ID` | no | Default `workspace_id` for calls on multi-workspace accounts. A tool's own `workspace_id` argument wins |
+| `FRESHSERVICE_READ_ONLY` | no | `1` exposes only read-only tools |
+| `FRESHSERVICE_TOOLSETS` | no | Which toolsets to expose: names, `default` (the core set, used when unset) and/or `all`. See [Choosing tools](#choosing-tools) |
+| `FRESHSERVICE_TIMEOUT` | no | HTTP timeout in seconds (default 30) |
+| `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT` | no | `stdio` (default), `streamable-http` or `sse` |
+
+The same switches exist as flags: `--read-only`, `--toolsets tickets,solutions`, `--transport`.
+
+### Choosing tools
+
+The server can expose 204 tools (full list in [TOOLS.md](TOOLS.md)), but some clients cap the tools per agent
+(for example 128) and models choose better from a shorter list. So **by default only a 76-tool core set is
+enabled**; everything else is opt-in by toolset.
+
+```bash
+uvx mcp-freshservice --list-toolsets                         # see what's available
+uvx mcp-freshservice --toolsets default,changes,assets       # core set + changes + assets
+uvx mcp-freshservice --toolsets all                          # everything
+uvx mcp-freshservice --toolsets tickets,solutions --read-only
+```
+
+The same works with `FRESHSERVICE_TOOLSETS=default,changes` in the client's `env`. A list of plain names is
+exact (only those toolsets); add `default` to keep the core set.
+
+| Toolset | Default | Tools | Covers |
+|---|:-:|---:|---|
+| `tickets` | yes | 17 | tickets, replies and notes (with attachments), conversations, child tickets, requested items |
+| `ticket_time_entries` | yes | 5 | time logged on tickets |
+| `ticket_tasks` | | 5 | ticket tasks |
+| `ticket_approvals` | | 9 | service-request approval groups and approvals |
+| `requesters` | yes | 9 | requesters, fields, reactivate, convert to agent |
+| `agents` | yes | 9 | agents, fields, roles |
+| `groups` | yes | 13 | agent groups, requester groups and membership |
+| `solutions` | yes | 18 | knowledge-base categories, folders, articles, search |
+| `service_catalog` | yes | 5 | browse/search items, place service requests |
+| `changes` | | 9 | change requests and planning fields |
+| `change_notes`, `change_tasks`, `change_time_entries` | | 5 each | notes, tasks, time entries on changes |
+| `change_approvals` | | 9 | change approval groups, chains, approvals |
+| `problems`, `releases` | | 8, 7 | problem and release records |
+| `problem_*`, `release_*` (`notes`, `tasks`, `time_entries`) | | 5 each | notes, tasks, time entries |
+| `assets` | | 16 | assets, asset types, canned responses |
+| `organisation` | | 20 | workspaces, departments, locations, vendors, products |
+
+Every tool is annotated read-only / destructive so clients can auto-approve safely.
+
+## Conventions
+
+- **Single records** come back as Freshservice returns them: `{"ticket": {...}}`.
+- **Lists** return one page plus `pagination: {page, per_page, next_page, has_more}`. `per_page` is at most 100.
+- **Errors** are real MCP tool errors (`isError: true`) carrying Freshservice's message and field errors,
+  with hints for 401/403/404/429.
+- **Filtering**: see [Query syntax](#query-syntax).
+- **Numeric codes**: ticket status 2 Open, 3 Pending, 4 Resolved, 5 Closed; priority 1 Low … 4 Urgent;
+  source 1 Email, 2 Portal, 3 Phone, 4 Chat … (see `list_ticket_sources` for the full list).
+- **Attachments**: `send_ticket_reply`, `create_ticket_note`, `create_ticket` and
+  `update_ticket_conversation` accept local file paths (max 15 files / 40 MB).
+
+Example prompts: "Show ticket 12031 with its conversations and resolution notes", "How much time was
+logged on ticket 8?", "List open P1 incidents unassigned for a day", "Search the KB for printer setup".
+
+## Query syntax
+
+`filter_tickets`, `filter_changes`, `filter_requesters`, `filter_agents` and the `query` / `filter` / `search`
+arguments of the list tools use Freshservice's query language. Freshservice requires the whole query to be
+**enclosed in a pair of double quotes** (without them the API answers `500`), so the server adds them for you;
+you can pass `status:3` or `"status:3"` and get the same request.
+
+| Rule | Example |
+|---|---|
+| Fields are snake_case and case-sensitive (custom fields by API name) | `status:3` |
+| Numbers bare, strings and dates in **single** quotes | `tag:'vip'`, `planned_start_date:>'2025-07-14'` |
+| `AND`, `OR` and parentheses | `(group_id:12 OR group_id:15) AND status:3` |
+| `:>` / `:<` are **inclusive** (>= and <=), confirmed on a live account | `status:<5` means status 5 or lower |
+| `null` finds empty values | `agent_id:null` |
+| Starts-with (requesters and agents only) | `~[first_name\|last_name]:'ad'` |
+| Max 512 characters (checked locally); filter results are 30 per page | |
+
+Changes: `"status:3"` awaiting approval, `"approval_status:1"` approved,
+`"approval_status:1 AND status:<5"` approved and not closed (status 6 is Closed, and `:<` includes its boundary, so `<6` would include closed changes), `"status:3 AND priority:1"`. `approval_status`
+is 0 Requested, 1 Approved, 2 Rejected, 3 Not requested. A change `view` and `query` cannot be combined.
+
+Not every endpoint supports every field: departments and locations filter on `name` only; asset `search`
+takes one field (`name`, `asset_tag`, `serial_number`, ...); releases only have predefined `filter_name`
+values. The per-tool descriptions list the supported fields. Filtered requester/agent pages are capped at 40;
+changes to users can take a few minutes to be indexed.
+
+## Running remotely
+
+```bash
+MCP_TRANSPORT=streamable-http MCP_PORT=8000 uvx mcp-freshservice
+```
+
+The server is stateless over streamable HTTP and serves `/mcp`. It has **no authentication of its own**:
+run it behind a gateway/reverse proxy that authenticates callers, because everyone who can reach it acts
+with the configured API key.
+
+## Development
+
+```bash
+uv sync
+uv run pytest        # offline, mocks the Freshservice API
+uv run ruff check .
+```
+
+To check the server against a real Freshservice account (read-only by default; never prints your key):
+
+```bash
+uv run python scripts/live_check.py
+```
+
+When you point an MCP client at a local checkout with `uvx --from <folder> mcp-freshservice`, uvx reuses a
+cached build and will not notice your code changes (`--refresh` does not help). Add `--no-cache` to the uvx
+arguments while developing, e.g. `"args": ["--no-cache", "--from", "G:/path/to/mcp-freshservice", "mcp-freshservice"]`.
+
+Tests call tools through FastMCP's real `call_tool` path against a mocked API, so output-schema problems
+(like the old `get_ticket_by_id` failure) are caught without credentials. Each tool module lives in
+`src/mcp_freshservice/tools/`; add tools with `@ts.tool(title, kind)` and they are registered, filtered and
+annotated automatically.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

mcp_freshservice-2.0.0/README.md

@@ -0,0 +1,165 @@
+# mcp-freshservice
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server for the
+[Freshservice REST API v2](https://api.freshservice.com/). It lets an AI assistant work with tickets,
+changes, problems, releases, assets, requesters, agents, groups, the service catalog and the knowledge
+base.
+
+> Forked from [effytech/freshservice_mcp](https://github.com/effytech/freshservice_mcp) and reworked for
+> v2 (see [CHANGELOG.md](CHANGELOG.md) for breaking changes).
+
+## Quick start
+
+You need a Freshservice API key (Profile Settings → API key) and your domain.
+
+```bash
+uvx mcp-freshservice --version
+```
+
+Claude Desktop / any MCP client (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "freshservice": {
+      "command": "uvx",
+      "args": ["mcp-freshservice"],
+      "env": {
+        "FRESHSERVICE_DOMAIN": "yourcompany.freshservice.com",
+        "FRESHSERVICE_APIKEY": "<your-api-key>"
+      }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add freshservice -e FRESHSERVICE_DOMAIN=yourcompany.freshservice.com -e FRESHSERVICE_APIKEY=... -- uvx mcp-freshservice`
+
+## Configuration
+
+| Variable | Required | Description |
+|---|---|---|
+| `FRESHSERVICE_DOMAIN` | yes | `yourcompany.freshservice.com` (a bare `yourcompany` also works) |
+| `FRESHSERVICE_APIKEY` | yes | API key of the agent the server acts as. Permissions follow that agent |
+| `FRESHSERVICE_WORKSPACE_ID` | no | Default `workspace_id` for calls on multi-workspace accounts. A tool's own `workspace_id` argument wins |
+| `FRESHSERVICE_READ_ONLY` | no | `1` exposes only read-only tools |
+| `FRESHSERVICE_TOOLSETS` | no | Which toolsets to expose: names, `default` (the core set, used when unset) and/or `all`. See [Choosing tools](#choosing-tools) |
+| `FRESHSERVICE_TIMEOUT` | no | HTTP timeout in seconds (default 30) |
+| `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT` | no | `stdio` (default), `streamable-http` or `sse` |
+
+The same switches exist as flags: `--read-only`, `--toolsets tickets,solutions`, `--transport`.
+
+### Choosing tools
+
+The server can expose 204 tools (full list in [TOOLS.md](TOOLS.md)), but some clients cap the tools per agent
+(for example 128) and models choose better from a shorter list. So **by default only a 76-tool core set is
+enabled**; everything else is opt-in by toolset.
+
+```bash
+uvx mcp-freshservice --list-toolsets                         # see what's available
+uvx mcp-freshservice --toolsets default,changes,assets       # core set + changes + assets
+uvx mcp-freshservice --toolsets all                          # everything
+uvx mcp-freshservice --toolsets tickets,solutions --read-only
+```
+
+The same works with `FRESHSERVICE_TOOLSETS=default,changes` in the client's `env`. A list of plain names is
+exact (only those toolsets); add `default` to keep the core set.
+
+| Toolset | Default | Tools | Covers |
+|---|:-:|---:|---|
+| `tickets` | yes | 17 | tickets, replies and notes (with attachments), conversations, child tickets, requested items |
+| `ticket_time_entries` | yes | 5 | time logged on tickets |
+| `ticket_tasks` | | 5 | ticket tasks |
+| `ticket_approvals` | | 9 | service-request approval groups and approvals |
+| `requesters` | yes | 9 | requesters, fields, reactivate, convert to agent |
+| `agents` | yes | 9 | agents, fields, roles |
+| `groups` | yes | 13 | agent groups, requester groups and membership |
+| `solutions` | yes | 18 | knowledge-base categories, folders, articles, search |
+| `service_catalog` | yes | 5 | browse/search items, place service requests |
+| `changes` | | 9 | change requests and planning fields |
+| `change_notes`, `change_tasks`, `change_time_entries` | | 5 each | notes, tasks, time entries on changes |
+| `change_approvals` | | 9 | change approval groups, chains, approvals |
+| `problems`, `releases` | | 8, 7 | problem and release records |
+| `problem_*`, `release_*` (`notes`, `tasks`, `time_entries`) | | 5 each | notes, tasks, time entries |
+| `assets` | | 16 | assets, asset types, canned responses |
+| `organisation` | | 20 | workspaces, departments, locations, vendors, products |
+
+Every tool is annotated read-only / destructive so clients can auto-approve safely.
+
+## Conventions
+
+- **Single records** come back as Freshservice returns them: `{"ticket": {...}}`.
+- **Lists** return one page plus `pagination: {page, per_page, next_page, has_more}`. `per_page` is at most 100.
+- **Errors** are real MCP tool errors (`isError: true`) carrying Freshservice's message and field errors,
+  with hints for 401/403/404/429.
+- **Filtering**: see [Query syntax](#query-syntax).
+- **Numeric codes**: ticket status 2 Open, 3 Pending, 4 Resolved, 5 Closed; priority 1 Low … 4 Urgent;
+  source 1 Email, 2 Portal, 3 Phone, 4 Chat … (see `list_ticket_sources` for the full list).
+- **Attachments**: `send_ticket_reply`, `create_ticket_note`, `create_ticket` and
+  `update_ticket_conversation` accept local file paths (max 15 files / 40 MB).
+
+Example prompts: "Show ticket 12031 with its conversations and resolution notes", "How much time was
+logged on ticket 8?", "List open P1 incidents unassigned for a day", "Search the KB for printer setup".
+
+## Query syntax
+
+`filter_tickets`, `filter_changes`, `filter_requesters`, `filter_agents` and the `query` / `filter` / `search`
+arguments of the list tools use Freshservice's query language. Freshservice requires the whole query to be
+**enclosed in a pair of double quotes** (without them the API answers `500`), so the server adds them for you;
+you can pass `status:3` or `"status:3"` and get the same request.
+
+| Rule | Example |
+|---|---|
+| Fields are snake_case and case-sensitive (custom fields by API name) | `status:3` |
+| Numbers bare, strings and dates in **single** quotes | `tag:'vip'`, `planned_start_date:>'2025-07-14'` |
+| `AND`, `OR` and parentheses | `(group_id:12 OR group_id:15) AND status:3` |
+| `:>` / `:<` are **inclusive** (>= and <=), confirmed on a live account | `status:<5` means status 5 or lower |
+| `null` finds empty values | `agent_id:null` |
+| Starts-with (requesters and agents only) | `~[first_name\|last_name]:'ad'` |
+| Max 512 characters (checked locally); filter results are 30 per page | |
+
+Changes: `"status:3"` awaiting approval, `"approval_status:1"` approved,
+`"approval_status:1 AND status:<5"` approved and not closed (status 6 is Closed, and `:<` includes its boundary, so `<6` would include closed changes), `"status:3 AND priority:1"`. `approval_status`
+is 0 Requested, 1 Approved, 2 Rejected, 3 Not requested. A change `view` and `query` cannot be combined.
+
+Not every endpoint supports every field: departments and locations filter on `name` only; asset `search`
+takes one field (`name`, `asset_tag`, `serial_number`, ...); releases only have predefined `filter_name`
+values. The per-tool descriptions list the supported fields. Filtered requester/agent pages are capped at 40;
+changes to users can take a few minutes to be indexed.
+
+## Running remotely
+
+```bash
+MCP_TRANSPORT=streamable-http MCP_PORT=8000 uvx mcp-freshservice
+```
+
+The server is stateless over streamable HTTP and serves `/mcp`. It has **no authentication of its own**:
+run it behind a gateway/reverse proxy that authenticates callers, because everyone who can reach it acts
+with the configured API key.
+
+## Development
+
+```bash
+uv sync
+uv run pytest        # offline, mocks the Freshservice API
+uv run ruff check .
+```
+
+To check the server against a real Freshservice account (read-only by default; never prints your key):
+
+```bash
+uv run python scripts/live_check.py
+```
+
+When you point an MCP client at a local checkout with `uvx --from <folder> mcp-freshservice`, uvx reuses a
+cached build and will not notice your code changes (`--refresh` does not help). Add `--no-cache` to the uvx
+arguments while developing, e.g. `"args": ["--no-cache", "--from", "G:/path/to/mcp-freshservice", "mcp-freshservice"]`.
+
+Tests call tools through FastMCP's real `call_tool` path against a mocked API, so output-schema problems
+(like the old `get_ticket_by_id` failure) are caught without credentials. Each tool module lives in
+`src/mcp_freshservice/tools/`; add tools with `@ts.tool(title, kind)` and they are registered, filtered and
+annotated automatically.
+
+## License
+
+MIT, see [LICENSE](LICENSE).