NexTool MCP for GLPI

NexTool MCP for GLPI

将 Claude 和其他 MCP 客户端连接到 GLPI。一个 MCP 服务支持两种 GLPI API；每个工具系列都使用各自的凭据启用：

系列	API	工具	启用方式
glpi_*	经典 REST（apirest.php）或 api.php/v1 — GLPI 9.5、10 和 11	111	GLPI_URL + GLPI_USER_TOKEN（+ GLPI_APP_TOKEN）
glpi_v2_*	基于 OAuth2 的高级 API v2 — GLPI 11	55	GLPI_V2_URL + GLPI_V2_CLIENT_ID/SECRET + GLPI_V2_USERNAME/PASSWORD

在 2.x 之前，v2 系列是一个单独的软件包（mcp-glpi-v2）；从 3.0.0 起，它包含在本项目中，工具名称和架构保持不变。两个系列共用以下写入策略、载荷格式和创建幂等机制。

与 Teclib' 无关联。GLPI 是 Teclib' 的注册商标。

工具选择。 GLPI_TOOLSETS 用于选择命名预设（tickets,kb；参见 工具集）；GLPI_TOOLS_INCLUDE / GLPI_TOOLS_EXCLUDE 接受以逗号分隔的工具名称 glob （glpi_*ticket*,glpi_search、*webhook*）。工具集和包含 glob 的效果会累加； 排除项始终优先；若既未指定工具集也未指定包含 glob，则会注册所有工具。未知的工具集名称会导致启动失败。工具越少，每个会话占用的上下文就越少。

多个实例可通过不同的环境文件共用这个二进制文件。

两种运行方式

入口	传输方式	实例	身份验证
dist/index.js（mcp-glpi）	stdio	一个，来自环境变量	无（本地进程）
dist/http.js（mcp-glpi-http）	Streamable HTTP，/mcp/<instance>	多个，来自 MCP_INSTANCES_FILE	Authorization: Bearer <key>，必需

HTTP 入口旨在从一个位置为所有 NexTool 环境提供服务。密钥只能访问获准使用的实例；会话会绑定到创建它的密钥和实例；GLPI 会话、OAuth 令牌和目录缓存按凭据隔离；创建操作的幂等机制则按实例在会话间共享。每个请求都会向 stdout 写入一行 JSON 审计日志（密钥、实例、方法、工具；绝不记录参数或凭据）。 GET /healthz 无需身份验证即可响应。

实例文件中只存储密钥的 SHA-256 哈希值（权限模式为 600；文件变更时会重新读取）：

{
  "instances": {
    "acme": { "env": { "GLPI_URL": "https://glpi.acme.example", "GLPI_USER_TOKEN": "…", "GLPI_APP_TOKEN": "…" } }
  },
  "keys": [{ "name": "laptop", "sha256": "<sha256 hex of the key>", "instances": ["acme"] }]
}

KEY=$(openssl rand -hex 32)                       # give it to the client once
printf %s "$KEY" | sha256sum | cut -d' ' -f1      # goes into "sha256"
MCP_INSTANCES_FILE=instances.json MCP_HTTP_PORT=8787 npx mcp-glpi-http

可通过 NexTool 门户登录的托管多租户版本现已推出，网址为 https://mcp.nextoolsolutions.com/mcp。

其他变量：MCP_HTTP_HOST（默认值为 127.0.0.1）、MCP_ALLOWED_HOSTS（Host 标头允许列表）、 MCP_SESSION_IDLE_MIN（默认值为 30）。文件变更时会重新读取。

提供的功能

• 111 个 API v1 工具（60 个读取 / 42 个写入 / 9 个破坏性操作），涵盖工单、变更、问题、统一时间线、审批、资产和预订、webhook、用户、组、实体、文档、知识库、规则和搜索。

• 4 个资源（glpi://entities、glpi://itil-categories、glpi://request-types、 glpi://code-maps），无需调用工具即可查询目录。

• 4 个提示词，用于分诊、重复问题调查、请求者历史记录和资产上下文。只有在提示词中提及的所有工具都已注册时，才会提供该提示词（使用 GLPI_TOOLSETS=kb 时不会提供任何提示词）。

• 55 个 API v2 工具（glpi_v2_*）：实体、ITIL（含团队成员和时间线）、用户、组、知识库、下拉列表、文档、规则、会话和健康检查。

列出工单

需求	工具	默认值
“我的工单”（已连接用户的工单）	glpi_list_my_tickets	仅未关闭工单，按最近更新时间排序，任意角色
整个实例中的工单	glpi_list_tickets	所有状态，按最近更新时间排序
任意条件	glpi_search	GLPI 搜索顺序

• glpi_list_my_tickets：role（any | requester | assigned | observer）、status、 sort、order、range、users_id（其他用户；默认使用 getFullSession 中的会话用户）。行包含 {id, name} 格式的 requesters / assigned / observers、requester_groups、assigned_groups、status_name、type_name 和 my_roles；结果 还包含 total 和 user。
• glpi_list_tickets：新增 status、sort 和 order（旧的 range 和 expand_dropdowns 仍然有效）。使用状态筛选时，结果还包含 total。行包含 status_name、type_name、priority_name、category_name 和 {id, name} 格式的 requesters / assigned（每 50 个工单搜索一次，而非每个工单调用一次）。
• status 可接受单个名称或列表：new、assigned（即 processing）、planned、pending、 solved、closed 和 open（即新建 + 已分配 + 已计划 + 待处理，GLPI 的“未归档”）。
• sort：date_mod（默认）、date、id、priority、status、name、solvedate、 closedate；order：desc（默认）或 asc。
• glpi_v2_list_tickets 接受相同的 status 名称，默认按 date_mod:desc 排序。 v2 API 无法按团队筛选（GLPI 11.0.7 会忽略或拒绝 team 筛选条件），因此 “我的工单”使用 v1 工具。
• glpi_list_changes / glpi_list_problems（以及 v2 版本）也默认按最近更新时间排序。

ID 旁的名称

子项保留其 ID，并添加名称：glpi_list_ticket_users（user_name、type_name）、 glpi_list_ticket_groups（group_name、type_name）、跟进项（user_name）、任务 （user_name、tech_name、tech_group_name）、审批（user_name、validator_name、 status_name）、glpi_list_timeline（以上所有字段，以及解决方案中的 solutiontype_name 和 user_name_approval）、glpi_get_ticket（recipient_name、category_name、 entity_name、requesttype_name、location_name、status_name、type_name、priority_name、 urgency_name、impact_name）、问题和变更（category_name、status_name、 priority_name；单项还包括人员和实体），以及 glpi_list_assets （location_name、state_name、user_name）。名称通过 GET // 读取，并按凭证缓存 5 分钟；用户无权读取的名称会保留为 null。

代码标签（*_status、type_name、priority_name……）使用 GLPI 会话语言（getFullSession → glpilanguage），并按凭证缓存；pt_BR、pt_PT、es_ES、fr_FR、it_IT 和 de_DE 均有对应表（取自 GLPI 11 的 locales/*.po），区域变体使用其语言系列（es_MX → es_ES），其他情况使用 GLPI 的英文。 3.5.0 之前，v1 工具始终以英文回答（“Solved”），而 v2 工具则使用 GLPI 语言回答 （“Solucionado”）。

API v2 会标注状态本身，但优先级、紧急度、影响和工单类型以数字形式返回。从 3.5.1 起，v2 工单／变更／问题工具会在代码旁添加 priority_name、urgency_name、impact_name（工单还会添加 type_name），所用语言与 API 返回的状态标签所对应的状态表一致（v2 会话不包含语言）；时间线会为审批和解决方案添加 status_name，为任务添加 state_name，语言按凭证缓存（或从一张工单读取）。无法匹配时使用英文。

默认情况下，自 3.5.0 起，glpi_search 会用 GLPI 用户语言中的搜索选项名称作为行键（"Título"、 "Status"、"Última atualização"）；named_columns: false 则返回数字选项 ID（"1"、"12"、"19"）。自 3.5.1 起，编码列（状态、优先级、紧急度、影响、工单类型、审批和解决方案审批状态）会以会话语言显示标签，代码则放在旁边的 "<name> (id)" 列中："Status": "Solucionado", "Status (id)": 5。 只有当搜索选项指向已知表／字段时，列才会显示标签；Markdown 表格会省略 (id) 列，而 named_columns: false 仍返回原始搜索结果。

完整参考文档：docs/TOOLS.md（v1）和 docs/v2/TOOLS.md（v2）； OAuth2 设置见 docs/v2/SETUP.md。

工具集

GLPI_TOOLSETS 的命名预设（或 instanceFromConfig 的 toolsets 选项）。领域预设同时包含两个系列；系列仍需要凭据才能注册。一个工具可以属于多个预设，且每个工具至少属于除 core 以外的一个预设（由测试断言）。core 是面向托管场景的精简默认预设：包含日常预设中的所有读取工具（不含 webhook、规则或会话内部工具），以及非破坏性的工单操作。

预设是自包含的（由测试断言）：如果某个工具的描述或参数中提到了另一个工具，那么包含前者的每个预设也都包含后者。这就是为什么 tickets 包含 glpi_search / glpi_list_search_options，以及能显示人员姓名的用户/群组读取工具；而 assets 包含其列表工具所指向的通用搜索工具。

预设	工具（v1 + v2）	内容
core	93（59 + 34）	工单/itil/资产/知识库/文档/用户/搜索读取 + 实体和人员读取，另含创建/更新工单、后续跟进、解决方案、任务、验证和参与者
tickets	53（33 + 20）	工单生命周期，包括我的工单，以及搜索和用户/群组读取
itil	46（24 + 22）	问题和变更、共享时间线和类别、用户/群组读取
assets	15（14 + 1）	资产、预订、位置、通用搜索
kb	16（10 + 6）	知识库
documents	12（8 + 4）	文档和文档链接
users	10（5 + 5）	用户和群组读取
search	3（3 + 0）	通用搜索、计数、搜索选项
admin	55（37 + 18）	GLPI 管理：创建/更新用户和群组、实体、会话/配置文件、规则、后续跟进模板、webhook（另含用户/群组读取）
v2	55（0 + 55）	所有 glpi_v2_* 工具

**仅在 admin 中提供写入操作的管理功能（3.5.0，所有者决定）：**创建或修改用户和群组、实体、业务规则及 webhook，不属于 core，也不属于任何日常预设（tickets、itil、assets、kb、documents、users、search）；有助于处理工单的读取功能（用户、群组、实体）仍保留。v2 预设包含整个系列，因此仍包含这些工具。由测试断言（ADMIN_WRITE_TOOLS、EVERYDAY_TOOLSETS）。

3.5.0 之前：users 为 15（7 + 8），admin 为 42（31 + 11）。3.4.0 之前：core 为 92，tickets 为 42，itil 为 38，assets 为 13。

各预设中的工具

#### core（93：59 个 v1 + 34 个 v2） 精简默认配置：包含日常预设中的所有读取工具，以及非破坏性的工单操作

v1：glpi_list_tickets、glpi_list_my_tickets、glpi_get_ticket、glpi_list_followups、glpi_list_timeline、glpi_list_ticket_validations、glpi_list_ticket_users、glpi_list_ticket_groups、glpi_list_ticket_tasks、glpi_get_ticket_stats、glpi_list_itil_categories、glpi_get_itil_category、glpi_list_itil_followup_templates、glpi_get_itil_followup_template、glpi_list_changes、glpi_get_change、glpi_list_change_followups、glpi_list_change_tasks、glpi_list_problems、glpi_get_problem、glpi_list_problem_followups、glpi_list_problem_tasks、glpi_list_assets、glpi_get_asset、glpi_get_asset_details、glpi_list_reservation_items、glpi_list_reservations、glpi_get_reservation、glpi_list_locations、glpi_get_location、glpi_list_knowbase_items、glpi_get_knowbase_item、glpi_list_knowbase_categories、glpi_get_knowbase_category、glpi_list_documents、glpi_get_document、glpi_list_document_items、glpi_get_document_item、glpi_get_user、glpi_search_user_by_email、glpi_list_users、glpi_list_groups、glpi_get_group、glpi_search、glpi_count_items、glpi_list_search_options、glpi_list_entities、glpi_get_entity、glpi_get_my_entities、glpi_get_my_profiles、glpi_create_ticket、glpi_update_ticket、glpi_add_followup、glpi_add_solution、glpi_create_ticket_validation、glpi_update_ticket_validation、glpi_add_ticket_user、glpi_add_ticket_group、glpi_add_ticket_task

v2：glpi_v2_list_tickets、glpi_v2_get_ticket、glpi_v2_list_timeline、glpi_v2_list_team_members、glpi_v2_list_itil_categories、glpi_v2_get_itil_category、glpi_v2_list_request_types、glpi_v2_list_changes、glpi_v2_get_change、glpi_v2_list_problems、glpi_v2_get_problem、glpi_v2_list_locations、glpi_v2_list_kb_articles、glpi_v2_get_kb_article、glpi_v2_list_kb_categories、glpi_v2_get_kb_category、glpi_v2_list_documents、glpi_v2_get_document、glpi_v2_download_document、glpi_v2_list_users、glpi_v2_get_user、glpi_v2_get_me、glpi_v2_list_groups、glpi_v2_get_group、glpi_v2_list_entities、glpi_v2_get_entity、glpi_v2_create_ticket、glpi_v2_update_ticket、glpi_v2_add_followup、glpi_v2_add_solution、glpi_v2_add_task、glpi_v2_add_validation、glpi_v2_update_validation、glpi_v2_add_team_member

tickets（53：33 个 v1 + 20 个 v2）

工单生命周期（我的工单、跟进、解决方案、任务、验证、参与者、时间线），以及其关联的搜索和用户／群组读取工具

v1：glpi_list_tickets、glpi_list_my_tickets、glpi_get_ticket、glpi_create_ticket、glpi_update_ticket、glpi_add_followup、glpi_list_followups、glpi_add_solution、glpi_list_timeline、glpi_list_ticket_validations、glpi_create_ticket_validation、glpi_update_ticket_validation、glpi_delete_ticket_validation、glpi_list_ticket_users、glpi_add_ticket_user、glpi_delete_ticket_user、glpi_list_ticket_groups、glpi_add_ticket_group、glpi_delete_ticket_group、glpi_list_ticket_tasks、glpi_add_ticket_task、glpi_get_ticket_stats、glpi_list_itil_categories、glpi_get_itil_category、glpi_list_itil_followup_templates、glpi_get_itil_followup_template、glpi_search、glpi_list_search_options、glpi_get_user、glpi_search_user_by_email、glpi_list_users、glpi_get_group、glpi_list_groups

v2：glpi_v2_list_tickets、glpi_v2_get_ticket、glpi_v2_create_ticket、glpi_v2_update_ticket、glpi_v2_delete_ticket、glpi_v2_list_timeline、glpi_v2_add_followup、glpi_v2_add_solution、glpi_v2_add_task、glpi_v2_add_validation、glpi_v2_update_validation、glpi_v2_list_team_members、glpi_v2_add_team_member、glpi_v2_remove_team_member、glpi_v2_list_itil_categories、glpi_v2_get_itil_category、glpi_v2_list_request_types、glpi_v2_get_user、glpi_v2_get_me、glpi_v2_get_group

itil（46：24 个 v1 + 22 个 v2）

问题和变更（以及共享的 ITIL 时间线和类别，还有用户／组读取功能）

v1：glpi_list_changes、glpi_get_change、glpi_create_change、glpi_update_change、glpi_list_change_followups、glpi_add_change_followup、glpi_add_change_solution、glpi_list_change_tasks、glpi_list_problems、glpi_get_problem、glpi_create_problem、glpi_update_problem、glpi_list_problem_followups、glpi_add_problem_followup、glpi_add_problem_solution、glpi_list_problem_tasks、glpi_list_timeline、glpi_list_itil_categories、glpi_get_itil_category、glpi_get_user、glpi_search_user_by_email、glpi_list_users、glpi_get_group、glpi_list_groups

v2：glpi_v2_list_changes、glpi_v2_get_change、glpi_v2_create_change、glpi_v2_update_change、glpi_v2_list_problems、glpi_v2_get_problem、glpi_v2_create_problem、glpi_v2_update_problem、glpi_v2_list_timeline、glpi_v2_add_followup、glpi_v2_add_solution、glpi_v2_add_task、glpi_v2_add_validation、glpi_v2_update_validation、glpi_v2_list_team_members、glpi_v2_add_team_member、glpi_v2_remove_team_member、glpi_v2_list_itil_categories、glpi_v2_get_itil_category、glpi_v2_get_user、glpi_v2_get_me、glpi_v2_get_group

assets（15：14 个 v1 + 1 个 v2）

资产、预订和位置（以及通用搜索）

v1：glpi_list_assets、glpi_get_asset、glpi_get_asset_details、glpi_create_asset、glpi_update_asset、glpi_list_reservation_items、glpi_list_reservations、glpi_get_reservation、glpi_create_reservation、glpi_update_reservation、glpi_list_locations、glpi_get_location、glpi_search、glpi_list_search_options

v2：glpi_v2_list_locations

kb（16：10 个 v1 + 6 个 v2）

知识库文章和类别

v1：glpi_list_knowbase_items、glpi_get_knowbase_item、glpi_create_knowbase_item、glpi_update_knowbase_item、glpi_delete_knowbase_item、glpi_list_knowbase_categories、glpi_get_knowbase_category、glpi_create_knowbase_category、glpi_update_knowbase_category、glpi_delete_knowbase_category

v2：glpi_v2_list_kb_articles、glpi_v2_get_kb_article、glpi_v2_create_kb_article、glpi_v2_update_kb_article、glpi_v2_list_kb_categories、glpi_v2_get_kb_category

documents（12：8 个 v1 + 4 个 v2）

文档及其与项目的关联

v1：glpi_list_documents、glpi_get_document、glpi_create_document、glpi_delete_document、glpi_list_document_items、glpi_get_document_item、glpi_create_document_item、glpi_delete_document_item

v2：glpi_v2_list_documents、glpi_v2_get_document、glpi_v2_create_document、glpi_v2_download_document

users（10：5 个 v1 + 5 个 v2）

用户和组读取功能（创建或更改用户和组的功能位于 admin 中）

v1：glpi_get_user、glpi_search_user_by_email、glpi_list_users、glpi_list_groups、glpi_get_group

v2：glpi_v2_list_users、glpi_v2_get_user、glpi_v2_get_me、glpi_v2_list_groups、glpi_v2_get_group

search（3：3 个 v1 + 0 个 v2）

通用搜索、计数和搜索选项

v1：glpi_search、glpi_count_items、glpi_list_search_options

管理（55：37 个 v1 + 18 个 v2）

GLPI 管理：用户和群组（创建/更新）、实体、会话/配置文件上下文、业务规则、跟进模板、Webhook

v1：glpi_list_entities、glpi_get_entity、glpi_get_my_entities、glpi_get_my_profiles、glpi_list_users、glpi_get_user、glpi_list_groups、glpi_get_group、glpi_create_entity、glpi_update_entity、glpi_delete_entity、glpi_change_active_entities、glpi_get_full_session、glpi_list_rules、glpi_get_rule_ticket、glpi_list_rule_ticket_criteria、glpi_list_rule_ticket_actions、glpi_list_rule_criteria、glpi_list_rule_actions、glpi_create_rule_ticket、glpi_create_rule_criteria、glpi_create_rule_action、glpi_update_rule_action、glpi_list_itil_followup_templates、glpi_get_itil_followup_template、glpi_create_itil_followup_template、glpi_update_itil_followup_template、glpi_list_webhooks、glpi_get_webhook、glpi_create_webhook、glpi_update_webhook、glpi_set_webhook_active、glpi_delete_webhook、glpi_list_webhook_deliveries、glpi_retry_webhook_delivery、glpi_create_user、glpi_update_user

v2：glpi_v2_list_entities、glpi_v2_get_entity、glpi_v2_list_users、glpi_v2_get_user、glpi_v2_list_groups、glpi_v2_get_group、glpi_v2_create_entity、glpi_v2_update_entity、glpi_v2_delete_entity、glpi_v2_list_rule_collections、glpi_v2_list_rules、glpi_v2_get_rule、glpi_v2_create_rule、glpi_v2_get_session、glpi_v2_health_check、glpi_v2_create_user、glpi_v2_update_user、glpi_v2_create_group

v2（55：0 个 v1 + 55 个 v2）

所有 GLPI 11 API v2 工具（glpi_v2_*）

作为库使用

包根目录导出服务器工厂；导入该包不会启动传输（stdio 和 HTTP 服务器分别是 mcp-glpi 和 mcp-glpi-http 可执行文件）。

import { createGlpiServer, instanceFromConfig } from "@nextoolsolutions/mcp-glpi";

const instance = instanceFromConfig({
  id: "acme",                                   // lowercase letters, digits, "-"
  v1: { url: "https://glpi.acme.com", userToken, appToken },
  v2: { url: "https://glpi.acme.com", clientId, clientSecret, username, password, scope: "api", apiVersion: "v2.2" },
  policy: { readOnly: true, allowDelete: false }, // defaults: false / false / requireDeleteReason true
  toolsets: ["core"],                           // or "tickets,kb"
  toolsInclude: ["glpi_search"],                // globs, add to toolsets
  toolsExclude: ["*delete*"],                   // globs, always win
  fetchImpl,                                    // optional, see below
});
const { server, summary } = createGlpiServer(instance, { fetchImpl, idempotencyStore });
await server.connect(transport);

instanceFromConfig 不会读取 process.env；遇到无效 ID 或 URL、未知工具集，或未指定 v1 和 v2 时会抛出异常。instanceFromEnv(id, env) 会根据 GLPI_* 变量构建相同对象。还会导出：SERVER_VERSION、InstanceConfig / InstanceEnv / InstanceOptions 类型、TOOLSETS / TOOLSET_NAMES / parseToolsets、错误类（GlpiHttpError、GlpiApiError、GlpiV2ApiError、GlpiRedirectError、GlpiPolicyError）以及 IdempotencyStore。

fetchImpl。 调用形式与 fetch 相同（(url, init) => Promise<Response>），用于所有 GLPI 请求：v1 会话和调用、v2 令牌和调用、资源及 Webhook。宿主可以注入一个会验证解析后 IP 的实现。它始终会收到 redirect: "manual"。

安全默认设置

• 除非设置 GLPI_ALLOW_DELETE=true，否则破坏性工具默认关闭，且需要提供书面 reason。
• GLPI_READ_ONLY=true 会在写入请求到达 GLPI 前拦截所有写入操作——请在客户实例上设置。
• 每个工具都会根据名称发布 MCP 注释：title、readOnlyHint（读取）、destructiveHint（删除/清除/移除）、idempotentHint（读取、update_*/set_*、删除）和 openWorldHint: false。
• 绝不跟随重定向：GLPI 返回 3xx 时会变为 redirect not followed: <status> -> <host>（GlpiRedirectError），因此会话和 OAuth 标头绝不会发送到其他主机。
• v2 客户端只会与 GLPI_V2_URL 的源通信；请求发出前会拒绝任何指向其他主机的绝对 URL。
• 在 120 秒内使用相同参数重复调用 create_/add_，会重放首次结果（replayed: true），而不是创建第二条记录。

载荷

读取工具默认使用 fields: "essential"：GLPI 的内部记账信息（SLA/OLA 计数器、延迟统计、HAL 链接；API v2 时长）会被舍弃，TinyMCE 富文本会被转换为纯文本。传入 fields: "all" 可获取原始载荷。

format: "markdown" 会为列表返回表格，为单个条目返回 键：值 行（长文本不会在此处截断）。Markdown 内容既在文本块中，也在 structuredContent（{ data: "<markdown>", format: "markdown", count, note }）中：支持结构化结果的客户端（包括 Claude）会向模型提供 structuredContent，因此在 3.4.0 之前，仅文本的呈现结果会被忽略。JSON 仍是默认格式。

列表中的表格较为紧凑（3.5.0）：原始工单行有 22 列，其中包括单独的 ID，因此每种列表都有自己的列集合（src/markdown-views.ts）：

列表	列
工单（glpi_list_tickets、glpi_list_my_tickets、glpi_v2_list_tickets）	id、标题、状态、类别、请求者、技术人员、优先级、更新时间
问题、变更（v1 和 v2）	id、标题、状态、类别、（v2：技术人员）、优先级、更新时间
时间线（glpi_list_timeline、glpi_v2_list_timeline）	类型、id、日期、作者、摘要——每个条目占一行（审批：状态 → 审批人 · 评论）
跟进 / 任务	id、日期、作者、（任务：技术人员）、私有、摘要
资产	id、名称、序列号、库存编号、状态、位置、用户、更新时间
用户（v1 和 v2）	id、登录名、姓名、启用状态、上次登录时间
知识库文章（v1 和 v2）	id、标题、（v2：类别）、FAQ、浏览量、更新时间

JSON 结果会保留所有字段，fields: "all" 也会在 Markdown 中显示所有列。

说明

initialize 中发送的 instructions 根据服务实际注册的工具生成：在预设（或 GLPI_TOOLS_EXCLUDE）下，其中只会列出已注册的工具，所列领域也仅涵盖已注册工具支持的内容。DEFAULT_INSTRUCTIONS 是包含两个系列全部工具的服务所用文本；buildInstructions(tools, { v1, v2 }) 可为任意工具集合生成说明；宿主可通过 createGlpiServer(instance, { instructions }) 替换这些说明。

列表受数量和大小限制：

• 默认 25 项，每次调用最多 100 项（GLPI_DEFAULT_PAGE_SIZE、GLPI_MAX_PAGE_SIZE； 上限原为 200 项）；
• 列表中超过 300 个字符的文本会被截断（GLPI_LIST_TEXT_MAX_CHARS）；打开条目或传入 fields: "all" 可获取完整文本。工单历史列表（时间线、 跟进、任务、审批）不会截断；
• 单个响应不超过 50,000 个字符（GLPI_MAX_RESPONSE_CHARS）：更长的列表会从末尾开始 截断。

note 会说明发生了什么以及如何获取下一页，并且只会列出该工具自身的参数（Next page: range=68-135. 或 Next page: start=33 limit=33.）。

条目 ID 必须是正整数（数字或由数字组成的字符串；实体 ID 可以为 0）。其他任何值（"abc"、""、-1、1.5）都会在发起请求前通过输入验证时报错：此前，无效 ID 会用于访问 GLPI 的 /ITILCategory/abc，而该接口会返回集合的第一页。

错误会以 isError 返回，文本中包含 GLPI 消息，且不包含 structuredContent（校验客户端会根据输出架构进行检查，并用架构错误替换该消息）。

目录结构

• src/lib.ts — 库入口（包根目录）：createGlpiServer、instanceFromConfig、类型
• src/index.ts — stdio 入口（从环境变量获取一个实例）
• src/http.ts — HTTP 入口：身份验证、实例绑定、会话、审计
• src/create-server.ts — 为一个实例构建服务：安全层、工具系列、资源
• src/instance.ts — 从环境变量或对象读取实例配置（凭据、策略、工具选择）和凭据缓存键
• src/tools-v1.ts、src/tools-v2.ts — 按系列注册工具
• src/tool-filter.ts — 选择规则（工具集 + GLPI_TOOLS_INCLUDE / GLPI_TOOLS_EXCLUDE）
• src/toolsets.ts — 命名预设（GLPI_TOOLSETS）
• src/glpi-client.ts — API v1 客户端（工单、ITIL、用户、知识库、规则、时间线）
• src/glpi-v2-client.ts — API v2 客户端（带令牌缓存的 OAuth2 密码授权）
• src/assets-client.ts — 资产、预订、清点
• src/webhooks-client.ts — Webhook 和投递队列（GLPI 10.0.7+）
• src/ticket-lists.ts — glpi_list_tickets 排序／状态筛选和 glpi_list_my_tickets
• src/names.ts — ID 对应的名称（缓存查询）和代码标签
• src/labels.ts — 按 GLPI 语言区分的代码标签，以及会话（用户 + 语言）缓存
• src/markdown-views.ts — 按列表类型显示的精简 Markdown 列
• src/instructions.ts — 根据已注册的工具构建的 instructions
• src/search-columns.ts — glpi_search 的搜索选项名称（named_columns，默认开启）及其编码列的标签
• src/ids.ts — 项目 ID 架构
• src/resources.ts、src/prompts.ts — MCP 资源和提示词
• test/ — npm test（node --test，无额外依赖）

共享基础设施——带重试的 HTTP 传输、写入策略、负载格式化、分页和幂等性——位于 @nextoolsolutions/mcp-glpi-core，并声明为 semver 依赖（^1.3.0）。

开发

在此仓库中，core 会解析到同级目录：锁文件将 node_modules/@nextoolsolutions/mcp-glpi-core 链接到 ../mcp-glpi-core，且 npm 接受该链接， 因为该文件夹的版本符合 ^1.3.0。因此请先构建 core：

(cd ../mcp-glpi-core && npm ci && npm run build)   # the server loads the core's dist/
npm ci
npm test
npx tsc --noEmit
npx tsx src/index.ts     # needs GLPI_URL/GLPI_USER_TOKEN and/or the GLPI_V2_* variables

• 编辑 mcp-glpi-core 后，请重新构建它（在该目录中运行 npm run build）。
• 如果更改需要新的 core 版本，请先升级 core，再更新此处的版本范围，然后运行 npm install（它会保留链接并更新锁文件）。
• 如果 core 文件夹的版本不符合版本范围，npm ci 会回退到 npm 注册表。要手动建立链接：npm install ../mcp-glpi-core --no-save（或 npm link）。
• 发布顺序：先发布 @nextoolsolutions/mcp-glpi-core，再发布此包。