MiguelMartinezCV/chatvolt-mcp

Chatvolt MCP Server: High-Level Overview

This document provides a high-level overview of the Chatvolt Model Context Protocol (MCP) server, a TypeScript-based application designed to extend the capabilities of AI agents by providing them with a suite of tools to interact with the Chatvolt platform.

Project Goal

The main goal of this project is to act as a bridge between an AI model and the Chatvolt API. It exposes a set of tools that an AI agent can call to perform actions such as managing agents, querying datastores, and handling CRM scenarios. This allows for the automation of complex workflows and provides a natural language interface to the Chatvolt platform.

Key Technologies

• Node.js: The runtime environment for the server.
• TypeScript: The primary programming language, providing static typing and modern JavaScript features.
• @modelcontextprotocol/sdk: The core SDK for building MCP servers, which simplifies the process of defining tools, resources, and handling requests from an AI model.

Main Components

1. MCP Server ()

The core of the application is the MCP server, which is responsible for:

• Initializing the Server: Sets up the server with its name, version, and capabilities.
• Handling Requests: Implements handlers for various MCP request types, including ListTools, CallTool, ListResources, and GetPrompt.
• Tool Dispatching: Receives CallTool requests and dispatches them to the appropriate tool handler.

2. Tools ()

The tools are the actions that the AI agent can perform. They are defined in the src/tools/ directory and are broadly categorized into:

• Agent Management: Tools for creating, updating, deleting, and listing Chatvolt agents.
• CRM Management: Tools for managing CRM scenarios and steps.
• Datastore Management: Tools for interacting with datastores and datasources.

3. Resources and Prompts

The server provides additional context to the AI model through resources and prompts:

• : A markdown file that provides detailed descriptions of all available tools and their parameters.
• : A list of the AI models that can be used with the agents.
• : Contains the system-level instructions that guide the AI agent.

Client Configuration

This MCP server is launched via a command from the client. To connect, you need to configure your client to launch the chatvolt-mcp command and pass the necessary environment variables.

Here is an example of how you might configure your client's mcpServers setting:

{
  "mcpServers": {
    "chatvolt-mcp": {
      "command": "npx",
      "args": [
        "chatvolt-mcp"
      ],
      "env": {
        "CHATVOLT_API_KEY": "{your_token}"
      }
    }
  }
}

Note: You must replace "{your_token}" with your actual Chatvolt API key.

Chatvolt MCP Server: Detailed Architecture

This document provides a detailed technical architecture of the Chatvolt Model Context Protocol (MCP) server. It expands on the high-level overview, covering the request lifecycle, directory structure, and the process of defining and registering tools.

1. Request Lifecycle: CallTool

The CallTool request is the primary mechanism by which an AI agent executes an action. The lifecycle of this request is as follows:

sequenceDiagram
    participant AI Agent
    participant MCP Server
    participant Tool Handler
    participant Chatvolt API

    AI Agent->>+MCP Server: Sends CallToolRequest (e.g., 'delete_agent', {id: '123'})
    MCP Server->>MCP Server: Receives request in CallTool handler
    Note over MCP Server: Finds handler for 'delete_agent' in `toolHandlers` map
    MCP Server->>+Tool Handler: Invokes handleDeleteAgent(request)
    Tool Handler->>Tool Handler: Validates arguments (e.g., checks for 'id')
    Tool Handler->>+Chatvolt API: Calls `deleteAgent('123')`
    Chatvolt API-->>-Tool Handler: Returns result (e.g., {success: true})
    Tool Handler-->>-MCP Server: Returns formatted content
    MCP Server-->>-AI Agent: Sends response with tool output

Flow Description:

1. Request Reception: The MCP server receives a CallToolRequest. This request is handled by the generic CallToolRequestSchema handler defined in .
2. Handler Dispatching: The server looks up the specific tool handler from the toolHandlers object, which maps tool names (e.g., "delete_agent") to their corresponding handler functions (e.g., handleDeleteAgent). This object is imported from the central src/tools/ index file.
3. Tool Execution: The matched handler function is executed. For example, in is called.
4. Business Logic: The tool handler extracts the necessary arguments from the request, validates them, and then calls the relevant function from the src/services/ layer (e.g., deleteAgent(id)).
5. API Interaction: The service function is responsible for making the actual API call to the Chatvolt platform.
6. Response Formatting: The tool handler receives the data back from the service, stringifies it (in this case, as a JSON), and wraps it in the format expected by the MCP SDK.
7. Response Transmission: The server sends the final, formatted content back to the AI agent that initiated the call.

2. Directory Structure

The project is organized to separate concerns, making it modular and maintainable.

• src/: This is the root directory for all application source code.
• src/tools/: This directory contains the implementation for each tool the server exposes.
  • Structure: Each tool typically has its own file (e.g., ).
  • Contents: Each file exports two main constructs:
    1. A Tool definition object (e.g., deleteAgentTool) that contains the tool's name, description, and inputSchema as required by the MCP SDK.
    2. A handler function (e.g., handleDeleteAgent) that contains the logic for executing the tool.
  • Aggregation: A central index.js file within this directory is responsible for importing all individual tools and handlers and exporting them as two aggregate objects: tools (an array of all tool definitions) and toolHandlers (a map of tool names to their handlers).
• src/services/: This directory is intended to house the business logic and API client code that interacts with external services, primarily the Chatvolt API.
  • Purpose: It acts as a bridge between the tool handlers and the underlying platform. This separation ensures that tool handlers are only responsible for request/response handling and argument validation, while the services layer manages the specifics of API communication.
  • Example: The function, imported from , would contain the fetch call and logic required to send a DELETE request to the Chatvolt /agents/:id endpoint.

3. Tool Definition and Registration

Tools are the core components that define the server's capabilities. Their definition and registration follow a clear pattern:

1. Tool Definition: Each tool is defined as a constant object of type Tool from the @modelcontextprotocol/sdk/types.js library. This object includes:

   • name: A unique, machine-readable name for the tool (e.g., "delete_agent").
   • description: A human-readable description of what the tool does and its parameters. While a resource file like exists to provide detailed documentation to the AI model, the description property within the tool definition itself serves as a concise summary.
   • inputSchema: A JSON Schema object that formally defines the arguments the tool accepts, including their types and whether they are required.

2. Tool Registration: The server discovers and registers tools through the following process:

   • The tools array and toolHandlers map are imported from src/tools/index.js into .
   • The ListToolsRequestSchema handler in uses the imported tools array to respond to requests for the list of available tools.
   • The CallToolRequestSchema handler uses the toolHandlers map to find and execute the correct function based on the name parameter in the incoming request.

This architecture creates a decoupled system where new tools can be easily added by creating a new file in the src/tools/ directory and updating the central index.js file, without modifying the core server logic in .

System Prompts Documentation

This document explains the role and content of system prompts used to guide the AI agent's behavior when interacting with the Chatvolt MCP (Model Context Protocol). These prompts are defined in the file and provide a foundational set of instructions for the AI.

Purpose of System Prompts

System prompts are high-level instructions that define the AI's persona, objectives, and operational constraints. They ensure the AI acts in a predictable and effective manner by establishing a clear framework for how it should interpret user requests, utilize its tools, and structure its responses.

Key Instructions and Scenarios

The file outlines three primary scenarios, each with a corresponding system prompt to guide the AI's behavior.

1. Simple Tool Operation

• Purpose: To handle straightforward user requests that can be fulfilled by a single tool call.
• AI Persona: An expert AI assistant for the Chatvolt platform.
• Core Instructions:
  1. Identify the user's intent.
  2. Select the single, most appropriate tool (e.g., ).
  3. Execute the tool with the correct parameters.
  4. Report the outcome to the user.

2. Complex, Multi-Step Workflow

• Purpose: To manage complex tasks that require a sequence of tool calls to achieve a larger goal.
• AI Persona: A senior AI automation engineer responsible for orchestrating workflows.
• Core Instructions:
  1. Deconstruct: Break down the user's request into smaller, sequential steps.
  2. Plan: Create a step-by-step plan, identifying the right tool for each step.
  3. Execute: Call the tools sequentially, waiting for each one to complete successfully before proceeding to the next. The output of one tool can be used as input for another.
  4. Synthesize: Provide a final summary of all actions taken and the result.

3. Self-Discovery and Learning

• Purpose: To enable the AI to be resourceful and learn about its own capabilities before executing a task.
• AI Persona: A highly autonomous and proactive AI agent.
• Core Instructions:
  1. Self-Discovery First: Before attempting a complex task, the AI must first call the getDocumentation tool to retrieve information about all its available tools.
  2. Analyze: Review the documentation to understand its capabilities.
  3. Plan: Formulate a plan based on the newly acquired knowledge of its tools.
  4. Execute: Carry out the plan and report the outcome.

API and Tool Reference

This document provides a detailed reference for the available tools that can be used to interact with the server.

create_agent

Creates a new Chatvolt agent.

update_agent

Partially updates an existing agent based on the ID. Allows updating one or more fields of a specific agent. Only the fields provided in the request body will be updated.

delete_agent

Deletes a specified agent.

list_agents

Retrieves a list of all available agents.

This tool takes no parameters.

get_agent

Retrieves detailed information about a single agent.

agent_query

Sends a query or message to an agent for processing.

enable_disable_agent_integration

Enables or disables a specific integration for an agent.

create_crm_scenario

Creates a new scenario within the CRM.

update_crm_scenario

Updates an existing CRM scenario.

delete_crm_scenario

Deletes a CRM scenario.

list_crm_scenarios

Lists all CRM scenarios.

create_crm_step

Creates a new step within a CRM scenario.

update_crm_step

Updates an existing step in a CRM scenario.

delete_crm_step

Deletes a step from a CRM scenario.

list_crm_steps

Lists all steps for a given CRM scenario.

create_datastore

Creates a new datastore.

get_datastore

Retrieves information about a specific datastore.

list_datastores

Retrieves a list of all datastores.

This tool takes no parameters.

create_datasource

Creates a new data source within a datastore.