timeseries
Monitor tone changes over time for any topic with configurable time bins, returning per-bin averages and dominant tone for line charts.
Instructions
Tone trajectory over time for a topic. bin is 'hour', '6h',
or 'day'. hours up to 240 (10 days). Returns an ordered series
of per-bin tone averages, article_count, and dominant_tone.
Render as a Mermaid line chart or ASCII sparkline when presenting
to the user.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| bin | No | hour | |
| hours | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/overtone_news_mcp/server.py:164-175 (handler)The timeseries tool handler function. Decorated with @mcp.tool(), it accepts a query string, a bin literal ('hour', '6h', 'day'), and hours (1-240). Calls _post('timeseries', ...) to execute the API request.
@mcp.tool() def timeseries( query: Query, bin: Bin = "hour", hours: Annotated[int, Field(ge=1, le=240)] = 72, ) -> dict[str, Any]: """Tone trajectory over time for a topic. `bin` is 'hour', '6h', or 'day'. `hours` up to 240 (10 days). Returns an ordered series of per-bin tone averages, article_count, and dominant_tone. Render as a Mermaid line chart or ASCII sparkline when presenting to the user.""" return _post("timeseries", {"query": query, "bin": bin, "hours": hours}) - Type aliases/schemas used by timeseries: Query (str, 1-500 chars), Bin (Literal 'hour', '6h', 'day'), and the hours field constraints (ge=1, le=240).
Query = Annotated[str, Field(min_length=1, max_length=500)] ToneFilter = Literal["positive", "negative", "informational"] ToneName = Literal[ "happy", "funny", "hopeful", "informational", "angry", "sad", "fearful" ] Bin = Literal["hour", "6h", "day"] - src/overtone_news_mcp/server.py:164-164 (registration)The @mcp.tool() decorator registers timeseries as an MCP tool on the FastMCP server instance.
@mcp.tool() - The _post helper function that timeseries uses to make HTTP POST requests to the Overtone API. It injects the API key via X-API-Key header.
def _post(path: str, body: dict[str, Any]) -> dict[str, Any]: with httpx.Client(timeout=HTTP_TIMEOUT) as client: resp = client.post( f"{API_URL}/{path}", headers={"X-API-Key": _load_api_key()}, json=body, ) resp.raise_for_status() return resp.json() - src/overtone_news_mcp/server.py:213-214 (registration)The 'timeseries' tool name is listed in the server_capabilities resource, confirming it's available alongside other tools.
return json.dumps({ "tools": ["news", "tone", "pulse", "emerging", "velocity", "timeseries", "report"],