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 (src/server.ts)

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 (src/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:

• TOOL_DESCRIPTIONS.md: A markdown file that provides detailed descriptions of all available tools and their parameters.
• MODELS.md: A list of the AI models that can be used with the agents.
• SYSTEM_PROMPTS.md: 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 src/server.ts.
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, handleDeleteAgent in src/tools/deleteAgent.ts 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., deleteAgent.ts).
  • 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 deleteAgent function, imported from ../services/chatvolt.js, 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 TOOL_DESCRIPTIONS.md 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 src/server.ts.
   • The ListToolsRequestSchema handler in src/server.ts 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 src/server.ts.

---

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 SYSTEM_PROMPTS.md 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 SYSTEM_PROMPTS.md 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 tha

---