feat: modular architecture — 115 tools consolidated to 21 + Assets/CMDB support + Change planning fixes

README.md

@@ -17,20 +17,23 @@ A powerful MCP (Model Context Protocol) server implementation that seamlessly in
 
 **This MCP server currently supports operations across a wide range of Freshservice modules**:
 
--  Tickets
--  Changes
--  Conversations
--  Products
--  Requesters
--  Agents
--  Agent Groups
--  Requester Groups
--  Canned Responses
--  Canned Response Folders
--  Workspaces
--  Solution Categories
--  Solution Folders
--  Solution Articles
+- Tickets
+- Changes
+- Conversations
+- Products
+- Requesters
+- Agents
+- Agent Groups
+- Requester Groups
+- Canned Responses
+- Canned Response Folders
+- Workspaces
+- Solution Categories
+- Solution Folders
+- Solution Articles
+- Assets / CMDB
+- Asset Relationships
+- Asset Types
 
 ## Components & Tools
 
@@ -39,7 +42,7 @@ The server provides a comprehensive toolkit for Freshservice operations:
 ### Ticket Management
 
 | Tool | Description | Key Parameters |
-|------|-------------|----------------|
+| ---- | ----------- | -------------- |
 | `create_ticket` | Create new service tickets | `subject`, `description`, `source`, `priority`, `status`, `email` |
 | `update_ticket` | Update existing tickets | `ticket_id`, `updates` |
 | `delete_ticket` | Remove tickets | `ticket_id` |
@@ -51,7 +54,7 @@ The server provides a comprehensive toolkit for Freshservice operations:
 ### Change Management
 
 | Tool | Description | Key Parameters |
-|------|-------------|----------------|
+| ---- | ----------- | -------------- |
 | `get_changes` | List all changes with pagination | `page`, `per_page`, `query` |
 | `filter_changes` | Filter changes with advanced queries | `query`, `page`, `per_page` |
 | `get_change_by_id` | Retrieve single change details | `change_id` |
@@ -66,16 +69,54 @@ The server provides a comprehensive toolkit for Freshservice operations:
 
 When using `get_changes` or `filter_changes` with the `query` parameter, **the query string must be wrapped in double quotes** for the Freshservice API to work correctly:
 
-✅ **CORRECT**: `"status:3"`, `"approval_status:1 AND status:<6"`  
+✅ **CORRECT**: `"status:3"`, `"approval_status:1 AND status:<6"`
 ❌ **WRONG**: `status:3` (will cause 500 Internal Server Error)
 
 **Common Query Examples:**
+
 - `"status:3"` - Changes awaiting approval
-- `"approval_status:1"` - Approved changes  
+- `"approval_status:1"` - Approved changes
 - `"approval_status:1 AND status:<6"` - Approved changes that are not closed
 - `"planned_start_date:>'2025-07-14'"` - Changes starting after specific date
 - `"status:3 AND priority:1"` - High priority changes awaiting approval
 
+### Asset / CMDB Management
+
+| Tool | Description | Key Parameters |
+| ---- | ----------- | -------------- |
+| `get_assets` | List all assets with pagination | `page`, `per_page`, `include`, `order_by`, `order_type`, `trashed`, `workspace_id` |
+| `get_asset_by_id` | Retrieve single asset details | `display_id`, `include` |
+| `create_asset` | Create a new asset | `name`, `asset_type_id`, `impact`, `usage_type`, `description`, `type_fields` |
+| `update_asset` | Update an existing asset | `display_id`, `asset_fields` |
+| `delete_asset` | Delete (trash) an asset | `display_id` |
+| `delete_asset_permanently` | Permanently delete a trashed asset | `display_id` |
+| `restore_asset` | Restore a trashed asset | `display_id` |
+| `search_assets` | Search assets by attributes | `search_query`, `page`, `trashed` |
+| `filter_assets` | Filter assets with advanced queries | `filter_query`, `page`, `include` |
+| `move_asset` | Move asset to another workspace | `display_id`, `workspace_id`, `agent_id`, `group_id` |
+| `get_asset_components` | List hardware components | `display_id` |
+| `get_asset_assignment_history` | View user assignment history | `display_id` |
+| `get_asset_requests` | List associated tickets | `display_id` |
+| `get_asset_contracts` | List associated contracts | `display_id` |
+
+### Asset Relationships
+
+| Tool | Description | Key Parameters |
+| ---- | ----------- | -------------- |
+| `get_asset_relationships` | List relationships for an asset | `display_id` |
+| `get_all_relationships` | List all relationships | `page`, `per_page` |
+| `get_relationship_by_id` | View a specific relationship | `relationship_id` |
+| `create_asset_relationships` | Create relationships in bulk | `relationships` |
+| `delete_asset_relationships` | Delete relationships in bulk | `relationship_ids` |
+| `get_relationship_types` | List available relationship types | None |
+
+### Asset Types
+
+| Tool | Description | Key Parameters |
+| ---- | ----------- | -------------- |
+| `get_asset_types` | List all asset types | `page`, `per_page` |
+| `get_asset_type_by_id` | View a specific asset type | `asset_type_id` |
+
 ## Getting Started
 
 ### Installing via Smithery
@@ -119,27 +160,42 @@ npx -y @smithery/cli install @effytech/freshservice_mcp --client claude
   }
 }
 ```
+
 **Important**: Replace `<YOUR_FRESHSERVICE_APIKEY>` with your actual API key and `<YOUR_FRESHSERVICE_DOMAIN>` with your domain (e.g., `yourcompany.freshservice.com`)
 
 ## Example Operations
 
 Once configured, you can ask Claude to perform operations like:
 
 **Tickets:**
+
 - "Create a new incident ticket with subject 'Network connectivity issue in Marketing department' and description 'Users unable to connect to Wi-Fi in Marketing area', set priority to high"
 - "List all critical incidents reported in the last 24 hours"
 - "Update ticket #12345 status to resolved"
 
 **Changes:**
+
 - "Create a change request for scheduled server maintenance next Tuesday at 2 AM"
 - "Update the status of change request #45678 to 'Approved'"
 - "Close change #5092 with result explanation 'Successfully deployed to production. All tests passed.'"
 - "List all pending changes"
 
 **Other Operations:**
+
 - "Show asset details for laptop with asset tag 'LT-2023-087'"
 - "Create a solution article about password reset procedures"
 
+**Assets / CMDB:**
+
+- "List all assets in the CMDB"
+- "Create a new hardware asset named 'Dell Latitude 5540' with asset type 'Laptop'"
+- "Search assets with serial number 'HSN12345'"
+- "Filter assets by state 'IN USE' in department 5"
+- "Show all components of asset #42 (CPU, memory, disk, etc.)"
+- "Show the assignment history for asset #115"
+- "List all relationships for asset #42"
+- "Move asset #99 to workspace 3"
+
 ## Testing
 
 For testing purposes, you can start the server manually:
@@ -155,7 +211,6 @@ uvx freshservice-mcp --env FRESHSERVICE_APIKEY=<your_api_key> --env FRESHSERVICE
 - Check API rate limits and quotas
 - Verify the `uvx` command is available in your PATH
 
-
 ## License
 
 This MCP server is licensed under the MIT License. See the LICENSE file in the project repository for full details.

src/freshservice_mcp/config.py

@@ -0,0 +1,110 @@
+"""Freshservice MCP — Configuration and constants."""
+import os
+import logging
+from enum import IntEnum, Enum
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("freshservice_mcp")
+
+# ---------------------------------------------------------------------------
+# API credentials
+# ---------------------------------------------------------------------------
+FRESHSERVICE_DOMAIN = os.getenv("FRESHSERVICE_DOMAIN")
+FRESHSERVICE_APIKEY = os.getenv("FRESHSERVICE_APIKEY")
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+class TicketSource(IntEnum):
+    EMAIL = 1
+    PORTAL = 2
+    PHONE = 3
+    YAMMER = 6
+    CHAT = 7
+    AWS_CLOUDWATCH = 7
+    PAGERDUTY = 8
+    WALK_UP = 9
+    SLACK = 10
+    WORKPLACE = 12
+    EMPLOYEE_ONBOARDING = 13
+    ALERTS = 14
+    MS_TEAMS = 15
+    EMPLOYEE_OFFBOARDING = 18
+
+class TicketStatus(IntEnum):
+    OPEN = 2
+    PENDING = 3
+    RESOLVED = 4
+    CLOSED = 5
+
+class TicketPriority(IntEnum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    URGENT = 4
+
+class ChangeStatus(IntEnum):
+    OPEN = 1
+    PLANNING = 2
+    AWAITING_APPROVAL = 3
+    PENDING_RELEASE = 4
+    PENDING_REVIEW = 5
+    CLOSED = 6
+
+class ChangePriority(IntEnum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    URGENT = 4
+
+class ChangeImpact(IntEnum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+
+class ChangeType(IntEnum):
+    MINOR = 1
+    STANDARD = 2
+    MAJOR = 3
+    EMERGENCY = 4
+
+class ChangeRisk(IntEnum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    VERY_HIGH = 4
+
+class UnassignedForOptions(str, Enum):
+    THIRTY_MIN = "30m"
+    ONE_HOUR = "1h"
+    TWO_HOURS = "2h"
+    FOUR_HOURS = "4h"
+    EIGHT_HOURS = "8h"
+    TWELVE_HOURS = "12h"
+    ONE_DAY = "1d"
+    TWO_DAYS = "2d"
+    THREE_DAYS = "3d"
+
+# All available scopes for --scope flag
+AVAILABLE_SCOPES = [
+    "tickets",
+    "changes",
+    "assets",
+    "agents",
+    "requesters",
+    "groups",
+    "solutions",
+    "products",
+    "service_catalog",
+    "canned_responses",
+    "workspaces",
+    "discovery",
+]