@nextoolsolutions/mcp-glpi-core 0.0.0-stage → 1.3.1

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog — @nextoolsolutions/mcp-glpi-core
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions follow semver.
+
+## [Unreleased]
+
+## [1.3.1] - 2026-10-04
+
+### Fixed
+- **Raw HTML in markdown tables for nested richtext.** `pickFields` flattens richtext only at the top
+  level, so the API v2 timeline (`{type, item: {content: "<p>…</p>"}}`) reached the markdown summary
+  as `<p>Olá <strong></strong>…`. In `format: "markdown"` (default `fields: "essential"`) the payload
+  now goes through `flattenRichtext` before the view and the table: richtext fields are turned into
+  text at any depth (up to 3 levels). The JSON result and `fields: "all"` keep the HTML as GLPI sent it.
+- Table cells turn a run of line breaks into one space (a flattened paragraph left double spaces).
+
+### Added
+- `flattenRichtext(value, maxDepth = 3)` and `MARKDOWN_RICHTEXT_FIELDS` (`RICHTEXT_FIELDS` plus the
+  validation comments `comment_submission`, `comment_validation`, `submission_comment`,
+  `approval_comment`, which GLPI 11 stores as HTML).
+
+## [1.3.0] - 2026-10-04
+
+### Added
+- `markdownViews` option of `installPayloadFormatting` and `columnView` / `MarkdownColumn` /
+  `MarkdownView`: per-tool column projection for listings in `format: "markdown"` (only with the
+  default `fields: "essential"`; the JSON result is never projected). The size budget measures the
+  projected table, so more rows fit.
+
+### Changed
+- `ESSENTIAL_FIELDS.Ticket` keeps `requesters` and `assigned` (the `{id, name}` lists
+  `mcp-glpi` 3.5.0 adds to ticket listings).
+
+## [1.2.0] - 2026-10-04
+
+### Added
+- Size budget for every read tool (`installPayloadFormatting`): texts longer than
+  `LIST_TEXT_MAX_CHARS` (300, `GLPI_LIST_TEXT_MAX_CHARS`) are cut in listings (except the ticket
+  history listings in `FULL_TEXT_LISTS`, and with `fields: "all"`); an answer longer than
+  `MAX_RESPONSE_CHARS` (50000, `GLPI_MAX_RESPONSE_CHARS`) is trimmed from the end of the list.
+- `nextPageNote`: the pagination note names only the parameters the tool has (`range`, or
+  `start`/`limit`) with the values of the next page, and uses `total` when the result carries it.
+- `cutLongTexts`, `FULL_TEXT_LISTS`.
+
+### Changed
+- **`format: "markdown"` is carried in `structuredContent` too** (`{ data: "<markdown>",
+  format: "markdown", count?, note? }`). Clients that support structured results hand that to
+  the model, so a markdown text block alone was ignored. Sibling keys of `data` (e.g. `total`)
+  are kept in the rendering. A single item renders as `key: value` lines without cutting texts;
+  `{id, name}` references render as "name (id)".
+- Results whose payload is the structured object itself (API v2 single items) are formatted
+  too; before, `fields` and `format` were silently ignored on them.
+- `TOOL_ITEMTYPES` holds API v1 tools only: v2 payloads use other field names and the v1
+  whitelists stripped their relations (`entity`, `category`, `team`). v2 tools use the generic
+  blocklist, which now also drops `*_duration` and `internal_*`.
+- Whitelists keep keys ending in `_name` (names resolved by the server) and numeric keys (search
+  columns). `glpi_search` is no longer a generic-itemtype tool.
+- `MAX_PAGE_SIZE` default 200 -> 100. `paginationNote` no longer names a parameter.
+- `errorResult` has no `structuredContent`: the MCP SDK client validates it against the output
+  schema even on errors, which replaced every GLPI error message with a schema error.
+- `sanitizeId` refuses an empty ID (it built the collection URL).
+
+## [1.1.0] - 2026-10-04
+
+### Added
+- `FetchImpl` type and an optional `fetchImpl` argument on `fetchFn` / `fetchWithTimeout`:
+  callers inject their own `fetch` (e.g. one that validates the resolved IP).
+- `GlpiRedirectError` (extends `GlpiHttpError`, with `targetHost`) and `assertNotRedirect`.
+- `titleFromToolName` and the `ToolAnnotationHints` type.
+
+### Changed
+- **Redirects are never followed.** Every request is sent with `redirect: "manual"`; a 3xx (or an
+  opaque redirect) throws `redirect not followed: <status> -> <host>`. Only the host of the
+  Location is reported, never its path or query. The Node polyfill now exposes `location`.
+- **Annotations.** `annotationsFor(kind, toolName?)`: `openWorldHint` is now `false`;
+  `idempotentHint` is `true` for reads, destructive tools and `update_*` / `set_*` writes.
+  `destructiveHint` is `true` for deletes and for every write that is not additive
+  (`update_*`, `set_*`, `change_*`, `retry_*`): the MCP spec defines `false` as "only additive
+  updates", so only `create_*` / `add_*` stay non-destructive.
+  `installWritePolicy` also sets `annotations.title` (the tool's `title`, or one derived from
+  its name).
+- LICENSE (MIT, NexTool Solutions) and CHANGELOG ship in the package.
+
+## [1.0.0] - 2026-08-31
+
+### Added
+- Shared HTTP transport with retry/timeout, typed errors, tool-result helpers, write policy,
+  payload formatting, pagination and create idempotency for the GLPI MCP servers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NexTool Solutions
+
+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.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @nextoolsolutions/mcp-glpi-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared infrastructure for NexTool MCP for GLPI (`@nextoolsolutions/mcp-glpi`, API v1 and v2
+families). It started as the byte-identical code the old `mcp-glpi` and `mcp-glpi-v2` servers
+both carried.
+
+> Not affiliated with Teclib'. GLPI is a registered trademark of Teclib'.
+
+| Module | What it holds |
+|--------|---------------|
+| `http.ts` | Injectable fetch (`FetchImpl`), polyfill, timeout, redirect refusal, retry/backoff helpers, URL helpers, ID sanitisation |
+| `errors.ts` | `GlpiHttpError` base class, `GlpiRedirectError`, `GlpiPolicyError` |
+| `result.ts` | `toolResult` / `jsonResult` / `errorResult` / `makeWrap` |
+| `policy.ts` | Write policy: read-only mode, delete gating, tool classification by name |
+| `server-policy.ts` | Installs the policy and MCP annotations (title, read-only, destructive, idempotent, closed world) by wrapping `registerTool` |
+| `format.ts` | HTML stripping, per-itemtype field whitelists (API v1), markdown rendering |
+| `pagination.ts` | Range/limit defaults and ceiling, size budget constants, next-page notes |
+| `server-format.ts` | Installs payload formatting, pagination and the size budget on read tools; markdown goes in the text and in `structuredContent` |
+| `idempotency.ts` | Create idempotency key and store |
+| `server-idempotency.ts` | Installs the create guard, including in-flight collapsing |
+
+## Design note
+
+The three `install*` functions wrap `server.registerTool` once, right after the server is
+constructed, instead of editing 144 call sites. Every tool registered afterwards — present or
+future — is covered, and misclassification fails the test suite rather than leaking a write.
+They compose in any order.
+
+## Transport guarantees
+
+- `fetchFn(url, init, fetchImpl?)` / `fetchWithTimeout(...)` use the injected `fetchImpl`, else
+  the global `fetch`, else a Node `http`/`https` polyfill.
+- Requests always go out with `redirect: "manual"`. A 3xx throws `GlpiRedirectError`
+  (`redirect not followed: <status> -> <host>`); the Location path and query never reach the
+  message. Clients treat it as final (no retry).
+
+## Read tool output (1.2.0)
+
+- `format: "markdown"` is returned in the text block and in `structuredContent`
+  (`{ data: "<markdown>", format: "markdown", count, note }`), for wrapped (`{ data }`) and
+  unwrapped (API v2 item) payloads alike.
+- Listings: at most `GLPI_MAX_PAGE_SIZE` (100) items, texts cut at `GLPI_LIST_TEXT_MAX_CHARS`
+  (300) except in `FULL_TEXT_LISTS`, answer trimmed to `GLPI_MAX_RESPONSE_CHARS` (50000). The
+  `note` names only the tool's own pagination parameters.
+- `errorResult` carries no `structuredContent`, so validating clients show the error message.
+- Markdown views (1.3.0): `installPayloadFormatting({ markdownViews })` maps a tool name to a row
+  projection (`columnView([{ label, from }])`, `from` = a key, candidate keys or a function). In
+  `format: "markdown"` with `fields: "essential"` the listing table shows only those columns; the
+  JSON result and `fields: "all"` keep every field. The `Ticket` whitelist keeps `requesters` and
+  `assigned` (people resolved by the server).
+- Nested richtext in markdown (1.3.1): `flattenRichtext` turns HTML into text in richtext fields at
+  any depth (the API v2 timeline's `item.content`, validation comments) before a markdown table or
+  item is drawn; the JSON result and `fields: "all"` keep the HTML.
+
+## Consuming it
+
+`@nextoolsolutions/mcp-glpi` declares it as `^1.3.1`. Inside the repo its lockfile links the
+sibling folder, so build here first — `tsx` does not transpile TypeScript inside
+`node_modules`, the server loads the compiled `dist/`:
+
+```bash
+cd mcp-glpi-core && npm ci && npm run build    # after every change
+```
+
+Publish this package before any `mcp-glpi` release that needs a new core version.
+
+## Tests
+
+```bash
+npm test    # node --test via tsx, no extra dependency
+```

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared error types for the GLPI MCP servers.
+ *
+ * Both mcp-glpi (REST v1) and mcp-glpi-v2 (API v2 / OAuth2) used to declare an
+ * identical error class. They now extend this base so callers can catch a
+ * single type while each server keeps its own `name` for readable messages.
+ */
+export declare class GlpiHttpError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    constructor(message: string, status: number, method: string, path: string, name?: string);
+}
+/** Raised when the write policy blocks an operation before it reaches GLPI. */
+export declare class GlpiPolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when GLPI answers a request with a 3xx. Requests go out with
+ * `redirect: "manual"`, so a redirect is never followed: following one would
+ * send the session/OAuth headers to whatever host the Location names. Only the
+ * target host is kept in the message — the Location path and query may carry
+ * tokens.
+ */
+export declare class GlpiRedirectError extends GlpiHttpError {
+    readonly targetHost: string;
+    constructor(status: number, method: string, path: string, targetHost: string);
+}

package/dist/errors.js

@@ -0,0 +1,40 @@
+/**
+ * Shared error types for the GLPI MCP servers.
+ *
+ * Both mcp-glpi (REST v1) and mcp-glpi-v2 (API v2 / OAuth2) used to declare an
+ * identical error class. They now extend this base so callers can catch a
+ * single type while each server keeps its own `name` for readable messages.
+ */
+export class GlpiHttpError extends Error {
+    status;
+    method;
+    path;
+    constructor(message, status, method, path, name = "GlpiHttpError") {
+        super(message);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.name = name;
+    }
+}
+/** Raised when the write policy blocks an operation before it reaches GLPI. */
+export class GlpiPolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GlpiPolicyError";
+    }
+}
+/**
+ * Raised when GLPI answers a request with a 3xx. Requests go out with
+ * `redirect: "manual"`, so a redirect is never followed: following one would
+ * send the session/OAuth headers to whatever host the Location names. Only the
+ * target host is kept in the message — the Location path and query may carry
+ * tokens.
+ */
+export class GlpiRedirectError extends GlpiHttpError {
+    targetHost;
+    constructor(status, method, path, targetHost) {
+        super(`redirect not followed: ${status} -> ${targetHost}`, status, method, path, "GlpiRedirectError");
+        this.targetHost = targetHost;
+    }
+}

package/dist/format.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Payload formatting for the GLPI MCP servers.
+ *
+ * GLPI returns everything it has: a single ticket carries 45 fields, roughly
+ * twenty of which are SLA/OLA bookkeeping and delay statistics no agent ever
+ * reads, and richtext fields arrive as double-escaped TinyMCE HTML
+ * (`<div class="elementToProof">Teste</div>`). Returning that raw
+ * burns context on every call.
+ *
+ * `essential` mode keeps the fields that describe the item; `all` returns the
+ * untouched payload for the cases where a rare field is genuinely needed.
+ */
+export type FieldMode = "essential" | "all";
+export type OutputFormat = "json" | "markdown";
+/**
+ * Turns a TinyMCE richtext field into plain text.
+ *
+ * Entities are decoded twice on purpose: GLPI stores the markup escaped, so a
+ * first pass turns `<div>` into real tags that the tag stripper can
+ * remove, and a second pass decodes the entities that were inside the text.
+ */
+export declare function stripHtml(value: string): string;
+/** Fields whose content is richtext and should be flattened to plain text. */
+export declare const RICHTEXT_FIELDS: Set<string>;
+/**
+ * Richtext fields flattened for markdown: RICHTEXT_FIELDS plus the validation
+ * comments (v1 comment_submission / comment_validation, v2 submission_comment /
+ * approval_comment), which GLPI 11 also stores as HTML.
+ */
+export declare const MARKDOWN_RICHTEXT_FIELDS: Set<string>;
+/**
+ * Flattens richtext fields to plain text at any depth up to `maxDepth` nested
+ * objects/arrays. `pickFields` only flattens the top level, so the API v2
+ * timeline (`{type, item: {content: "<p>…</p>"}}`) reached the markdown table
+ * as raw HTML. Used for markdown only: the JSON result keeps nested fields as
+ * GLPI sent them. Returns a copy; the input is not modified.
+ */
+export declare function flattenRichtext(value: unknown, maxDepth?: number): unknown;
+/**
+ * Per-itemtype whitelists. Derived from real payloads: what is dropped for
+ * Ticket is the SLA/OLA block, the *_delay_stat counters and the HAL `links`.
+ */
+export declare const ESSENTIAL_FIELDS: Record<string, string[]>;
+export declare function pickFields(itemtype: string | undefined, obj: Record<string, unknown>, mode: FieldMode): Record<string, unknown>;
+/**
+ * Formats a whole payload. Objects and arrays of objects are filtered;
+ * anything else is returned untouched.
+ */
+export declare function formatPayload(itemtype: string | undefined, data: unknown, mode: FieldMode): unknown;
+/**
+ * Renders rows as a markdown table. Columns come from the union of the keys
+ * present, in first-seen order, so a sparse row does not lose its data.
+ * Long cells are cut at 80 characters: a table is for scanning a listing;
+ * open the item (or ask for JSON) to read a long text in full.
+ */
+export declare function toMarkdownTable(rows: Record<string, unknown>[]): string;
+/**
+ * One column of a conversational markdown view: `label` heads the column and
+ * `from` says where the value comes from — a key, a list of candidate keys
+ * (the first non-empty one wins) or a function of the row.
+ */
+export interface MarkdownColumn {
+    label: string;
+    from: string | readonly string[] | ((row: Record<string, unknown>) => unknown);
+}
+/** Projects a full row onto the columns of a view. */
+export type MarkdownView = (row: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Builds a view from a column list. A listing in markdown is read in a
+ * conversation: the 22 columns of a raw ticket row (bare IDs such as
+ * `users_id_lastupdater: 368` among them) bury the 8 a person scans for.
+ * The JSON result keeps every field; only the markdown table is projected.
+ */
+export declare function columnView(columns: readonly MarkdownColumn[]): MarkdownView;
+/** Renders a payload as markdown; falls back to JSON for non-tabular shapes. */
+export declare function renderMarkdown(data: unknown): string;