CX TimeFilter MCP Server

A Model Context Protocol (MCP) server providing time filter tools for CX Dashboard. This server exposes time filtering functionality that can be used by any MCP-compatible client, including Langflow.

🎯 Features

• Set Predefined Time Periods: Last Month, Last 7 days, This Quarter, etc.

• Set Custom Date Ranges: Specify exact start and end dates

• List Available Periods: Get all supported time periods

• HTTP-based MCP Protocol: Easy integration with any MCP client

• Optional Authentication: API key protection

• Comprehensive Validation: Input validation and error handling

Related MCP server: Utility MCP Server

🚀 Quick Start

1. Installation

# Clone or create the project directory
mkdir cx-timefilter-mcp-server
cd cx-timefilter-mcp-server

# Install dependencies
npm install

2. Configuration

# Copy environment template
cp env.example .env

# Edit .env file
PORT=3000
NODE_ENV=development
MCP_API_KEY=your-secret-api-key-here
ALLOWED_ORIGINS=http://localhost:3001,https://your-langflow-instance.com

3. Run the Server

# Development mode
npm run dev

# Production mode
npm start

# Run tests
npm test

4. Verify Installation

# Health check
curl http://localhost:3000/health

# List available tools
curl http://localhost:3000/mcp/tools

# Test a tool (with API key if configured)
curl -X POST http://localhost:3000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "name": "set_time_period",
    "arguments": {
      "timePeriodName": "Last Month",
      "tabName": "Overview"
    }
  }'

🛠️ Available Tools

1. set_time_period

Set a predefined time period for dashboard tabs.

Parameters:

• timePeriodName (string): Exact name of the time period

• tabName (string): Dashboard tab name

Example:

{
  "name": "set_time_period",
  "arguments": {
    "timePeriodName": "Last Month",
    "tabName": "Overview"
  }
}

2. set_custom_date_range

Set a custom date range with specific start and end dates.

Parameters:

• startDate (string): Start date in YYYY-MM-DD format

• endDate (string): End date in YYYY-MM-DD format

• tabName (string): Dashboard tab name

Example:

{
  "name": "set_custom_date_range",
  "arguments": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "tabName": "Comparison"
  }
}

3. list_time_periods

List all available predefined time periods.

Parameters: None

Example:

{
  "name": "list_time_periods",
  "arguments": {}
}

🔗 API Endpoints

🔐 Authentication

The server supports optional API key authentication:

1. Set API Key: Add MCP_API_KEY=your-secret-key to .env

2. Include in Requests: Add Authorization: Bearer your-secret-key header

3. Alternative Formats: ApiKey your-secret-key or Key your-secret-key

🌐 Langflow Integration

Step 1: Add MCP Tools Component

1. Open your Langflow project

2. Add an "MCP Tools" component

3. Configure the connection

Step 2: Configure Connection

{
  "serverName": "CX TimeFilter Server",
  "connectionMode": "HTTP",
  "serverUrl": "http://localhost:3000",
  "apiKey": "your-api-key",
  "endpoints": {
    "tools": "/mcp/tools",
    "call": "/mcp/tools/call"
  }
}

Step 3: Use Tools in Flows

The tools will appear in Langflow and can be used in your AI workflows.

📦 Deployment

Railway (Recommended)

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway up

Render

1. Connect your GitHub repository

2. Set environment variables

3. Deploy automatically

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

🧪 Testing

# Run built-in tests
npm test

# Manual testing with curl
curl -X POST http://localhost:3000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "list_time_periods",
    "arguments": {}
  }'

📊 Supported Time Periods

Calendar Periods:

• All Time, Today, Yesterday

• This Week, Last Week

• This Month, Last Month

• This Quarter, Last Quarter

• This Year, Last Year

Rolling Periods:

• Last 24 hours, Last 7 days, Last 14 days

• Last 30 days, Last 90 days, Last 180 days

• Last 12 Months

Custom Periods:

• Any date range in YYYY-MM-DD format

🔧 Development

Project Structure

cx-timefilter-mcp-server/
├── src/
│   ├── server.js              # Main server
│   ├── tools/
│   │   └── timefilter.js      # Time filter tools
│   ├── utils/
│   │   └── mcp-protocol.js    # MCP utilities
│   ├── middleware/
│   │   └── auth.js            # Authentication
│   └── test.js                # Test suite
├── package.json
├── .env
└── README.md

Adding New Tools

1. Create tool definition in src/tools/

2. Add validation schema

3. Implement execute function

4. Export in tools array

5. Update README

🐛 Troubleshooting

Common Issues:

1. Port already in use: Change PORT in .env

2. CORS errors: Update ALLOWED_ORIGINS in .env

3. Auth failures: Check MCP_API_KEY configuration

4. Tool not found: Verify tool name matches exactly

Debug Mode:

NODE_ENV=development npm start

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests

5. Submit a pull request

Ready to integrate with Langflow and start filtering time periods via MCP! 🎉