Agenda MCP Server

Overview

This service exposes a Model Context Protocol (MCP) server that lets agents create and manage scheduled reminders backed by MongoDB. It wraps the agenda job scheduler and publishes several tools through the MCP runtime so that agents can create one-off or recurring jobs, change their snooze duration, cancel them, and inspect the current schedule.

The Docker image is intended to be launched by the MCP host using agenda.mcp.yml, which runs the server over STDIO and wires the required environment variables.

Components

• index.js – boots the MCP server (buddai-agenda) and registers the exposed tools.
• agenda.js – helper module that connects to MongoDB, schedules jobs with Agenda, applies snooze logic, and returns human readable responses.
• reader.js – optional worker that defines runtime handlers for each job found in MongoDB. It logs execution and re-schedules snoozed jobs. Run it alongside the MCP server when you want the reminders to process automatically.
• Dockerfile – multi-stage build that ships a slim Node 22 image running node index.js as a non-root user.

mongo.js and the Jest tests were copied from the notes service and are not used by the agenda server today. They can be ignored or removed once dedicated tests are written.

Exposed MCP tools

Tool	Purpose	Key arguments
createTask	Schedule a new job. Supports cron-like repetition (type: "every") or a single execution (type: "schedule").	interval (cron string or ISO/date string), name (unique job id), rememberText (free text), type (every/schedule, default schedule), snooze (minutes, default 0).
stopSnooze	Stop the current snooze cycle and, for one-off jobs, disable the job entirely.	name
removeTask	Disable an existing job. Behind the scenes it shares the logic with stopSnooze.	name
changeSnooze	Update the snooze duration. If the job is currently snoozed it is re-scheduled relative to “now”.	name, snooze (minutes)
getAllTasks	Return a text list with every job stored in MongoDB.	includeDisabled (boolean, optional)

Snooze behaviour

• A snooze value (minutes) is persisted in job.attrs.data.
• When a job fires, reader.js copies the current nextRunAt into data.nextRunAt and schedules the next alarm snooze minutes ahead. Without reader.js the jobs will still be stored but nothing will drive the snooze loop.
• stopSnooze resets onSnooze and snoozeCounter markers so the job resumes its normal cadence (every) or is disabled (schedule).

Jobs are stored in MongoDB’s agendaJobs collection. Each record contains the Agenda metadata (name, repeatInterval, nextRunAt, etc.) and the custom data object with interval, rememberText, snooze, type, and snooze tracking flags.

Configuration

Environment variables expected by the service:

• MONGO_URI – connection string used by the worker. The runtime replaces the database name buddai with mcp_agenda so you can share credentials with the rest of the stack while isolating data.
• DEFAULT_SNOOZE_MINUTES – passed through by agenda.mcp.yml for future use (currently unused).
• DEBUG – use mcp_agenda:* to see verbose logs from index.js, agenda.js, and reader.js.

Example .env for local development:

MONGO_URI=mongodb://localhost:27017/buddai
DEBUG=mcp_agenda:*
DEFAULT_SNOOZE_MINUTES=5

Ensure the target MongoDB instance allows change streams (replicaSet or Atlas) if you plan to run reader.js.

Running locally

1. Install dependencies with npm install (Node.js ≥ 20 recommended).
2. Start MongoDB and export the environment variables above.
3. Launch the MCP server: node index.js. The server listens on STDIO; when wired into an MCP client it will register the five tools listed earlier.
4. (Optional) In a separate terminal run node reader.js to watch job changes and execute snooze logic.

Docker usage

The provided Dockerfile produces the image expected by the MCP host configuration.

docker build -t buddai/mcp-agenda mcp_servers/agenda

To reproduce the runtime used by agenda.mcp.yml:

docker network create buddai_net          # once per host
docker run --rm --init -i \
  --network buddai_net \
  -e MONGO_URI=mongodb://mongo:27017/buddai \
  -e DEFAULT_SNOOZE_MINUTES=5 \
  -e DEBUG=mcp_agenda:* \
  buddai/mcp-agenda

This will expose the MCP server over STDIO so it can be consumed by the Model Context Protocol host.

MCP host configuration

The host definition at mcp_servers/agenda.mcp.yml wires the Docker command above:

agenda:
  transport: stdio
  command: docker
  args:
    - run
    - --init
    - -i
    - --rm
    - --network
    - buddai_net
    - -e
    - MONGO_URI
    - -e
    - DEFAULT_SNOOZE_MINUTES
    - -e
    - DEBUG
    - buddai/mcp-agenda
  env:
    MONGO_URI: "${MONGO_URI}"
    DEFAULT_SNOOZE_MINUTES: "${AGENDA_DEFAULT_SNOOZE_MINUTES}"
    DEBUG: "*"

Place this block in your MCP host configuration so the host injects the secrets at runtime. Update ${MONGO_URI} and ${AGENDA_DEFAULT_SNOOZE_MINUTES} in the host environment to match your deployment.

Development notes

• Automated tests are currently stale (test.js/test_agenda.js). They reference the notes service and will fail; fresh coverage still needs to be written.
• The service relies on MongoDB change streams for reader.js. If you run against a standalone MongoDB instance without replica set support you will not see snooze rescheduling.
• Use DEBUG=mcp_agenda:* to diagnose scheduling problems. Agenda will log database errors and job lifecycle events.

Troubleshooting

• Jobs never trigger: make sure reader.js is running and MongoDB supports change streams. Also verify the system clock and the interval value (schedule jobs expect a valid date string).
• Database errors: confirm the service user has permission to create the mcp_agenda database and the agendaJobs collection.
• Tool not registered: ensure the host starts the container with the STDIO transport; the MCP server does not expose HTTP endpoints.