tiflux/tiflux-mcp

Purpose and Entry Points

This is a Node.js MCP server/SDK that exposes Tiflux service-management operations as AI-callable tools: tickets, chats/WhatsApp, clients, requestors, assets, knowledge, billing, and reporting. It supports local stdio execution via npx @tiflux/mcp; the hosted HTTP/OAuth service described in the README is an external deployment mode.

• SDK/bootstrap entry: server-sdk.js

• MCP API assembly: src/api/tiflux-api.js

• Package/runtime contract: package.json

Composition Root and Dependency Boundaries

The application uses a lightweight dependency container. Startup loads environment/configuration, creates shared infrastructure, then registers tool handlers. Tool code should depend on container-provided services rather than directly constructing HTTP, cache, or logging clients.

• Configuration and environment defaults: src/core/Config.js, config/default.json

• Dependency composition: src/core/Container.js

• Infrastructure initialization: src/infrastructure/InfrastructureBootstrap.js

MCP Tool Registration and Dispatch

The registry is the control boundary between an MCP client invocation and a domain handler. Domain folders export tool definitions/handlers, while the central registry aggregates them for the MCP API layer.

• Registry: src/registry/HandlerRegistry.js, src/registry/index.js

• API-facing MCP server logic: src/api/tiflux-api.js

• Representative domain entry points: src/tools/tickets/index.js, src/tools/chats/index.js, src/tools/clients/index.js

Domain Tool Layer

Tools are organized by Tiflux business capability, generally mapping an MCP schema and response formatter to one or more Tiflux API v2 calls. The ticket domain is the largest workflow surface: lifecycle changes, answers, files, histories, SLA, appointments, entity fields, aggregation, and feedback reports.

• Ticket workflows: src/tools/tickets/createTicket.js, src/tools/tickets/updateTicket.js, src/tools/tickets/listTickets.js

• Chat and WhatsApp operations: src/tools/chats/sendMessage.js, src/tools/chats/updateChat.js

• Other major bounded domains: src/tools/equipments/, src/tools/pre_tickets/, src/tools/billings/

Resolution, Validation, and Presentation Pipeline

Handlers normalize/validate MCP arguments, resolve human names to Tiflux IDs when needed, make API calls, and render Markdown-oriented responses. Shared logic encapsulates cross-domain business behaviors such as fuzzy matching, desk/client/requestor/user lookup, custom-field handling, file validation, pagination, comparisons, and diagnostics.

• Name and entity resolution: src/tools/_shared/deskResolver.js, src/tools/_shared/clientResolver.js, src/tools/_shared/entityFieldResolver.js

• Validation and errors: src/tools/_shared/validators.js, src/tools/_shared/errors.js

• Response/rendering and Markdown conversion: src/tools/_shared/response.js, src/tools/_shared/markdownToHtml.js

External Integration and Resilience

The primary external dependency is the Tiflux API v2. Requests are made through a centralized HTTP client, with retry policy and cache abstractions available for reusable API access patterns. API credentials are supplied through environment configuration (TIFLUX_API_KEY for local execution); permissions and licenses are enforced by Tiflux API responses.

• HTTP boundary: src/infrastructure/http/HttpClient.js, src/infrastructure/http/RetryPolicy.js

• Cache abstraction: src/infrastructure/cache/CacheManager.js, src/infrastructure/cache/CacheStrategy.js

• Error normalization: src/utils/errors.js

Runtime Observability and Request Context

Node.js 18+ is the material local runtime. Logging and client fingerprinting provide operational context without being part of business-domain handlers. Output verbosity is configurable for token-sensitive MCP clients.

• Logging: src/core/Logger.js

• Client identification: src/telemetry/ClientFingerprint.js

• Environment template: .env.example