Skip to main content
Glama
aadityakushwaha

worklog-mcp

by aadityakushwaha
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

worklog-mcp

An MCP server that gives a coding agent somewhere to write down what it did and why.

Git already records what changed. What it doesn't record is the reasoning — why this approach over the alternative, what was tried and abandoned, what's still broken, which test run was green when the PR went up. That context lives in a chat transcript that nobody reads again.

This server gives the agent six tools to record it as it works. By default it appends JSONL to a file in your repo. Point it at an HTTP endpoint and it posts there instead.

// .mcp.json
{
  "mcpServers": {
    "worklog": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:aadityakushwaha/worklog-mcp"]
    }
  }
}

That's the whole setup. No account, no key, no server. Events land in .worklog/events.jsonl.

Tools

Tool

When the agent calls it

log_work

finished something meaningful — the why and any open loops

record_decision

made an architecturally consequential choice (ADR-style, with alternatives and consequences)

report_test_run

ran a suite — result and counts, not full logs

link_pr

opened or merged a pull request

update_progress

set a work item's status: not_started / in_progress / blocked / done

sync_doc

pushed a plan, spec, progress doc, runbook or research note as rendered markdown

Every event carries a sessionId shared across one agent run and a unique id per event. The agent never passes either — they're threaded automatically, so one run's events can be grouped afterwards and a retried call can be de-duplicated by the receiver.

Related MCP server: logbook-mcp

Configuration

Variable

Default

Meaning

WORKLOG_FILE

.worklog/events.jsonl

Where to append when there's no receiver

WORKLOG_URL

—

If set, POST events here instead of writing a file

WORKLOG_API_KEY

—

Bearer token. Required when WORKLOG_URL is set

Add .worklog/ to .gitignore unless you want the log committed. Some teams do — it makes review of an agent's reasoning part of the PR.

Reading the log

It's JSONL, so the usual tools work:

# what got done, most recent first
jq -r 'select(.tool=="log_work") | "\(.at)  \(.summary)"' .worklog/events.jsonl | tail -20

# every architectural decision, with its alternatives
jq 'select(.tool=="record_decision") | {title, decision, alternatives}' .worklog/events.jsonl

# anything still blocked
jq 'select(.tool=="update_progress" and .status=="blocked")' .worklog/events.jsonl

Sending somewhere else

Set WORKLOG_URL and every event is POSTed to <WORKLOG_URL>/api/agent/events with Authorization: Bearer <WORKLOG_API_KEY>. The body is the event — tool, id, sessionId when known, and the tool's own arguments:

{ "tool": "log_work", "id": "9f2c…", "sessionId": "7a10…", "summary": "…", "intent": "…" }

Answer with:

{ "success": true, "data": { "sessionId": "7a10…", "eventId": "…" } }

The sessionId in the first response is adopted and threaded into every later call, so the receiver owns session identity rather than the client guessing at it. On { "success": false, "error": "…" } or a non-2xx, the tool call returns that error to the agent.

That's the entire contract — a single endpoint. A receiver is an afternoon's work in whatever you already run.

Making it automatic

Logging that depends on the agent remembering to log is logging that stops after a week. Wire it to a Stop hook so it fires at the end of every session:

// .claude/settings.json
{
  "hooks": {
    "Stop": [{ "matcher": "", "hooks": [{ "type": "command",
      "command": "echo 'Before finishing: call log_work with what you did and why.'" }] }]
  }
}

Development

npm install
npm run build   # tsc → dist/  (dist is committed so npx needs no build step)
npm test

Licence

MIT

Available Tools

6 tools
log_workA

Log a unit of work when you finish something meaningful. Capture the WHY and any open loops — git already has the diff.

ParametersJSON Schema
NameRequiredDescriptionDefault
intentNowhy it was done
summaryYeswhat was done (one line)
commitShaNo
filesTouchedNo

TDQS

A3.7/5.0
Behavior3/5

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

Adds useful context beyond annotations (none provided): 'git already has the diff' implies the tool is for metadata/context, not code changes. However, it doesn't disclose whether this is a persistent write operation, auth requirements, or what happens on invocation. Since annotations are absent, the description carries the burden and only partially fulfills it.

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 concise, front-loaded sentences. Every word earns its place, delivering the core purpose and a key design philosophy without fluff.

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

Completeness3/5

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

For a simple logging tool with no output schema, the description gives the essential purpose and mindset but omits parameter details (especially commitSha and filesTouched) and any behavioral specifics. It's minimally viable but leaves gaps for optional parameters.

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

Parameters3/5

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

Schema coverage is 50% (intent and summary have descriptions; commitSha and filesTouched do not). The description adds guidance by stating to capture the WHY (intent) and open loops (likely in summary), and 'git already has the diff' hints that diff-related fields (commitSha/filesTouched) may be redundant. But it doesn't explain the un-documented parameters explicitly.

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

Purpose4/5

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

The description clearly identifies the action ('Log a unit of work') and the resource (a unit of work), with context ('when you finish something meaningful'). It doesn't explicitly differentiate from siblings like 'update_progress' or 'record_decision', but the resource and phrasing are distinct enough.

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

Usage Guidelines4/5

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

Provides a clear usage context: use when you finish something meaningful. However, it doesn't mention alternatives or exclusions, such as when to use 'update_progress' or 'record_decision' instead.

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

record_decisionA

Record an architecturally consequential decision (ADR-style). Only call when a real choice was made.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYes
contextNo
decisionYesthe decision taken
alternativesNo
consequencesNo
supersedesIdNoid of a prior decision this replaces

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains what the tool does but does not describe side effects, return values, idempotency, or how supersedesId affects existing decisions. This is a significant gap for a decision-recording tool.

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 a single sentence with no fluff, front-loading the core purpose and a usage condition. Every word earns its place.

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

Completeness2/5

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

Given 6 parameters, no output schema, and no annotations, a one-sentence description is insufficient. It omits details about the ADR format, expected field contents, and the supersede mechanism, leaving the agent to infer too much.

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 description coverage is only 33%, and the tool description adds no parameter information. The schema describes 'decision' and 'supersedesId' but leaves title, context, alternatives, and consequences undocumented. The description does not compensate for this low coverage.

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 uses a specific verb+resource ('Record an architecturally consequential decision (ADR-style)') that clearly distinguishes it from sibling tools like log_work or link_pr. The qualifier 'architecturally consequential' adds precision about the intended scope.

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

Usage Guidelines4/5

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

The description explicitly states 'Only call when a real choice was made', providing a clear condition for when to use the tool. However, it does not mention alternatives or when not to use it, so it falls short of full when/when-not guidance.

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

report_test_runB

Report the outcome of a test/verify run (counts, not full logs).

ParametersJSON Schema
NameRequiredDescriptionDefault
suiteNo
failedNo
passedNo
resultYes
skippedNo
durationMsNo
failureSummaryNoshort summary if failed

TDQS

B3/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the disclosure burden. It adds 'counts, not full logs,' which clarifies the output type, but it omits whether the tool mutates state, requires permissions, or returns confirmation. The tool appears to be a reporting action but side effects are not described.

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 a single, focused sentence that front-loads the purpose and adds one clarifying parenthetical. No wasted words.

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

Completeness2/5

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

With 7 parameters, no output schema, and no annotations, the description is too sparse. It doesn't explain parameter relationships, required fields beyond the schema, or what the tool returns. The parenthetical about counts helps but is insufficient for complete operational guidance.

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?

Only 14% of parameters have schema descriptions, and the description does not elaborate on individual parameters. It hints that passed/failed/skipped are counts, but doesn't explain suite, durationMs, or failureSummary beyond what parameter names imply. The schema's enum for result is clear, but no additional meaning is added.

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

Purpose4/5

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

The description clearly states the tool reports test/verify outcomes and restricts scope to counts rather than logs. This distinguishes it from sibling tools like log_work, though it doesn't explicitly name alternatives. The verb 'Report' and resource 'outcome of a test/verify run' are specific.

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

Usage Guidelines3/5

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

The description implies usage when a test/verify run has completed and you need to submit its outcome. It does not explicitly state when to use this tool over alternatives like log_work or update_progress, nor any exclusions.

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

sync_docA

Sync a long-form project document (plan/spec/progress/runbook/research) as rendered markdown. Upserts by (kind, key); the version bumps each sync. Use for docs an agent maintains in-repo, so the log carries their current state.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesstable slug within the kind, e.g. the doc filename
bodyYesthe rendered markdown body
kindYes
titleYes
statusNokind-specific, e.g. draft|approved|building|done

TDQS

A4/5.0
Behavior3/5

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

With no annotations provided, the description carries the full transparency burden. It does reveal non-obvious behavior: upsert semantics by (kind, key) and version bumping per sync, plus the markdown format. However, it does not disclose overwrite/retention details, required permissions, or side effects beyond versioning.

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?

Three tightly written sentences: front-loaded verb/resource, immediately followed by identity/version semantics and a clear use case. Every clause earns its place without repetition or fluff.

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?

For a 5-parameter tool with no output schema, the description adequately covers purpose, identity, version behavior, doc kinds, and intended usage. It is slightly light on return value/response behavior and explicit differentiation from siblings, but it is sufficient for correct tool selection and invocation.

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

Parameters3/5

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

Schema description coverage is 60%, so the description adds some value. It clarifies that kind+key form the identity ('Upserts by (kind, key)'), and 'rendered markdown' explains the body format. Yet title and status are not semantically elaborated, and the enum values are already in the schema.

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 uses a specific verb ('Sync') and identifies the resource ('long-form project document') with enumerations of doc kinds (plan/spec/progress/runbook/research). It also distinguishes from sibling tools by noting 'docs an agent maintains in-repo', clearly separating this from logging or progress-update tools.

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

Usage Guidelines4/5

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

It explicitly states when to use the tool: 'Use for docs an agent maintains in-repo, so the log carries their current state.' This gives clear context, but it does not name alternative tools or provide explicit when-not-to-use guidance, keeping it just below a 5.

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

update_progressB

Upsert the current status of a work item (feature/task). Overwrites the item's status; also records the change.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusYes
summaryNo
blockersNo
nextStepsNo
workItemKeyNostable key for the work item; defaults to the session

TDQS

B3.2/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses that the operation overwrites the existing status and records the change, which is useful. However, it does not mention idempotency, reversibility, permission requirements, or behavior when the work item does not exist (despite the 'upsert' implication).

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 two sentences, immediately states the core purpose, and adds a critical behavioral note about overwriting and recording. It wastes no words and is well-structured for quick comprehension.

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

Completeness2/5

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

The tool has 5 parameters, is a mutation, lacks annotations and output schema, yet the description does not explain return values, error cases, or the meaning of several parameters. The 'upsert' semantics and defaulting of workItemKey to the session are only hinted in the schema, not described. For a write operation, this is insufficient.

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 description coverage is only 20% (only workItemKey has a description). The tool description adds minimal parameter meaning beyond the schema: it clarifies 'status' as the main thing being updated, but leaves 'summary', 'blockers', and 'nextSteps' without semantic explanation. Since schema coverage is low, the description should compensate, but it does not.

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

Purpose4/5

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

The description clearly states the tool's purpose with a specific verb ('Upsert') and resource ('current status of a work item'), and clarifies it overwrites status and records the change. It is distinct enough from siblings like 'log_work' or 'record_decision' because it focuses on status updates, though it does not explicitly name alternatives.

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

Usage Guidelines3/5

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

The description implies usage for updating a work item's status, but it does not explicitly state when to use it versus alternatives, nor does it provide exclusions or prerequisites. The sibling tools are not referenced, so the agent must infer the tool's niche from its name and description.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.1.0
    • First observedlink_pr
    • First observedlog_work
    • First observedrecord_decision
    • First observedreport_test_run
    • First observedsync_doc
    • First observedupdate_progress
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation4/5

Most tools target distinct actions (logging work, recording decisions, reporting test runs, linking PRs, updating progress, syncing docs). However, log_work and update_progress could be confused since both deal with work item status, though descriptions help clarify boundaries.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (log_work, record_decision, report_test_run, link_pr, update_progress, sync_doc). The naming is predictable and uniform, making it easy to infer function from name.

Tool Count5/5

With 6 tools, the set is well-scoped for a worklog server. Each tool covers a distinct aspect of work logging without redundancy or excessive granularity, fitting comfortably within the ideal 3-15 range.

Completeness2/5

The tool set is heavily write-oriented (log, record, report, link, update, sync) but lacks any retrieval or query tools. There is no way to read/list/export the work log, which is a significant gap for a server whose purpose is to capture work history. This will likely cause agent failures when attempting to review or summarize logged work.

Maintenance

ActivityMaintained
ResponsivenessNo issues

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

  • roo-activity-logger

    annenpolka
    A
    license
    A
    quality
    C
    maintenance
    MCP server that automatically logs AI coding assistant activities such as command executions and code generation, saving them as JSON files for later search and analysis.
    3
    25
    MIT

  • logbook-mcp

    aether-technologies
    A
    license
    Not graded
    quality
    D
    maintenance
    A local MCP server for AI agents to log activities, query logs, and leave notes for each other, featuring a web UI and REST API.
    MIT

  • Claude Session Logger

    goosefly99
    A
    license
    Not graded
    quality
    F
    maintenance
    A local MCP server that records completed tasks to daily JSONL files and promotes substantial work to a cumulative weekly Markdown worklog, providing persistent, searchable logs of AI-assisted productivity.
    MIT

  • AIS Revizor

    bswvladimir-beep
    F
    license
    Not graded
    quality
    C
    maintenance
    A local-first MCP server that gives AI coding agents runtime visibility and AI-managed debug logging. It replaces blind print() debugging by turning runtime execution into causal chains, allowing agents to instantly locate bugs by finding missing .success events in Python and TypeScript code. Single binary with MCP, CLI, and HTTP interfaces.
    -

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/aadityakushwaha/worklog-mcp'

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