Русская версия | English

Time Toolkit

An independent client and integration toolkit for Time Messenger and Mattermost-compatible servers. One Python package provides the timetk CLI, a time-toolkit MCP server, an importable Python API, a WebSocket event stream, and a local read-only HTTP API.

Time Toolkit needs no server plugin. It uses the permissions of a selected user or bot through the public REST API v4 and does not change read state during ordinary read operations.

Capabilities

• inspect teams, channels, direct messages, posts, threads, unread messages, mentions, pins, flags, read receipts, reactions, users, and file metadata;
• search messages and users with machine-readable text, json, and ndjson output;
• create, reply to, edit, and delete posts with an explicit write policy;
• manage reactions, pins, flags, followed threads, files, and read state;
• stream Mattermost WebSocket events with filtering, reconnection, and deduplication;
• expose tools to Codex and other clients through MCP;
• embed the same service layer in Python applications;
• serve a protected local read-only HTTP API;
• isolate any number of profiles with separate servers, tokens, and write modes.

Safety model

Every profile has one of three write modes:

Mode	Interactive CLI and confirmed MCP	Automation and --yes
readonly	blocked	blocked
approval	allowed after confirmation	blocked
fullauto	allowed	allowed

New profiles default to approval. MCP always uses a two-step write flow with a single-use confirmation token, including for fullauto profiles. Tokens are stored in the operating-system keyring rather than Git or config.json.

Quick start

Time Toolkit requires Python 3.11+ and uv.

git clone https://github.com/erstcl/time-toolkit.git
cd time-toolkit
uv sync --locked --no-editable --all-extras

# Generic Mattermost-compatible server
uv run --no-sync timetk profile add example https://time.example.com

# Explicitly supported Time Messenger deployment
uv run --no-sync timetk profile add university https://time.cu.ru

Store and verify a personal access token through hidden input:

uv run --no-sync timetk -p university auth set
uv run --no-sync timetk -p university auth status --check

Start with read-only commands:

uv run --no-sync timetk -p university channels --pattern general
uv run --no-sync timetk -p university unread --with-posts
uv run --no-sync timetk -p university search "exam" --since 7d

Preview and confirm a write operation:

uv run --no-sync timetk -p university post general -m "Hello" --dry-run
uv run --no-sync timetk -p university post general -m "Hello"

--dry-run never calls a write endpoint. Without --yes, the CLI shows the exact plan and asks Proceed? [y/N]. Automated writers require a separately configured fullauto profile.

Interfaces

Use case	Interface
Human operator in a terminal	timetk CLI
Codex or another agent	time-toolkit MCP server
In-process Python application	TimeService
Local service written in another language	read-only HTTP API
Reaction to new events	timetk -o ndjson watch
Short language-agnostic script	CLI with -o json or -o ndjson

Automated sending from an external service should use a dedicated bot token, a fullauto profile, and an application-level recipient allowlist. The built-in HTTP API intentionally remains read-only.

Architecture

CLI / MCP / Python API / HTTP API / WebSocket watcher
                         │
                    TimeService
                         │
             authenticated REST API v4 client
                         │
       Time Messenger / Mattermost-compatible server

All interfaces share the same configuration, authentication, service, and safety layers. Network code stays behind a typed client, while CLI and MCP adapters handle presentation and confirmation semantics.

Documentation

• Getting started, profiles, and tokens
• Complete CLI reference
• MCP integration
• Integration patterns
• Python API
• HTTP API
• Security model
• Architecture and guarantees
• Troubleshooting
• Development and releases
• Changelog

Scope

Time Toolkit is not part of, or endorsed by, Time Messenger, Mattermost, Inc., Central University, or operators of compatible servers. Product names and trademarks belong to their respective owners.

The project intentionally excludes password login, browser-profile scraping, persistent message mirroring, automatic mark-read, HTTP write endpoints, a full-screen TUI, and Mattermost administration. The rationale is documented in the architecture guide.

Time Toolkit is independently implemented against documented network interfaces and released under the MIT License.