CLAUDE.md•5.28 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is a **BotPe MCP Server** - a Model Context Protocol (MCP) server generated via the Postman MCP Generator. It provides automated tools for the BotPe WhatsApp API, enabling AI assistants to send various types of WhatsApp messages (text, images, videos, documents, stickers, contacts, locations, lists, catalogs, and more).
The server exposes 40+ WhatsApp messaging tools via the MCP protocol, allowing integration with Claude Desktop, Postman Desktop, and other MCP-compatible clients.
## Key Commands
### Development & Testing
```bash
# Install dependencies
npm install
# List all available tools (40+ WhatsApp API tools)
npm run list-tools
# or
node index.js tools
# Start MCP server in stdio mode (default)
node mcpServer.js
# Start server with Streamable HTTP support (port 3001)
node mcpServer.js --streamable-http
# Start server with Server-Sent Events (SSE) support (port 3001)
node mcpServer.js --sse
# Open Postman for testing
npm run postman
```
### Docker Deployment
```bash
# Build Docker image
docker build -t botpe-mcp-server .
# Run with Docker (requires .env file)
docker run -i --rm --env-file=.env botpe-mcp-server
```
## Architecture
### Core Components
1. **mcpServer.js** - Main MCP server implementation
- Supports 3 transport modes: stdio (default), Streamable HTTP, SSE
- Handles tool discovery, registration, and execution
- Routes requests to appropriate tool functions
- Validates required parameters before execution
2. **Tool Discovery System** (lib/tools.js)
- `discoverTools()` dynamically loads all tools from paths.js
- Automatically deduplicates tool names by appending suffixes
- Returns array of tool objects with definition + function
3. **Tool Registry** (tools/paths.js)
- Central manifest of all 40+ API tool paths
- Tools are organized as: `botpe-mcp/api-documentation/<tool-name>.js`
4. **Individual Tool Files** (tools/botpe-mcp/api-documentation/*.js)
- Each exports an `apiTool` object with:
- `function`: The executable async function
- `definition`: MCP-compatible tool schema (name, description, parameters)
- Tools use `fetch` to make HTTP requests to BotPe WhatsApp API
- Authentication via `process.env.BOTPE_MCP_API_KEY`
### Tool Structure Pattern
Every tool file follows this pattern:
```javascript
const executeFunction = async ({ param1, param2 }) => {
const token = process.env.BOTPE_MCP_API_KEY;
// API call logic
};
const apiTool = {
function: executeFunction,
definition: {
type: 'function',
function: {
name: 'tool_name',
description: 'Tool description',
parameters: { /* JSON Schema */ }
}
}
};
export { apiTool };
```
### Transport Modes
The server can run in 3 modes (mutually exclusive):
1. **stdio** (default): For Claude Desktop, programmatic integration
- Uses StdioServerTransport
- Single server instance
2. **Streamable HTTP** (`--streamable-http`): HTTP endpoint at /mcp
- Creates new server instance per request
- Port: 3001 (configurable via PORT env var)
3. **SSE** (`--sse`): Server-Sent Events
- GET /sse for stream, POST /messages for input
- Session-based with transport/server mapping
- Port: 3001 (configurable via PORT env var)
## Environment Configuration
**Critical**: The `.env` file must contain:
```
BOTPE_MCP_API_KEY=<your_api_key>
```
Additionally, tool files contain placeholder values that must be configured:
- `<API_URL>` - Base URL for BotPe API
- `<Version>` - API version
- `<PHONE_NUMBER_ID>` - Business phone number ID
These are typically hardcoded in tool files or should be extracted to environment variables.
## Adding New Tools
To add new WhatsApp API tools:
1. Generate new tools via Postman MCP Generator
2. Copy generated .js files to `tools/botpe-mcp/api-documentation/`
3. Update `tools/paths.js` to include new tool paths
4. Server will automatically discover and register new tools on restart
## Node.js Version Requirements
- **Minimum**: Node.js 16.0.0
- **Recommended**: Node.js 18+ (for native `fetch` support)
- **Docker**: Uses Node.js 22.12-alpine
Note: If using Node < 18, tools will fail because they use native `fetch`. Workaround: import `node-fetch` and install it as a dependency.
## Integration with MCP Clients
### Claude Desktop Configuration
Add to Claude Desktop config:
```json
{
"mcpServers": {
"botpe-mcp": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/mcpServer.js"]
}
}
}
```
### Postman Desktop
1. Create MCP Request with type "STDIO"
2. Command: `node /absolute/path/to/mcpServer.js`
3. Connect to test individual tools
## Tool Categories
The 40+ tools cover:
- Text messages (simple, with preview URLs, templates)
- Media messages (images, videos, audio, documents, stickers) - by ID or URL
- Interactive messages (buttons, lists, catalogs, products)
- Location messages
- Contact messages
- Reply messages (to any message type with reactions)
- Message templates (text, media, interactive)
- Message status (mark as read)
All tools follow the pattern: `send_<type>_message` or `send_reply_to_<type>_message`.