Vietnamese Water Utility API

🚀 MCP API Service

The MCP API Service is an intermediate server that operates on the Model Context Protocol (MCP) communication protocol. It facilitates the connection between clfude AI and various internal system APIs. This system performs the following functions:

• Receive commands from clfude: When a user requests a task, clfude sends instructions.
• Process and transform commands: MCP converts clfude's requests into a format acceptable to the internal system APIs.
• Call APIs: Execute calls to various internal system APIs.
• Return results: Format the results and send them to clfude for the end - user to view.

🚀 Quick Start

System Architecture

Overview

The MCP API Service is an intermediate server running on the Model Context Protocol (MCP) communication protocol, which helps connect clfude AI with various internal system APIs. This system performs the following functions:

1. Receive commands from clfude: When users request a certain task, clfude sends instructions.
2. Process and transform commands: MCP converts clfude's requests into a format acceptable to internal system APIs.
3. Call APIs: Execute calls to various internal system APIs.
4. Return results: Format the results and send them to clfude for end - users to view.

Operating Mechanism

The MCP server communicates via standard input/output (stdio):

• Standard Input (stdin): Receive requests from clfude (e.g., employee search commands).
• Standard Output (stdout): Send results to clfude (e.g., found employee information).
• Standard Error (stderr): Record error messages (e.g., errors when connecting to APIs).

Request processing flow:

1. clfude sends a JSON - formatted request via stdin.
2. The MCP server processes the request and calls the appropriate API.
3. The MCP server sends the results to clfude via stdout.
4. clfude displays the results for users to view.

✨ Features

Existing functional modules:

• check_connection - Check the connection status to the API server.
• search_employee - Search for employees by name or number.
• register_breakfast - Register employees for the breakfast event.
• manage_conference_rooms - Manage conference room reservations.

📚 Documentation

Guide to Adding New Scripts

Add a New Endpoint

To add a new API endpoint, perform the following steps:

1. Modify the config.ts file:

// Add a new .endpoint file to the existingEndpoints array
{
    name: "new_endpoint_name",
    path: "/new_endpoint_path",
    method: "POST",  // Could be GET, POST, etc.
    description: "New endpoint description"
}

2. Create a new handling file:

• Create the /src/new_endpoint_handler.ts file.
• Implement the NewEndpointHandler class, inheriting from the base handler class.

Add Script Steps

1. Run the following command in the command line:

npm run add - scenario -- --name new_scenario_name --description "New scenario description"

2. Follow the prompts to enter the required information to complete the configuration of the new script.

🔧 Technical Details

Best Practices

1. Consistency

• Follow the existing naming conventions and code structure.
• Use the established code templates.

2. Error Handling

• Use try/catch statements in all API calls.
• Record complete error information.
• Return clear and concise error messages.

3. Logging

• Record DEBUG - level logs before the operation starts.
• Record INFORMATION - level logs after the operation succeeds.
• Ensure that the logs contain all relevant parameters and context information.

4. Data Validation

• Check the existence of required parameters.
• Validate the data types and formats of input parameters.

For more information on how to implement these best practices, please refer to the docs/add - new - scenario.md file.