# tiflux/tiflux-mcp architecture

> Architecture diagram of the GitHub repository tiflux/tiflux-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tiflux/tiflux-mcp
- Repository: https://github.com/tiflux/tiflux-mcp

## Overview

#### 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`

Main entry points: [`src/infrastructure/http/HttpClient.js`](https://github.com/tiflux/tiflux-mcp/blob/main/src/infrastructure/http/HttpClient.js) (HTTP client & retries), [`src/registry/HandlerRegistry.js`](https://github.com/tiflux/tiflux-mcp/blob/main/src/registry/HandlerRegistry.js) (Handler registry), [`src/tools/tickets/index.js`](https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/tickets/index.js) (Ticket workflows), [`server-sdk.js`](https://github.com/tiflux/tiflux-mcp/blob/main/server-sdk.js) (SDK bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & Composition"]
  node_package["Package &amp; runtime<br/>Node.js contract<br/>[package.json]"]
  node_sdk["SDK bootstrap<br/>entrypoint<br/>[server-sdk.js]"]
  node_config["Config &amp; environment<br/>configuration<br/>[Config.js]"]
  node_container{{"Dependency container<br/>composition root<br/>[Container.js]"}}
  node_bootstrap["Infrastructure bootstrap<br/>initializer"]
  node_logger["Logger<br/>observability<br/>[Logger.js]"]
end

subgraph group_mcp["MCP Boundary"]
  node_mcp_api["Tiflux MCP API<br/>MCP server<br/>[tiflux-api.js]"]
  node_registry["Handler registry<br/>tool dispatcher<br/>[HandlerRegistry.js]"]
end

subgraph group_domains["Domain Tools"]
  node_ticket_tools["Ticket workflows<br/>MCP tools<br/>[index.js]"]
  node_chat_tools["Chat &amp; WhatsApp tools<br/>MCP tools<br/>[index.js]"]
  node_client_tools["Client tools<br/>MCP tools<br/>[index.js]"]
  node_other_tools["Assets, pre-tickets &amp; billing<br/>MCP tools"]
end

subgraph group_shared["Shared Pipeline"]
  node_resolution["Entity resolution<br/>shared service<br/>[deskResolver.js]"]
  node_validation["Validation &amp; tool errors<br/>shared service<br/>[validators.js]"]
  node_presentation["Response rendering<br/>shared service<br/>[response.js]"]
end

subgraph group_integration["Infrastructure &amp; External API"]
  node_http["HTTP client &amp; retries<br/>API gateway<br/>[HttpClient.js]"]
  node_cache[("Cache manager<br/>cache abstraction<br/>[CacheManager.js]")]
  node_tiflux_api(("Tiflux API v2<br/>external service"))
  node_fingerprint["Client fingerprint<br/>telemetry"]
end

node_package -->|"declares entrypoint"| node_sdk
node_sdk -->|"loads"| node_config
node_sdk -->|"creates"| node_container
node_container -->|"initializes"| node_bootstrap
node_bootstrap -->|"provisions"| node_http
node_bootstrap -->|"provisions"| node_cache
node_container -->|"provides"| node_logger
node_sdk -->|"starts"| node_mcp_api
node_mcp_api -->|"dispatches tools through"| node_registry
node_registry -->|"registers"| node_ticket_tools
node_registry -->|"registers"| node_chat_tools
node_registry -->|"registers"| node_client_tools
node_registry -->|"registers"| node_other_tools
node_ticket_tools -->|"validates arguments"| node_validation
node_chat_tools -->|"validates arguments"| node_validation
node_ticket_tools -->|"resolves entities"| node_resolution
node_client_tools -->|"resolves entities"| node_resolution
node_ticket_tools -->|"renders response"| node_presentation
node_chat_tools -->|"renders response"| node_presentation
node_resolution -->|"looks up IDs via"| node_http
node_ticket_tools -->|"calls through"| node_http
node_chat_tools -->|"calls through"| node_http
node_client_tools -->|"calls through"| node_http
node_other_tools -->|"calls through"| node_http
node_http -.->|"may use"| node_cache
node_http -->|"API v2 requests"| node_tiflux_api
node_mcp_api -.->|"identifies client"| node_fingerprint

click node_package "https://github.com/tiflux/tiflux-mcp/blob/main/package.json"
click node_sdk "https://github.com/tiflux/tiflux-mcp/blob/main/server-sdk.js"
click node_config "https://github.com/tiflux/tiflux-mcp/blob/main/src/core/Config.js"
click node_container "https://github.com/tiflux/tiflux-mcp/blob/main/src/core/Container.js"
click node_bootstrap "https://github.com/tiflux/tiflux-mcp/blob/main/src/infrastructure/InfrastructureBootstrap.js"
click node_logger "https://github.com/tiflux/tiflux-mcp/blob/main/src/core/Logger.js"
click node_mcp_api "https://github.com/tiflux/tiflux-mcp/blob/main/src/api/tiflux-api.js"
click node_registry "https://github.com/tiflux/tiflux-mcp/blob/main/src/registry/HandlerRegistry.js"
click node_ticket_tools "https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/tickets/index.js"
click node_chat_tools "https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/chats/index.js"
click node_client_tools "https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/clients/index.js"
click node_resolution "https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/_shared/deskResolver.js"
click node_validation "https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/_shared/validators.js"
click node_presentation "https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/_shared/response.js"
click node_http "https://github.com/tiflux/tiflux-mcp/blob/main/src/infrastructure/http/HttpClient.js"
click node_cache "https://github.com/tiflux/tiflux-mcp/blob/main/src/infrastructure/cache/CacheManager.js"
click node_fingerprint "https://github.com/tiflux/tiflux-mcp/blob/main/src/telemetry/ClientFingerprint.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package,node_sdk,node_config,node_container,node_bootstrap,node_logger toneBlue
class node_mcp_api,node_registry toneAmber
class node_ticket_tools,node_chat_tools,node_client_tools,node_other_tools toneMint
class node_resolution,node_validation,node_presentation toneRose
class node_http,node_cache,node_tiflux_api,node_fingerprint toneIndigo
```

## Components

### Runtime & Composition

- [Package & runtime](https://github.com/tiflux/tiflux-mcp/blob/main/package.json): Node.js contract · Defines the Node.js 18+ package and npx entrypoint. · `package.json`
- [SDK bootstrap](https://github.com/tiflux/tiflux-mcp/blob/main/server-sdk.js): entrypoint · `server-sdk.js`
- [Config & environment](https://github.com/tiflux/tiflux-mcp/blob/main/src/core/Config.js): configuration · `src/core/Config.js`
- [Dependency container](https://github.com/tiflux/tiflux-mcp/blob/main/src/core/Container.js): composition root · `src/core/Container.js`
- [Infrastructure bootstrap](https://github.com/tiflux/tiflux-mcp/blob/main/src/infrastructure/InfrastructureBootstrap.js): initializer · `src/infrastructure/InfrastructureBootstrap.js`
- [Logger](https://github.com/tiflux/tiflux-mcp/blob/main/src/core/Logger.js): observability · `src/core/Logger.js`

### MCP Boundary

- [Tiflux MCP API](https://github.com/tiflux/tiflux-mcp/blob/main/src/api/tiflux-api.js): MCP server · Assembles MCP-facing tool execution. · `src/api/tiflux-api.js`
- [Handler registry](https://github.com/tiflux/tiflux-mcp/blob/main/src/registry/HandlerRegistry.js): tool dispatcher · Aggregates domain tool definitions and handlers. · `src/registry/HandlerRegistry.js`

### Domain Tools

- [Ticket workflows](https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/tickets/index.js): MCP tools · Largest workflow surface for ticket lifecycle and reporting. · `src/tools/tickets/index.js`
- [Chat & WhatsApp tools](https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/chats/index.js): MCP tools · `src/tools/chats/index.js`
- [Client tools](https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/clients/index.js): MCP tools · `src/tools/clients/index.js`
- **Assets, pre-tickets & billing**: MCP tools

### Shared Pipeline

- [Entity resolution](https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/_shared/deskResolver.js): shared service · Resolves human names and custom fields to Tiflux IDs. · `src/tools/_shared/deskResolver.js`
- [Validation & tool errors](https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/_shared/validators.js): shared service · `src/tools/_shared/validators.js`
- [Response rendering](https://github.com/tiflux/tiflux-mcp/blob/main/src/tools/_shared/response.js): shared service · Formats Markdown-oriented MCP responses. · `src/tools/_shared/response.js`

### Infrastructure & External API

- [HTTP client & retries](https://github.com/tiflux/tiflux-mcp/blob/main/src/infrastructure/http/HttpClient.js): API gateway · Centralizes Tiflux API v2 requests and retry policy. · `src/infrastructure/http/HttpClient.js`
- [Cache manager](https://github.com/tiflux/tiflux-mcp/blob/main/src/infrastructure/cache/CacheManager.js): cache abstraction · `src/infrastructure/cache/CacheManager.js`
- **Tiflux API v2**: external service · Credentials, permissions, and licenses are enforced here.
- [Client fingerprint](https://github.com/tiflux/tiflux-mcp/blob/main/src/telemetry/ClientFingerprint.js): telemetry · `src/telemetry/ClientFingerprint.js`

## Connections

- Package & runtime → SDK bootstrap: declares entrypoint
- SDK bootstrap → Config & environment: loads
- SDK bootstrap → Dependency container: creates
- Dependency container → Infrastructure bootstrap: initializes
- Infrastructure bootstrap → HTTP client & retries: provisions
- Infrastructure bootstrap → Cache manager: provisions
- Dependency container → Logger: provides
- SDK bootstrap → Tiflux MCP API: starts
- Tiflux MCP API → Handler registry: dispatches tools through
- Handler registry → Ticket workflows: registers
- Handler registry → Chat & WhatsApp tools: registers
- Handler registry → Client tools: registers
- Handler registry → Assets, pre-tickets & billing: registers
- Ticket workflows → Validation & tool errors: validates arguments
- Chat & WhatsApp tools → Validation & tool errors: validates arguments
- Ticket workflows → Entity resolution: resolves entities
- Client tools → Entity resolution: resolves entities
- Ticket workflows → Response rendering: renders response
- Chat & WhatsApp tools → Response rendering: renders response
- Entity resolution → HTTP client & retries: looks up IDs via
- Ticket workflows → HTTP client & retries: calls through
- Chat & WhatsApp tools → HTTP client & retries: calls through
- Client tools → HTTP client & retries: calls through
- Assets, pre-tickets & billing → HTTP client & retries: calls through
- HTTP client & retries → Cache manager: may use
- HTTP client & retries → Tiflux API v2: API v2 requests
- Tiflux MCP API → Client fingerprint: identifies client