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

🚀 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

Endpoint	Method	Description
/health	GET	Health check
/mcp/info	GET	MCP protocol information
/mcp/tools	GET	List available tools
/mcp/tools/call	POST	Execute a tool
/mcp	POST	Full MCP protocol endpoint

🔐 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! 🎉