Resolve Time Period (Messaging)

messagingmcp-resolve_time_period

Resolve a natural-language time expression to {start_date, end_date}.

Uses messaging's own season calendar: SS = Mar–Aug; AW/FW = Sep–following Feb; Resort/Cruise = Nov–following Jan. Pass the returned date_range to the promo and search tools rather than embedding the expression in a query string.

Relative expressions ("last week") resolve against now when supplied, so backtesting with a past anchor produces windows relative to that anchor. Future-date handling: a start in the future is unset (open-ended start); an end in the future is clamped to now.

Unusual expressions (named holidays like "Eid"/"Diwali", non-English phrases) that no season/deterministic rule matches fall through to a best-effort LLM parse, flagged is_heuristic=True — surface it for confirmation rather than treating it as an exact filter.

Parameters

Name	Type	Required	Constraints	Description
expression	string	yes	—	Natural-language time expression, e.g. 'SS25', 'Resort 25', 'last 3 months', 'Black Friday 2024'.
now	string | null	no	default: null	Anchor date for relative expressions; defaults to today.

Returns

• {date_range: {start_date, end_date}, interpretation, is_heuristic}.
• is_heuristic is True when the heuristic / LLM fallback was used or a
• future-date rewrite was applied.
• On parse failure: {"error": str}.

Try it

Loading interactive widget…

Code examples

curl

curl -s https://mcp.edited.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "x-api-key: $MCP_API_KEY" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "messagingmcp-resolve_time_period",
    "arguments": {
      "expression": "example",
      "now": null
    }
  }
}'

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "demo", version: "1.0.0" }, { capabilities: {} });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://mcp.edited.com/mcp"), {
    requestInit: { headers: { "x-api-key": process.env.MCP_API_KEY ?? "" } },
  }),
);

const result = await client.callTool({
  name: "messagingmcp-resolve_time_period",
  arguments: {
    "expression": "example",
    "now": null
  },
});

Python

import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

headers = {"x-api-key": os.environ["MCP_API_KEY"]}
async with streamablehttp_client("https://mcp.edited.com/mcp", headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "messagingmcp-resolve_time_period",
            {"expression": "example", "now": None},
        )

Input schema

{
  "type": "object",
  "properties": {
    "expression": {
      "description": "Natural-language time expression, e.g. 'SS25', 'Resort 25', 'last 3 months', 'Black Friday 2024'.",
      "type": "string"
    },
    "now": {
      "anyOf": [
        {
          "format": "date",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Anchor date for relative expressions; defaults to today."
    }
  },
  "required": [
    "expression"
  ]
}