MCP-ALBERTO

MCP-ALBERTO: Fundamental Tools Server for AI

This project implements a Model Context Protocol (MCP) server designed to extend the capabilities of an AI assistant . It provides a set of fundamental, atomic tools that, while potentially of limited utility in isolation, are designed to be combined and orchestrated by an AI model to execute complex workflows and interact with specific external services (currently, a system called "ALBERTO" related to TotalCheck).

The goal is not to offer complex pre-packaged tools, but rather building blocks (primitives) that AI can dynamically use to solve tasks such as obtaining credentials, authenticating, and potentially interacting with other endpoints of the underlying service.

Execution Configuration (Example for Integration)

The following configuration (example) shows how this MCP could be integrated with a tool that uses it:

Project Structure

• main.ts : Application entry point. Initializes the MCP server, configures the transport (currently StdioServerTransport ), and registers available tools.
• userservice/ :
  • userservice-api-rest.ts : Contains the logic to interact with the user service REST API (e.g. getting authentication ticket).
  • userservice-tool.ts : Defines and registers MCP tools related to the user service (e.g. get_ticket ).
• README.md : This file.
• .gitignore : Specifies files and directories ignored by Git.
• package.json / package-lock.json : Managing Node.js project dependencies.
• tsconfig.json : TypeScript compiler configuration.

MCP Tools Available

This server exposes the following tools. It's crucial to understand that these tools are low-level building blocks . Their true potential is unlocked when an AI uses them in sequence or combination to achieve a larger goal.

• get_node_info
  • Description: Obtains detailed and complete information about a specific node in the system.
  • Implementation: nodeservice/nodeservice-tool.ts
  • Parameters: unique_id (string, required ), alf_ticket (string).
  • Use: Ideal when the exact unique_id of the node is known and all its details are needed.
• search_by_type
  • Description: Perform flexible searches by Tenant and Type in ElasticSearch, allowing you to find nodes based on various criteria.
  • Implementation: searchservice/by_type/tool.ts
  • Endpoint API: /searchservice/tenant/{tenant}/type/{type}/...
  • Parameters:
    • tenant_name (string, required ): The tenant to search in.
    • type_name (string, required ): The specific index/type to query (e.g. expediente_inscripcion_mt ).
    • query_body (string, required ): ElasticSearch query in JSON string format.
    • alf_ticket (string): Authentication ticket.
    • from_index (number, optional): Pagination.
    • page_size (number, optional): Pagination.
    • sort (string, optional): Sort.
  • Use: For searches directed to a specific index (files, users, etc.).
• search_workflow
  • Description: Performs flexible searches on the Workflow taskmanager alias in ElasticSearch.
  • Implementation: searchservice/workflow/tool.ts
  • Endpoint API: /searchservice/workflow/...
  • Parameters:
    • query_body (string, required ): ElasticSearch query in JSON string format.
    • alf_ticket (string): Authentication ticket.
    • from_index (number, optional): Pagination.
    • page_size (number, optional): Pagination.
  • Use: To find tasks or workflow information, useful as an intermediate step to discover unique_id or type_name of a case if only partial data is available (patent, operation).
• get_ticket
  • Description: Obtains an authentication ticket from the external login service.
  • Implementation: userservice/userservice-tool.ts
  • Parameters:
    • usuario (string): Username for authentication.
    • password (string): User password.
  • Returns: The authentication ticket as text.
• get_config_credentials
  • Description: Gets a predefined list of configuration credentials (user, key, description).
  • Implementation: configuraciones/configuraciones-tool.ts
  • Parameters: None.
  • Returns: An array of JSON objects, each with username , clave , and description .
  • Note: Provide the AI with the available identities to interact with the system.

Common Workflows

• Get Ticket with Configuration Credentials:
  1. Call get_config_credentials to get the preconfigured username and password.
  2. Extract the usuario and password from the JSON result.
  3. Call get_ticket passing the usuario and password obtained in the previous step.

AI Orchestration (Conceptual Example)

An AI assistant might receive a request such as "Get a ticket for the admin user." The AI, using available tools, would perform the following steps:

1. Call get_config_credentials : To get the list of users and their descriptions.
2. Identify User : Process the response to find the username corresponding to the description "Administrator User".
3. Call get_ticket : Use the identified username and its clave (implicit or extracted) to request the authentication ticket.
4. Present Result : Return the ticket obtained to the user.

This example illustrates how simple tools combine under the direction of AI to meet a complex need.

Interaction between Services and Elasticsearch

It is essential to understand how search_by_type , search_workflow , and get_node_info interact and how they relate to the data structure in Elasticsearch:

1. Primary Indexes: Each primary entity type (e.g., expediente_inscripcion_mt , expediente_operacion_leasing , user , tenant ) resides in its own ElasticSearch index. search_by_type can query these indexes directly by specifying the appropriate type_name .
2. Workflow Indexes ( taskmanager_* ): When a node enters a workflow, entries are generated in workflow-specific indexes (e.g. taskmanager_expediente_inscripcion_mt ).
3. Alias taskmanager : There's an alias called taskmanager that groups all workflow indexes. Using search_workflow or search_by_type allows you to search across all active tasks.
4. Typical Flow:
   • If the primary type is known, the AI will use search_by_type directly.
   • If general information is being sought or the exact type is unknown, the AI could use search_workflow (querying the alias taskmanager ) as a discovery step.
   • The result of search_workflow or search_by_type may contain the necessary information or the unique_id of the parent node.
   • If a unique_id is obtained and all the details are needed, the AI can use get_node_info .

Guide to AI: Minimum Search Conditions

To ensure relevant and efficient results, when constructing the query_body for search_by_type or search_workflow , the AI should apply the following minimum default conditions, unless the user request explicitly states otherwise:

• When querying Primary Indexes (e.g. expediente_* , user , tenant ):
  • Exclude deleted records. Include in the query:
    { "query": { "bool": { "must_not": [{ "term": { "deleted": true } }] } } }
    (Combine with other must , filter clauses as needed within the bool .)
• When querying the Alias taskmanager :
  • Include only active tasks and exclude deleted records.
  • Include in the query:
    { "query": { "bool": { "must": [{ "term": { "status": "active" } }], "must_not": [{ "term": { "deleted": true } }] } } }
    (Adjust the status field and its active value if the actual names differ; combine with other must , filter clauses.)

Key Technical Details

1- Additional configuration of package.json - "type": "module" : Enables the use of ES6 modules (import/export).

2- Important packages ( dependencies ) - @modelcontextprotocol/sdk : SDK for creating the MCP server. - zod : For schema validation (used in tool definition). - axios : HTTP client for making REST API calls. - tsx : For directly executing TypeScript files.

3- MCP Core Files - main.ts : Main orchestrator. - userservice/userservice-api-rest.ts : API call logic. - userservice/userservice-tool.ts : MCP tool definition.

Commands for Local Development

1. Install dependencies:
   npm install
2. Run the MCP server:
   npx tsx main.ts
   The server will start and wait for communication via stdio.