MCP-ALBERTO

MCP-ALBERTO：人工智能基础工具服务器

该项目实现了一个模型上下文协议（MCP）服务器，旨在扩展人工智能助手的功能。它提供了一组基本的原子工具，虽然它们单独使用时效性有限，但旨在**通过 AI 模型进行组合和编排，**以执行复杂的工作流程并与特定的外部服务进行交互（目前是与 TotalCheck 相关的名为“ALBERTO”的系统）。

目标不是提供复杂的预打包工具，而是提供 AI 可以动态使用的**构建块（原语），**以解决诸如获取凭据、进行身份验证以及可能与底层服务的其他端点交互等任务。

执行配置（集成示例）

以下配置（示例）显示了如何将此 MCP 与使用它的工具集成：

项目结构

• main.ts ：应用程序入口点。初始化 MCP 服务器，配置传输（当前为StdioServerTransport ），并注册可用的工具。
• userservice/ ：
  • userservice-api-rest.ts ：包含与用户服务 REST API 交互的逻辑（例如获取身份验证票证）。
  • userservice-tool.ts ：定义并注册与用户服务相关的 MCP 工具（例如get_ticket ）。
• README.md ：此文件。
• .gitignore ：指定 Git 忽略的文件和目录。
• package.json / package-lock.json ：管理 Node.js 项目依赖项。
• tsconfig.json ：TypeScript 编译器配置。

MCP 工具可用

该服务器公开以下工具。至关重要的是要理解这些工具是低级构建块。当人工智能按顺序或组合使用它们来实现更大的目标时，它们的真正潜力就会被释放。

• get_node_info
  • **描述：**获取系统中特定节点的详细完整信息。
  • 实现： nodeservice/nodeservice-tool.ts
  • 参数： unique_id （字符串，必需）， alf_ticket （字符串）。
  • **用途：**当知道节点的确切unique_id并且需要其所有详细信息时，这是理想的选择。
• search_by_type
  • 描述：在 ElasticSearch 中按租户和类型执行灵活的搜索，允许您根据各种条件查找节点。
  • 实现： searchservice/by_type/tool.ts
  • 端点 API： /searchservice/tenant/{tenant}/type/{type}/...
  • 参数：
    • tenant_name (字符串，必需)：要搜索的租户。
    • type_name (字符串，必需)：要查询的特定索引/类型（例如expediente_inscripcion_mt ）。
    • query_body （字符串，必需）：JSON 字符串格式的 ElasticSearch 查询。
    • alf_ticket （字符串）：身份验证票。
    • from_index （数字，可选）：分页。
    • page_size （数字，可选）：分页。
    • sort （字符串，可选）：排序。
  • **用途：**针对特定索引（文件、用户等）的搜索。
• search_workflow
  • 描述：在 ElasticSearch 中对工作流taskmanager别名执行灵活搜索。
  • 实现： searchservice/workflow/tool.ts
  • 端点 API： /searchservice/workflow/...
  • 参数：
    • query_body （字符串，必需）：JSON 字符串格式的 ElasticSearch 查询。
    • alf_ticket （字符串）：身份验证票。
    • from_index （数字，可选）：分页。
    • page_size （数字，可选）：分页。
  • **用途：**查找任务或工作流信息，如果只有部分数据可用（专利、操作），则可用作发现案例的unique_id或type_name的中间步骤。
• get_ticket
  • **描述：**从外部登录服务获取身份验证票证。
  • 实现： userservice/userservice-tool.ts
  • 参数：
    • usuario （字符串）：用于身份验证的用户名。
    • password （字符串）：用户密码。
  • **返回：**文本形式的身份验证票证。
• get_config_credentials
  • **描述：**获取配置凭证的预定义列表（用户、密钥、描述）。
  • 实现： configuraciones/configuraciones-tool.ts
  • **参数：**无。
  • 返回： JSON 对象数组，每个对象包含username 、 clave和description 。
  • **注：**向AI提供可用的身份，以便与系统进行交互。

常见工作流程

• 获取带有配置凭证的票证：
  1. 调用get_config_credentials获取预先配置的用户名和密码。
  2. 从 JSON 结果中提取usuario和password 。
  3. 调用get_ticket并传递上一步获得的usuario和password 。

AI 编排（概念示例）

人工智能助手可能会收到诸如“为管理员用户获取票证”之类的请求。人工智能将利用可用的工具执行以下步骤：

1. 调用get_config_credentials ：获取用户列表及其描述。
2. 识别用户：处理响应以找到与描述“管理员用户”相对应的username 。
3. 调用get_ticket ：使用已识别的username及其clave （隐式或提取的）来请求身份验证票证。
4. 呈现结果：将获取到的票返回给用户。

这个例子说明了简单的工具如何在人工智能的指导下结合起来以满足复杂的需求。

服务与 Elasticsearch 之间的交互

必须理解search_by_type 、 search_workflow和get_node_info如何交互以及如何与 Elasticsearch 中的数据结构关联：

1. **主索引：**每个主要实体类型（例如expediente_inscripcion_mt 、 expediente_operacion_leasing 、 user 、 tenant ）都驻留在其自己的 ElasticSearch 索引中。 search_by_type可以通过指定适当的type_name直接查询这些索引。
2. **工作流索引（ taskmanager_* ）：**当节点进入工作流时，会在工作流特定的索引中生成条目（例如taskmanager_expediente_inscripcion_mt ）。
3. **别名taskmanager ：**有一个名为taskmanager的别名，它将所有工作流索引进行分组。使用search_workflow或search_by_type允许您搜索所有活动任务。
4. 典型流程：
   • 如果知道主要类型，AI将直接使用search_by_type 。
   • 如果正在寻找一般信息或确切类型未知，AI 可以使用search_workflow （查询别名taskmanager ）作为发现步骤。
   • search_workflow或search_by_type的结果可能包含必要的信息或父节点的unique_id 。
   • 如果获得了unique_id并且需要所有详细信息，AI可以使用get_node_info 。

人工智能指南：最低搜索条件

为了确保相关且有效的结果，在构建search_by_type或search_workflow的query_body时，AI 应应用以下最低默认条件，除非用户请求明确另有说明：

• 查询主索引时（例如expediente_* 、 user 、 tenant ）：
  • 排除已删除的记录。包含在查询中：
    { "query": { "bool": { "must_not": [{ "term": { "deleted": true } }] } } }
    （根据需要与bool内的其他must 、 filter子句相结合。）
• 查询Alias taskmanager时：
  • 仅包括活动任务并排除已删除的记录。
  • 包含在查询中：
    { "query": { "bool": { "must": [{ "term": { "status": "active" } }], "must_not": [{ "term": { "deleted": true } }] } } }
    （如果实际名称不同，则调整status字段及其active值；与其他must``filter子句结合使用。）

关键技术细节

1- package.json的附加配置- "type": "module" ：允许使用 ES6 模块（导入/导出）。

2-重要包（ dependencies ） - @modelcontextprotocol/sdk ：用于创建 MCP 服务器的 SDK。 - zod ：用于模式验证（用于工具定义）。 - axios ：用于调用 REST API 的 HTTP 客户端。 - tsx ：直接执行 TypeScript 文件。

3- MCP 主文件- main.ts ：主编排器。 - userservice/userservice-api-rest.ts ：API调用逻辑。 - userservice/userservice-tool.ts ：MCP 工具的定义。

本地开发命令

1. 安装依赖项：
   npm install
2. 运行 MCP 服务器：
   npx tsx main.ts
   服务器将启动并等待通过 stdio 进行通信。