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	no	—	Anchor date for relative expressions; defaults to today.

Returns

• On success: {"result": {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.
• An expression with no temporal content at all does not fail — the model
• answers it confidently, so the window comes back with is_heuristic=True
• and an interpretation saying it is a guess. Branch on is_heuristic; do
• not read the absence of an error as a successful parse.
• On failure: {"error": {code, message, field}}
• code is invalid_input with field expression; internal with no
• field when the resolved window itself is unusable (a retry returns the
• same error); or, from resolving the caller's config rather than from the
• parse and with no field, not_entitled (authorization refused) or
• upstream_unavailable.

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": "example"
    }
  }
}'

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": "example"
  },
});

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": "example"},
        )

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": {
      "description": "Anchor date for relative expressions; defaults to today.",
      "format": "date",
      "type": "string"
    }
  },
  "required": [
    "expression"
  ]
}

Output schema

Describes both branches of the envelope — result on success, error on a refusal. Validate against this rather than pattern-matching the prose above; see Concepts → Response shape.

{
  "type": "object",
  "properties": {
    "result": {
      "additionalProperties": true,
      "properties": {
        "date_range": {
          "description": "Always present — an expression that cannot be parsed is a refusal on `expression`, not a null window.",
          "properties": {
            "start_date": {
              "anyOf": [
                {
                  "format": "date",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "end_date": {
              "anyOf": [
                {
                  "format": "date",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "start_date",
            "end_date"
          ],
          "type": "object"
        },
        "interpretation": {
          "description": "How the window was arrived at.",
          "type": "string"
        },
        "is_heuristic": {
          "description": "True when the window was guessed rather than parsed — no date rule resolved the expression, or a future bound was rewritten. Read `interpretation` before treating the window as exact.",
          "type": "boolean"
        }
      },
      "required": [
        "date_range",
        "interpretation",
        "is_heuristic"
      ],
      "type": "object"
    },
    "error": {
      "type": "object",
      "description": "Present instead of `result` when the call was rejected. Branch on `code`; never string-match `message`.",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_input",
            "not_entitled",
            "upstream_unavailable",
            "internal"
          ]
        },
        "message": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "description": "Offending parameter, when the failure is attributable to one."
        },
        "details": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "oneOf": [
    {
      "required": [
        "result"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "x-fastmcp-wrap-result": true
}