node804-freshservice-mcp 1.2.0__tar.gz

node804_freshservice_mcp-1.2.0/.env.example

@@ -0,0 +1,9 @@
+FRESHSERVICE_DOMAIN=yourcompany.freshservice.com
+FRESHSERVICE_APIKEY=your_api_key_here
+# Permission mode: read, standard, full, or admin. Defaults to read if unset.
+FRESHSERVICE_MODE=standard
+FRESHSERVICE_CACHE_TTL=3600
+# Semicolon-separated directories the find_file tool may search (off when unset)
+# FRESHSERVICE_FILE_SEARCH_PATHS=C:\Users\me\Docs;C:\Exports
+# JSON-lines audit log of every tool call (off when unset)
+# FRESHSERVICE_AUDIT_LOG=C:\logs\freshservice-audit.jsonl

node804_freshservice_mcp-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Test
+        run: pytest tests/ -v

node804_freshservice_mcp-1.2.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

node804_freshservice_mcp-1.2.0/.gitignore

@@ -0,0 +1,177 @@
+# 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
+
+#GenAI Settings
+.claude/settings.local.json

node804_freshservice_mcp-1.2.0/.python-version

@@ -0,0 +1 @@
+3.13

node804_freshservice_mcp-1.2.0/CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+Project-level instructions for Claude Code when working on this repository.
+
+## Authoritative API Reference
+
+The **only** documentation source for Freshservice API endpoints, parameters, response formats, and behavior is:
+
+**https://api.freshservice.com/**
+
+Do not use third-party blogs, Stack Overflow, or other unofficial sources when adding or modifying tools. Always verify endpoint paths, required fields, query parameters, and response schemas against the official docs before writing code.
+
+## Project Overview
+
+This is an MCP (Model Context Protocol) server that wraps the Freshservice REST API v2 with permission-based tool gating. The `FRESHSERVICE_MODE` environment variable controls which tools are exposed to the LLM.
+
+## Key Architecture
+
+- **src-layout** Python package using hatchling build backend
+- **`server.py`** — FastMCP instance + `conditional_tool()` decorator. Tool modules are imported at the bottom to avoid circular imports.
+- **`config.py`** — Every tool function name must be listed in `TOOL_PERMISSIONS` with its minimum required mode. New tools that aren't in this map will be blocked by default.
+- **`client.py`** — Shared `httpx.AsyncClient` singleton with `RateLimitTransport` (429 retry + header tracking) and `TTLCache` / `@cached_response` for caching.
+- **`tools/`** — One module per Freshservice domain (tickets, changes, agents, etc). Each tool uses `@conditional_tool()` and calls `get_client()` for HTTP access.
+
+## Adding a New Tool
+
+1. Add the async function in the appropriate `tools/*.py` module with `@conditional_tool()`.
+2. Add the function name to `TOOL_PERMISSIONS` in `config.py` with the correct minimum mode (`read`, `standard`, `full`, or `admin`).
+3. If the tool returns rarely-changing data, add `@cached_response()` below `@conditional_tool()`. TTL is controlled by `FRESHSERVICE_CACHE_TTL` env var (default 3600s). Only override with `@cached_response(ttl_seconds=N)` if a tool genuinely needs a different TTL.
+4. All list endpoints must accept `page` and `per_page` parameters and return pagination metadata.
+5. Run `pytest tests/` and verify the tool count in the smoke test.
+
+## Tool Selection Guide
+
+When the user asks about their tickets, use the convenience tools instead of manually chaining lower-level calls. This saves API calls and avoids wasting tokens on plumbing.
+
+### "My tickets" / "My open tickets"
+
+Use `get_my_tickets(status_filter="unresolved")`. Do NOT manually call `get_current_agent` → `get_ticket_fields` → parse statuses → `filter_tickets`. The compound tool does all of that internally and its dependencies are cached.
+
+- `status_filter="unresolved"` (default) — everything except Resolved/Closed
+- `status_filter="resolved"` — only Resolved and Closed
+- `status_filter="all"` — every ticket assigned to the agent
+
+### Status lookups
+
+Use `get_ticket_statuses` to get categorized status IDs. Do NOT call `get_ticket_fields` and parse the status choices yourself. The tool returns `resolved_ids`, `unresolved_ids`, and a full `statuses` list with categories.
+
+### Agent identity
+
+Use `get_current_agent` whenever you need the authenticated user's agent ID, email, or group memberships. It is cached for the session — call it freely without worrying about API cost.
+
+### File discovery
+
+Use `find_file` to search for files on the local filesystem before using attachment tools. When the user asks to find, locate, or attach files from their system, always call `find_file` first. Searches are restricted to directories listed in `FRESHSERVICE_FILE_SEARCH_PATHS` (semicolon-separated). The tool supports partial names (`report`), glob patterns (`*.pdf`), and is case-insensitive. Results include absolute paths, sizes, and modified timestamps. Default limit is 25 results.
+
+### Attachments
+
+Use `add_ticket_attachment`, `add_note_attachment`, and `add_reply_attachment` to upload files. Each takes an absolute `file_path` on the MCP server's filesystem — the server reads the file, detects MIME type, and uploads it via multipart form-data. The total attachment size per ticket cannot exceed 40 MB (Freshservice limit).
+
+When the user provides a partial filename or isn't sure of the exact path, call `find_file` first to resolve the full path, then pass it to the attachment tool.
+
+To list or delete attachments, use `list_ticket_attachments`, `delete_ticket_attachment`, or `delete_conversation_attachment`.
+
+### Time entries
+
+Use `list_ticket_time_entries` and `view_ticket_time_entry` to read time logged against a ticket. Use `create_ticket_time_entry` to log new work (requires `time_spent` in "hh:mm" format, `note`, and `agent_id`). The optional `billable` flag marks whether the entry is billable. Use `update_ticket_time_entry` to modify an existing entry's time, note, or billable status. `delete_ticket_time_entry` permanently removes an entry (requires `full` mode).
+
+Equivalent tools exist for changes (`*_change_time_entry`).
+
+### Filter query syntax
+
+The `filter_tickets` and `filter_changes` tools accept a query string with this syntax:
+
+- Single condition: `"status:2"`
+- AND: `"status:2 AND priority:1"`
+- OR: `"status:2 OR status:3"`
+- Grouped: `"agent_id:123 AND (status:2 OR status:3)"`
+
+Field names match the Freshservice API field names (e.g., `agent_id`, `status`, `priority`, `requester_id`, `group_id`, `type`).
+
+### Pagination
+
+All list tools default to `page=1, per_page=30`. Only request additional pages if the user asks for more results or pagination metadata indicates `has_more: true`. Do not auto-paginate through all pages unless explicitly asked.
+
+### Cache behavior
+
+Schema and reference data (`get_ticket_fields`, `get_ticket_statuses`, `get_current_agent`, `list_change_fields`, etc.) are cached for the duration of `FRESHSERVICE_CACHE_TTL` (default 1 hour). If the user says data has changed, call `clear_cache` before retrying the lookup.
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```
+
+Tests use `monkeypatch` to set fake credentials. No real API calls are made in tests.

node804_freshservice_mcp-1.2.0/Dockerfile

@@ -0,0 +1,22 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
+# syntax=docker/dockerfile:1
+# Use Python 3.13 slim for compatibility (requires >=3.13)
+FROM python:3.13-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies for building Python packages
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy project definition
+COPY pyproject.toml ./
+COPY src ./src
+
+# Install project and dependencies
+RUN pip install --no-cache-dir .
+
+# Use python module entrypoint to start the MCP server
+ENTRYPOINT ["python", "-m", "node804_freshservice_mcp.server"]

node804_freshservice_mcp-1.2.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 effy (original work)
+Copyright (c) 2026 Michael Pope (this fork)
+
+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.