Skip to main content
Glama
vblearnstowritecode

WorkTrace MCP

by vblearnstowritecode
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

WorkTrace MCP

WorkTrace is a local MCP server that helps an AI agent recover missing historical developer context from captured work evidence.

It records manual or periodic screenshots, queues them locally, derives a work-oriented summary and OCR through OpenAI, embeds the summary, stores everything in SQLite/FTS5, and returns grounded answers with inspectable event citations.

Desktop capture
    → local pending image + sidecar
    → OpenAI vision summary/OCR
    → summary embedding
    → local SQLite + FTS5
    → WorkTrace MCP (`ask_context`, `get_event`)
    → host agent

Alpha / proof of concept. WorkTrace helps an agent orient itself to prior work. It does not establish current repository state, command success, causality, or developer intent. Inspect live files, Git, processes, and configuration before acting.

Privacy first

This public repository intentionally contains no screenshots, recordings, database, extracted OCR, embeddings, or developer session data.

Runtime evidence is ignored by Git, including:

  • data/ and SQLite files

  • demo_fixture/, captures/, and artifacts/

  • common image, audio, and video formats

  • .env and private-key formats

Important limitation: ingestion sends source screenshot pixels to OpenAI. Prompt-level output redaction does not redact the image before upload. Pause capture, exclude sensitive windows, or add local image redaction before using WorkTrace with private material.

Related MCP server: local-agent-context

Requirements

  • Python 3.11+

  • An OpenAI API key

  • Windows for the current Tkinter desktop-recorder demo

  • An MCP host such as Hermes Agent

Install

git clone https://github.com/vblearnstowritecode/worktrace-mcp.git
cd worktrace-mcp
python -m venv .venv

Activate the environment:

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Git Bash
source .venv/Scripts/activate

Install:

python -m pip install -e .
copy .env.example .env

Set open_ai_key in .env. Never commit that file.

Record evidence

Launch the desktop recorder:

worktrace-recorder

Or double-click Run WorkTrace Recorder.cmd on Windows.

The current defaults are:

  • capture every 5 minutes

  • ingest every 30 minutes

  • local capture folder: ~/.worktrace/captures/

  • managed artifacts: ~/.worktrace/artifacts/

  • database: ~/.worktrace/worktrace.db

Use Capture Now for an ad-hoc screenshot, optionally add a note, then use Ingest Pending to analyze and index it immediately. Scheduled capture and scheduled ingestion are independent.

Run the MCP server

worktrace-mcp

For stdio clients, configure:

{
  "command": "C:/absolute/path/to/worktrace-mcp/.venv/Scripts/python.exe",
  "args": ["-m", "worktrace.mcp_server"],
  "cwd": "C:/absolute/path/to/worktrace-mcp"
}

With Hermes, run hermes mcp add worktrace and provide the same executable, module arguments, and working directory when prompted. Start a fresh Hermes session after registration so it discovers the tools.

MCP tools

ask_context

Answers one comprehensive historical-context question using hybrid retrieval and grounded synthesis. The server instructs host agents to call it once per user request rather than iterating unnecessarily.

Inputs:

  • question

  • session_id (default: default)

  • max_evidence (1–8)

get_event

Inspects one cited event, including provenance, capture mode, managed artifact path, and SHA-256 integrity status. Host agents are instructed to use it only when provenance or artifact integrity materially matters.

Independent WorkTrace retrieval and live file/Git/process/configuration checks may run in parallel. get_event must wait for citations returned by ask_context.

Architecture boundaries

  • The MCP host launches WorkTrace as a local stdio subprocess.

  • SQLite, retrieval code, pending sidecars, and managed artifacts stay local.

  • Vision, embedding, query-planning, and synthesis requests use OpenAI.

  • WorkTrace owns its constrained planner and grounded synthesis calls; the host agent invokes tools but does not perform WorkTrace retrieval itself.

  • Screenshot/OCR text is treated as untrusted data and never as executable instructions.

Test

python -m unittest discover -s tests -p "test_*.py" -v

The tests use temporary files and deterministic doubles where possible. Live OpenAI calls are not required by the unit suite.

Status

The MVP includes:

  • manual and periodic desktop capture

  • durable local pending sidecars

  • serialized vision/embedding ingestion

  • SQLite storage and synchronized FTS5

  • semantic + keyword + time-filtered retrieval

  • grounded synthesis with citation validation

  • stdio MCP tools

  • explicit provenance and artifact-integrity checks

Deferred production work includes local image redaction, retention controls, crash recovery, multi-monitor support, automatic session detection, and a measured sqlite-vec evaluation.

License

MIT

Available Tools

2 tools
ask_contextA

Recover missing historical work context with one single comprehensive question.

Use once per user request for prior goals, decisions, attempts, rationale, or activity. The service plans retrieval, searches screenshot-derived evidence, and synthesizes a cited answer. Do not call repeatedly to refine the same question; use the returned answer and inspect live state separately when current truth matters. Run independent live-state tools in parallel with this call when the host supports parallel tool execution.

ParametersJSON Schema
NameRequiredDescriptionDefault
questionYes
session_idNodefault
max_evidenceNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the service plans retrieval, searches screenshot-derived evidence, and synthesizes a cited answer. It does not mention any destructive side effects (likely none) and gives warning about not repeating calls. A bit more detail on potential latency or state impact would improve, but it's solid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two short sentences and a paragraph of usage guidelines. All information is front-loaded, and every sentence adds value. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although there are 3 parameters and no output schema shown, the description provides enough context about what the tool does (searches evidence, synthesizes answer). The presence of an output schema (as per context signals) likely covers return details. The description could mention return format briefly, but it is adequate given the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, meaning no descriptions in the schema. The tool description only implicitly covers the 'question' parameter ('one single comprehensive question') but does not explain 'session_id' or 'max_evidence'. These parameters have defaults but their purpose and effect are not described, hampering correct usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool recovers missing historical work context via a single question. It specifies the resource ('historical work context') and action ('recover'), and distinguishes itself from the sibling tool 'get_event' by focusing on broad context retrieval rather than a specific event.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('once per user request for prior goals, decisions, attempts, rationale, or activity') and when not to ('do not call repeatedly to refine the same question'). Provides clear alternatives: use the returned answer and inspect live state separately, and run parallel tools. This is comprehensive guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_eventA

Inspect one cited event only when provenance or artifact integrity materially matters.

Prefer the answer returned by ask_context. Inspect at most one supporting event per user request unless the user explicitly asks for deeper evidence review.

ParametersJSON Schema
NameRequiredDescriptionDefault
event_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It implies read-only inspection with usage constraints, but doesn't explicitly deny side effects or state idempotency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no wasted words. Perfectly sized for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool, one parameter, and existence of output schema (unseen but noted), the description provides adequate context for appropriate use, though slightly better parameter guidance would raise this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage for the single required parameter event_id. The description does not explain what event_id is or how to obtain it, leaving the agent without guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool inspects a single event when provenance matters, and distinguishes it from the sibling ask_context by specifying preference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to prefer ask_context's answer and limits inspection to one event per request unless deeper review is requested, providing clear when-to-use and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a distinct purpose: ask_context provides a synthesized answer about historical context, while get_event allows inspection of a specific event for provenance. There is no overlap in functionality.

Naming Consistency5/5

Both tools follow a consistent verb_noun naming pattern (ask_context, get_event), making the intent clear and predictable.

Tool Count4/5

Only two tools, which is slightly thin but appropriate for a focused utility that retrieves historical context and inspects events. The tools complement each other well.

Completeness4/5

The tools cover the core workflow of recovering context and verifying evidence. Minor gaps may exist (e.g., no direct search or listing of events), but the surface is sufficient for the stated purpose.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/vblearnstowritecode/worktrace-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server