Unified History MCP

Config-driven MCP server for cross-domain full-text search across agent session logs, meeting transcripts, and notification files.

Quick Start

# Install from source (PyPI package coming soon)
pip install git+https://github.com/jmars/unified-history-mcp.git

# Create a config file at ~/.config/unified-history-mcp/config.toml
# or use the example as a starting point:
cp config.example.toml ~/.config/unified-history-mcp/config.toml

# Start the server
unified-history-mcp

Add to your MCP client configuration:

{
  "mcpServers": {
    "unified-history": {
      "command": "unified-history-mcp"
    }
  }
}

Configuration

Configuration is loaded from the first existing location:

$UNIFIED_HISTORY_CONFIG environment variable
~/.config/unified-history-mcp/config.toml
./unified-history.toml (current working directory)

Domain Configuration

Each [domains.X] section defines a searchable domain:

Field	Type	Default	Description
`dir`	string	required	Root directory for this domain's files
`pattern`	string	`"*"`	Glob pattern for file discovery
`type`	string	`"files"`	`"files"` or `"dirs"`
`extensions`	string[]	`[]`	Allowed extensions (e.g. `[".txt", ".docx"]`)
`extractor`	string	`"jsonl"`	Extractor: `jsonl`, `txt`, `transcript`, `notification`
`renderer`	string	(extractor)	Renderer override
`label`	string	`"file"`	Human label: "session", "transcript", etc.
`fst_binary`	string	`"fst-indexer"`	Path or name of the FST indexer binary
`fst_index_dir`	string	(dir)	Override for index directory
`date_field`	string	—	JSON field for date extraction (jsonl only)
`filters`	string[]	`[]`	Supported filters: `role`, `speaker`

Global Configuration

Section	Field	Description
`[history]`	`file`	Path to command history file
`[log]`	`file`	Path to runtime log file

MCP Tools

`search(domain, query, ...)`

Full-text search with FST fast path and regex fallback.

Parameter	Type	Default	Description
`domain`	string	`"all"`	Domain or `"all"` for cross-domain
`query`	string	`""`	Search text or regex pattern
`max_results`	int	`20`	Maximum total matches
`date_from`	string	—	Start date (YYYY-MM-DD)
`date_to`	string	—	End date (YYYY-MM-DD, inclusive)
`regex`	bool	`false`	Treat query as regex
`context_lines`	int	`2`	Surrounding context lines per match
`case_sensitive`	bool	`false`	Case-sensitive matching
`max_matches_per_file`	int	`5`	Max matches from any single file
`role`	string	—	[sessions] Filter by role: user, assistant, tool
`speaker`	string	—	[transcripts] Filter by speaker name

`list_domain(domain, date_from, date_to, max_results)`

List available files in a domain with metadata.

Parameter	Type	Default	Description
`domain`	string	—	Domain to list
`date_from`	string	—	Start date (YYYY-MM-DD)
`date_to`	string	—	End date (YYYY-MM-DD, inclusive)
`max_results`	int	`50`	Maximum entries to show

`read(domain, id, max_entries, role, speaker)`

Read entries from a domain file.

Parameter	Type	Default	Description
`domain`	string	—	Domain
`id`	string	—	File/directory name or unique prefix
`max_entries`	int	`50`	Maximum entries (newest first)
`role`	string	—	[sessions] Filter by role
`speaker`	string	—	[transcripts] Filter by speaker name

`summary(domain, id)`

Get the AI-generated summary for a domain entry.

Parameter	Type	Description
`domain`	string	Domain (sessions, transcripts)
`id`	string	File/directory name or unique prefix

`rebuild(domain)`

Rebuild FST indexes for configured domains.

Parameter	Type	Default	Description
`domain`	string	`"all"`	Domain or `"all"` for all

`search_history(query, max_results, regex, case_sensitive)`

Search the command history file.

Parameter	Type	Default	Description
`query`	string	—	Search text or regex pattern
`max_results`	int	`30`	Maximum matches
`regex`	bool	`false`	Treat query as regex
`case_sensitive`	bool	`false`	Case-sensitive matching

`search_log(query, max_results, regex, case_sensitive, level)`

Search the runtime log file.

Parameter	Type	Default	Description
`query`	string	—	Search text or regex pattern
`max_results`	int	`30`	Maximum matches
`regex`	bool	`false`	Treat query as regex
`case_sensitive`	bool	`false`	Case-sensitive matching
`level`	string	—	Filter by log level

How It Works

Configuration — TOML file defines domains, their directories, extractors, and renderers.
Domain Discovery — Files are discovered via glob patterns with extension filtering.
Fast Path (FST) — If the optional fst-indexer binary is installed and indexes are built (via the rebuild tool), searches use the blazing-fast FST index.
Slow Path (Regex) — Falls back to line-by-line regex scanning across files when FST is unavailable.
Extractors — Produce text entries for FST indexing from different file formats (JSONL, TXT, Tactiq transcripts, notifications).
Renderers — Format entries for human-readable display in search results, listings, and read output.

Development

git clone https://github.com/jmars/unified-history-mcp.git
cd unified-history-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines on setting up the dev environment, running tests, and submitting pull requests.

License

MIT — see LICENSE.