mcp-movidesk 0.1.0

package/.env.example

@@ -0,0 +1 @@
+MOVIDESK_TOKEN=coloque-seu-token-aqui

package/README.md

@@ -0,0 +1,161 @@
+# Movidesk MCP Server
+
+Servidor MCP em TypeScript/Bun para consultar tickets do Movidesk em modo somente leitura.
+
+## Ferramentas
+
+- `get_ticket`: retorna dados principais do ticket e resumo das ultimas interacoes.
+- `get_ticket_history`: retorna historico, comentarios, status e interacoes do ticket.
+- `get_ticket_attachments`: retorna anexos/imagens associados ao ticket, com metadados, hash e URL de download sem token quando houver hash.
+
+Nenhuma ferramenta cria, altera, exclui ou atualiza tickets.
+
+## Requisitos
+
+- Bun instalado.
+- Token da API Movidesk.
+
+## Instalacao
+
+```bash
+git clone <url-do-repositorio> mcp-movidesk
+cd mcp-movidesk
+bun install
+```
+
+## Variaveis De Ambiente
+
+Crie um arquivo `.env` ou configure a variavel no ambiente do MCP client:
+
+```bash
+MOVIDESK_TOKEN=seu-token-da-api-movidesk
+```
+
+O token nao deve ser versionado ou escrito no codigo.
+
+Um arquivo `.env.example` esta incluido apenas como modelo.
+
+## Execucao
+
+```bash
+bun run src/index.ts
+```
+
+Ou pelo script:
+
+```bash
+bun run start
+```
+
+## Configuracao MCP Client
+
+Exemplo generico de configuracao para um cliente MCP via stdio:
+
+```json
+{
+  "mcpServers": {
+    "movidesk": {
+      "command": "bun",
+      "args": ["run", "C:/MCP Servers/Movidesk/src/index.ts"],
+      "env": {
+        "MOVIDESK_TOKEN": "seu-token-da-api-movidesk"
+      }
+    }
+  }
+}
+```
+
+## Configuracao OpenCode
+
+Adicione o servidor no arquivo de configuracao do OpenCode, normalmente em `%USERPROFILE%\.opencode\opencode.json` no Windows.
+
+Exemplo usando pacote publicado e `bunx`:
+
+```json
+{
+  "mcpServers": {
+    "movidesk": {
+      "command": "bunx",
+      "args": ["mcp-movidesk@latest"],
+      "env": {
+        "MOVIDESK_TOKEN": "seu-token-da-api-movidesk"
+      }
+    }
+  }
+}
+```
+
+Exemplo usando o script `start` a partir de um repositorio clonado:
+
+```json
+{
+  "mcpServers": {
+    "movidesk": {
+      "command": "bun",
+      "args": ["run", "--cwd", "C:/caminho/para/mcp-movidesk", "start"],
+      "env": {
+        "MOVIDESK_TOKEN": "seu-token-da-api-movidesk"
+      }
+    }
+  }
+}
+```
+
+Depois de alterar a configuracao, reinicie o OpenCode e teste pedindo uma consulta de ticket numerico.
+
+## Publicacao
+
+Para publicar como pacote executavel e usar via `bunx`:
+
+```bash
+bun install
+bun run build
+npm publish
+```
+
+Depois de publicado, o OpenCode pode iniciar o MCP com `bunx mcp-movidesk@latest`.
+
+Antes de publicar, ajuste o `name` no `package.json` se quiser usar um pacote escopado, por exemplo `@sua-org/mcp-movidesk`. Nesse caso, a configuracao fica `"args": ["@sua-org/mcp-movidesk@latest"]`.
+
+Arquivos recomendados para versionar:
+
+- `bin/`
+- `scripts/`
+- `src/`
+- `package.json`
+- `bun.lock`
+- `tsconfig.json`
+- `README.md`
+- `.env.example`
+- `.gitignore`
+
+Nao versione `.env`, tokens, logs ou `node_modules/`.
+
+## API Movidesk Utilizada
+
+- Base URL: `https://api.movidesk.com/public/v1`
+- Ticket por ID: `GET /tickets?token=TOKEN&id=TICKET_ID`
+- Historico/interacoes: `GET /tickets` com `$expand=actions(...)`
+- Anexos do ticket: `actions($expand=attachments)`
+- Download de anexo: `GET /storage/download?token=TOKEN&id=HASH`; a ferramenta retorna apenas a URL sem `token` e o `hash`.
+
+Observacoes da documentacao Movidesk:
+
+- A rota `/tickets` cobre tickets com `lastUpdate` inferior a 90 dias; tickets antigos podem exigir `/tickets/past`.
+- A API possui limite de 10 requisicoes por minuto.
+- Em caso de bloqueio por falhas, a API pode retornar `429` e header `retry-after`.
+- O servidor serializa chamadas para respeitar aproximadamente 10 requisicoes por minuto.
+
+## Validacao
+
+```bash
+bun run typecheck
+```
+
+## Seguranca
+
+- O servidor usa apenas `GET`.
+- O token e lido exclusivamente de `MOVIDESK_TOKEN`.
+- URLs de anexo retornadas pelas ferramentas nao incluem token; use o hash retornado com credenciais fora do historico MCP quando precisar baixar o arquivo.
+- Logs sao minimos e nao exibem token.
+- Respostas grandes sao truncadas/resumidas antes de retornar ao agente.

package/bin/mcp-movidesk.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { MovideskClient } from "./movideskClient.js";
+import { registerTools } from "./tools.js";
+const token = process.env.MOVIDESK_TOKEN;
+if (!token) {
+    console.error("MOVIDESK_TOKEN nao configurado.");
+    process.exit(1);
+}
+const server = new McpServer({
+    name: "mcp-movidesk",
+    version: "0.1.0"
+});
+const client = new MovideskClient({ token });
+registerTools(server, client);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("Movidesk MCP server iniciado via stdio.");

package/dist/movideskClient.js

@@ -0,0 +1,141 @@
+const DEFAULT_BASE_URL = "https://api.movidesk.com/public/v1";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MIN_REQUEST_INTERVAL_MS = 6_100;
+let nextRequestAt = 0;
+export class MovideskApiError extends Error {
+    status;
+    retryAfterSeconds;
+    constructor(details) {
+        super(details.message);
+        this.name = "MovideskApiError";
+        this.status = details.status;
+        this.retryAfterSeconds = details.retryAfterSeconds;
+    }
+}
+export class MovideskClient {
+    baseUrl;
+    token;
+    timeoutMs;
+    constructor(options) {
+        this.token = options.token;
+        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async getTicket(ticketId) {
+        return this.getTicketWithFallback(ticketId, ticketExpand());
+    }
+    async getTicketHistory(ticketId) {
+        return this.getTicketWithFallback(ticketId, historyExpand());
+    }
+    async getTicketAttachments(ticketId) {
+        return this.getTicketWithFallback(ticketId, attachmentsExpand());
+    }
+    getAttachmentDownloadUrl(hash) {
+        const url = new URL(`${this.baseUrl}/storage/download`);
+        url.searchParams.set("id", hash);
+        return url.toString();
+    }
+    async getTicketWithFallback(ticketId, expand) {
+        try {
+            return await this.getTicketByRoute("tickets", ticketId, expand);
+        }
+        catch (error) {
+            if (error instanceof MovideskApiError && error.status === 404) {
+                return this.getTicketByRoute("tickets/past", ticketId, expand);
+            }
+            throw error;
+        }
+    }
+    async getTicketByRoute(route, ticketId, expand) {
+        const result = await this.get(`/${route}`, {
+            id: ticketId,
+            "$expand": expand
+        });
+        if (!result || typeof result !== "object") {
+            throw new MovideskApiError({ message: `Ticket ${ticketId} nao encontrado.` });
+        }
+        return result;
+    }
+    async get(path, params) {
+        await waitForRateLimit();
+        const url = new URL(`${this.baseUrl}${path}`);
+        url.searchParams.set("token", this.token);
+        for (const [key, value] of Object.entries(params)) {
+            url.searchParams.set(key, value);
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                headers: { Accept: "application/json" },
+                signal: controller.signal
+            });
+            if (!response.ok) {
+                throw await toApiError(response);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof MovideskApiError) {
+                throw error;
+            }
+            if (error instanceof DOMException && error.name === "AbortError") {
+                throw new MovideskApiError({ message: `Timeout ao consultar a API Movidesk apos ${this.timeoutMs}ms.` });
+            }
+            throw new MovideskApiError({ message: error instanceof Error ? error.message : "Erro desconhecido ao consultar a API Movidesk." });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+function ticketExpand() {
+    return [
+        "owner",
+        "createdBy",
+        "clients",
+        "actions($select=id,type,origin,status,justification,createdDate,createdBy,description,htmlDescription,isDeleted)"
+    ].join(",");
+}
+function historyExpand() {
+    return [
+        "actions($select=id,type,origin,status,justification,createdDate,createdBy,description,htmlDescription,isDeleted,tags)",
+        "actions($expand=attachments)"
+    ].join(",");
+}
+function attachmentsExpand() {
+    return [
+        "actions($select=id,createdDate,createdBy)",
+        "actions($expand=attachments)"
+    ].join(",");
+}
+async function toApiError(response) {
+    const retryAfter = response.headers.get("retry-after");
+    await safeDrainBody(response);
+    const message = retryAfter
+        ? `Movidesk retornou HTTP ${response.status}. Tente novamente apos ${retryAfter}s.`
+        : `Movidesk retornou HTTP ${response.status}.`;
+    return new MovideskApiError({
+        status: response.status,
+        message,
+        retryAfterSeconds: retryAfter
+    });
+}
+async function safeDrainBody(response) {
+    try {
+        await response.text();
+    }
+    catch {
+        // Ignore body read failures while preserving the HTTP status error.
+    }
+}
+async function waitForRateLimit() {
+    const now = Date.now();
+    const scheduledAt = Math.max(now, nextRequestAt);
+    nextRequestAt = scheduledAt + MIN_REQUEST_INTERVAL_MS;
+    const delayMs = scheduledAt - now;
+    if (delayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+}

package/dist/tools.js

@@ -0,0 +1,163 @@
+import { z } from "zod";
+import { MovideskApiError } from "./movideskClient.js";
+const TicketInputShape = {
+    ticketId: z.string().trim().regex(/^\d{1,30}$/, "ticketId deve conter apenas numeros")
+};
+const MAX_TEXT_LENGTH = 2_000;
+const MAX_ACTIONS = 40;
+export function registerTools(server, client) {
+    const registrar = server;
+    registrar.tool("get_ticket", "Consulta dados principais de um ticket Movidesk por ID. Ferramenta somente leitura.", TicketInputShape, async (input) => asToolResult(async () => summarizeTicket(await client.getTicket(input.ticketId))));
+    registrar.tool("get_ticket_history", "Consulta historico, comentarios, status e interacoes de um ticket Movidesk. Ferramenta somente leitura.", TicketInputShape, async (input) => asToolResult(async () => summarizeHistory(await client.getTicketHistory(input.ticketId))));
+    registrar.tool("get_ticket_attachments", "Lista anexos e imagens associados as acoes de um ticket Movidesk, incluindo metadados e URL de download sem token quando ha hash. Ferramenta somente leitura.", TicketInputShape, async (input) => asToolResult(async () => summarizeAttachments(await client.getTicketAttachments(input.ticketId), client)));
+}
+async function asToolResult(read) {
+    try {
+        const data = await read();
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, data }, null, 2) }]
+        };
+    }
+    catch (error) {
+        const data = formatError(error);
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify({ ok: false, error: data }, null, 2) }]
+        };
+    }
+}
+function summarizeTicket(ticket) {
+    const actions = Array.isArray(ticket.actions) ? ticket.actions : [];
+    return cleanObject({
+        id: ticket.id,
+        protocol: ticket.protocol,
+        subject: truncate(ticket.subject),
+        type: ticket.type,
+        status: ticket.status,
+        baseStatus: ticket.baseStatus,
+        justification: ticket.justification,
+        category: ticket.category,
+        urgency: ticket.urgency,
+        origin: ticket.origin,
+        createdDate: ticket.createdDate,
+        lastUpdate: ticket.lastUpdate,
+        lastActionDate: ticket.lastActionDate,
+        actionCount: ticket.actionCount,
+        ownerTeam: ticket.ownerTeam,
+        owner: summarizePerson(ticket.owner),
+        createdBy: summarizePerson(ticket.createdBy),
+        clients: ticket.clients?.map(summarizePerson),
+        serviceFull: ticket.serviceFull,
+        tags: ticket.tags,
+        dates: cleanObject({ resolvedIn: ticket.resolvedIn, reopenedIn: ticket.reopenedIn, closedIn: ticket.closedIn }),
+        recentActions: actions.slice(-5).map(summarizeAction),
+        note: actions.length > 5 ? `Retornadas as 5 acoes mais recentes de ${actions.length}. Use get_ticket_history para mais contexto.` : undefined
+    });
+}
+function summarizeHistory(ticket) {
+    const actions = Array.isArray(ticket.actions) ? ticket.actions : [];
+    const visibleActions = actions.slice(-MAX_ACTIONS);
+    return cleanObject({
+        ticketId: ticket.id,
+        subject: truncate(ticket.subject),
+        status: ticket.status,
+        totalActions: actions.length,
+        returnedActions: visibleActions.length,
+        truncated: actions.length > visibleActions.length,
+        actions: visibleActions.map(summarizeAction)
+    });
+}
+function summarizeAttachments(ticket, client) {
+    const actions = Array.isArray(ticket.actions) ? ticket.actions : [];
+    const attachments = actions.flatMap((action) => (action.attachments ?? []).map((attachment) => summarizeAttachment(attachment, action, client)));
+    return cleanObject({
+        ticketId: ticket.id,
+        subject: truncate(ticket.subject),
+        totalAttachments: attachments.length,
+        attachments
+    });
+}
+function summarizeAction(action) {
+    return cleanObject({
+        id: action.id,
+        type: action.type,
+        origin: action.origin,
+        status: action.status,
+        justification: action.justification,
+        createdDate: action.createdDate,
+        createdBy: summarizePerson(action.createdBy),
+        isDeleted: action.isDeleted,
+        description: truncate(stripHtml(action.description ?? action.htmlDescription ?? "")),
+        attachmentCount: action.attachments?.length ?? 0,
+        attachments: action.attachments?.map((attachment) => ({
+            fileName: attachment.fileName,
+            path: attachment.path,
+            createdDate: attachment.createdDate
+        })),
+        tags: action.tags
+    });
+}
+function summarizeAttachment(attachment, action, client) {
+    const hash = attachment.path?.trim();
+    return cleanObject({
+        fileName: attachment.fileName,
+        hash,
+        downloadUrl: hash ? client.getAttachmentDownloadUrl(hash) : undefined,
+        downloadRequiresToken: hash ? true : undefined,
+        createdDate: attachment.createdDate,
+        createdBy: summarizePerson(attachment.createdBy),
+        actionId: action.id,
+        actionCreatedDate: action.createdDate,
+        actionCreatedBy: summarizePerson(action.createdBy)
+    });
+}
+function summarizePerson(person) {
+    if (!person || typeof person !== "object") {
+        return undefined;
+    }
+    const value = person;
+    return cleanObject({
+        id: value.id,
+        businessName: value.businessName,
+        email: value.email,
+        personType: value.personType,
+        profileType: value.profileType
+    });
+}
+function truncate(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length <= MAX_TEXT_LENGTH) {
+        return normalized;
+    }
+    return `${normalized.slice(0, MAX_TEXT_LENGTH)}... [truncated]`;
+}
+function stripHtml(value) {
+    return value
+        .replace(/<[^>]*>/g, " ")
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/g, "'");
+}
+function cleanObject(object) {
+    return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined && value !== null));
+}
+function formatError(error) {
+    if (error instanceof MovideskApiError) {
+        return cleanObject({
+            type: error.name,
+            status: error.status,
+            message: error.message,
+            retryAfterSeconds: error.retryAfterSeconds
+        });
+    }
+    return {
+        type: "UnexpectedError",
+        message: error instanceof Error ? error.message : "Erro desconhecido."
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "mcp-movidesk",
+  "version": "0.1.0",
+  "description": "MCP server read-only para consultar tickets do Movidesk.",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "mcp-movidesk": "./bin/mcp-movidesk.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "build": "tsc && bun run scripts/add-shebang.ts",
+    "prepack": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.13",
+    "typescript": "5.9.3"
+  }
+}