Skip to main content
Glama
Unified History MCP

Unified History MCP

by jmars

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"
    }
  }
}

Related MCP server: Unified History MCP

Configuration

Configuration is loaded from the first existing location:

  1. $UNIFIED_HISTORY_CONFIG environment variable

  2. ~/.config/unified-history-mcp/config.toml

  3. ./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

  1. Configuration — TOML file defines domains, their directories, extractors, and renderers.

  2. Domain Discovery — Files are discovered via glob patterns with extension filtering.

  3. 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.

  4. Slow Path (Regex) — Falls back to line-by-line regex scanning across files when FST is unavailable.

  5. Extractors — Produce text entries for FST indexing from different file formats (JSONL, TXT, Tactiq transcripts, notifications).

  6. 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.

Available Tools

7 tools
list_domainA

List available files in a domain with metadata and summaries.

Args: domain: Domain to list (sessions, transcripts, notifications) date_from: Optional start of date range (YYYY-MM-DD) date_to: Optional end of date range (YYYY-MM-DD, inclusive) max_results: Maximum entries to show (default 50)

Inputs: domain (required), date_to, date_from, max_results. Returns: result

readB

Read entries from a domain file.

Args: domain: Domain (sessions, transcripts, notifications) id: File/directory name or unique prefix max_entries: Maximum entries to return, newest first (default 50) role: [sessions] Filter by role: user, assistant, tool speaker: [transcripts] Filter by speaker name

Inputs: id (required), domain (required), role, speaker, +1 more. Returns: result

rebuildA

Rebuild FST indexes for configured domains.

Args: domain: Domain to rebuild, or "all" for all configured domains

Inputs: domain. Returns: result

search_historyA

Search the Vibe command history (vibehistory file).

Args: query: Search text (or regex pattern if regex=True) max_results: Maximum matches to return (default 30) regex: If True, treat query as a regex pattern case_sensitive: If True, match case-sensitively (default False)

Inputs: query (required), regex, max_results, case_sensitive. Returns: result

search_logA

Search the Vibe runtime log (vibe.log).

Args: query: Search text (or regex pattern if regex=True) max_results: Maximum matches to return (default 30) regex: If True, treat query as a regex pattern case_sensitive: If True, match case-sensitively (default False) level: Filter by log level: WARNING, INFO, ERROR, DEBUG

Inputs: query (required), level, regex, max_results, +1 more. Returns: result

summaryA

Get the AI-generated summary for a domain entry.

Args: domain: Domain (sessions, transcripts) id: File/directory name or unique prefix

Inputs: id (required), domain (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a distinct purpose: search for full-text search, list_domain for listing files, read for reading entries, summary for AI summaries, rebuild for index rebuilding, search_history for command history, and search_log for runtime log. No overlap exists.

    Naming Consistency3/5

    Names use lowercase underscores, but the pattern is inconsistent: some are simple verbs (search, read, rebuild), one is a noun (summary), and three are verb_noun (list_domain, search_history, search_log). A more uniform verb_noun pattern would improve consistency.

    Tool Count5/5

    With 7 tools, the server is well-scoped for its purpose of managing and querying history domains, command history, and logs. Each tool contributes meaningfully without redundancy.

    Completeness4/5

    The tool surface covers essential operations: search, list, read, and summarize across domains, plus separate search for history and log. Minor gaps like missing delete or create operations are acceptable for a viewer-oriented server.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server for Elasticsearch log querying. Enables natural language search, filtering, context retrieval, and aggregation of logs.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP server that indexes local Claude Code transcripts and provides keyword, phrase, semantic, and date-range search, plus full context/session recall.
      -